Clarity Human Services: November 2023 Feature Updates

Most of this month's updates focus on the ability to edit referral dates.

Release Schedule: 

• All Training Sites: Monday, October 30, 2023

• All Production Sites: Monday, November 13, 2023

Highlights of this month’s updates:

• The main focus of this release is the ability to edit referral dates:
  • The first section of this article explains this new functionality.
  • The next section of the article describes the aspects of this update that apply specifically to the INVENTORY module.
• Additional updates not related to modifiable referral dates include the following:
  • DIT Update for the 2024 XML Specs
  • Ability to access the Edit/Delete icons on the Client Search page via keystrokes

New: Modifiable Referral Dates  

Overview: This update provides the ability to edit referral dates and to filter the Community Queue by date. Additional functionality has been added with respect to future-dated referrals. 

Editing Referral Dates

• When referring directly to a program:
  • The REFER TO PROGRAM page has a new Referral Date field that is editable.
    
    
    
    
  • Required Access Role permission:
    • Refer to Program

• • If the Would you like to make Reservation as well? toggle is enabled, the reservation’s Start Date will be set to the Referral Date, but can be edited.
    
    
    
    

• When referring directly to a Community Queue:
  • The REFERRAL: ADD TO CQ page has a new Referral Date field that is editable.
    
    
    
    
  • Required Access Role permissions:
    • Create Referral and Refer Directly to Community Queue

• When reassigning a referral from a Community Queue:
  • The REASSIGN section has a new Reassignment Date field that is editable.
    
    

• • To appear in the Program list, programs must have “Yes” selected for Project Receives CE Referrals (receives_ce_referrals) as of the Reassignment Date.

• When editing a referral on the REFERRALS tabs:
  • On the REFERRAL: EDIT and REFERRAL: ASSIGN pages, the existing Referred Date field is now editable.
    
    
    
  • Required Access Role permission:
    • Edit Agency Referral or Edit Any Agency Referral
    • The referral record must be available for the user according to sharing settings
           

• The default date for these editable referral date fields is the current date.
• Users will not be able to save a referral date that is not logical.
  • For example, if a referral was sent to a Community Queue on November 1, 2023, users will not be able to set the Reassignment Date for any date before November 1, 2023.
• If a referral expires on a certain date (due to the Inactive Referral Expiration Threshold for referrals from the Community Queue, or the Direct Referral Expiration Threshold for direct referrals), the system will not allow the referral date to be changed to a date that is after that expiration date.
• If a user enters a past date when creating or reassigning a referral, an event record is created on the current date with “client_events.date” equal to the past date that was entered. 
• Creation of referrals with a past or future date, as well as modification of referral dates, will be captured in the Audit Log.

Community Queue Date Filter

The Community Queue will now include a Date filter that allows users to search for referrals on the queue from the selected date and earlier. So, for example, if a user sets the Date to September 14, the search results will include referrals sent to the queue on or before September 14 that had not been reassigned or otherwise removed from the queue as of September 14. 

The Date filter is set to the current date by default, but can be set to either a past or future date. If the date field is empty, users will see referrals from on or before the current date. 

The default Reassignment Date in the REASSIGN section of a referral will be the same as the date that is entered in the Date filter. Users can select a different date if needed.

If a client is ineligible for a program due to any age-related eligibility requirements based on their age on the selected Reassignment Date, the system will display a pop-up with an OK button saying, “This client will not meet the age requirements of this referral for [Referral Date], and cannot be referred.” 

Functionality Specific to Future-Dated Referrals

Future-dated referrals will be visible on the HISTORY tab and REFERRALS tab as follows:

HISTORY tab	Referral will appear on the HISTORY tab on the date when the referral is created/reassigned.
Direct referral to program	The referral won’t appear in the Pending tab until the Referral Date.
Referral to Community Queue	The referral will be visible on the Community Queue tab if the new Date filter is set to a date on or after the Referral Date.
Reassignment from a Community Queue	The referral will remain on the Community Queue tab and will not move to the Pending tab until the Reassignment Date. Also, the REASSIGN and MOVE TO ANOTHER QUEUE sections of that referral will be hidden.

When future-dated referrals appear on the HISTORY tab and Community Queue tab, they will include the following elements:

• A “Referral scheduled for <date>” label with a tooltip.
  • On the HISTORY tab, the tooltip says, “This client has an upcoming referral to a program dated <date>.”
    
    
  • On the Community Queue tab:
    • The tooltip says, “This client has an upcoming Community Queue referral dated <date>.”
    • The “Referral scheduled for <date>” label will be applied with respect to today’s date. For example:
      • Today is December 14.
      • An upcoming referral with a Reassignment Date of December 21 is on the queue. 
      • A user searching the queue by entering January 14 in the Date field will see the “Referral scheduled for 12/21/23” label on the referral, even though it is in the past with respect to January 14, because the referral is in the future with respect to today’s date (December 14).

• A CANCEL button. 
  
  
  • Any user with access to edit a referral will also have access to cancel a future-dated referral.
  • If a user clicks the CANCEL button, a pop-up appears for the user to confirm the cancellation of the referral to the program (and to the Unit/Bed, if applicable). 
    
    If the user clicks OK, the referral will be deleted from the HISTORY tab and will not be created/reassigned on that future date.
  • Canceling the referral acts the same as deleting that referral (i.e., a canceled referral won’t be recorded as a “Denied” referral because it technically hasn’t happened yet).
  • Reports will distinguish between a deleted referral and a canceled referral.
  • Canceling a referral removes the upcoming referral record from occupancy history. 
• The View link (if sharing permissions allow).
  • The Edit and Delete links will be hidden for future-dated referrals.
    
    

Additional logic for future-dated referrals:

• If a client has a future-dated referral to a Community Queue, the “Client pending on Community Queue” message on the PROGRAM ELIGIBILITY DETERMINATION page will include that future date.  
  
  
  
  
• If a client has a future-dated referral to a program, the system will not display the Program Placement is a result of Referral provided by <referring agency> toggle that would otherwise appear for a program in the PROGRAMS: AVAILABLE section when there is an open referral to that program.
• If a user reassigns a referral on the Community Queue for a future date, users will not be able to create a direct referral to a program that is associated with the future-dated reassignment.
• When a user enters a future date for a referral with only one record in the referral history, the system will delete the existing referral and create a new one. Before deleting the existing referral, the system displays the following pop-up: “Changing the [original date] date of this referral to [future date] will remove the [original date] referral. Please confirm.”

Required Action: Assign Edit Agency Referral (or Edit Any Agency Referral) permission to any staff members who will need access to cancel future-dated referrals.


Updated: Referral Status 

Overview: Before this update, when a user updated the status of a referral, the status would be applied on that date. With this update, the user can set a referral status to be applied to a past or future date.

To achieve this, the Status field on the REFERRAL: EDIT page has been renamed to Current Status, and an Edit icon has been added.

Clicking the Edit icon displays two new fields for applying the new status.

Users can select a New Status of “Pending,” “Pending - in Process,” “Denied,” or “Expired” and select a Status Date as the start date for the selected new status. The date can be in the past, but it must be on or after the date when the referral was created.

The logic for applying a new status is as follows:

• If a user selects “Denied” for the New Status and sends the referral back to the Community Queue:
  • The system will fill the Denied Date field with the selected Status Date.
  • In the Referral History, the system will use the selected Status Date as the Date of the new “Denied: Reassigned to Community Queue” record that is created.
• For referrals created from a denied referral, the Referral Date of the second referral cannot start before the Denied Date of the first referral.
• Users will not be able to create a referral to a Community Queue if there is a future referral status for the client that could lead to the creation of a new CQ referral.

Saving a Future Status

If a user saves a status with a future date, a FUTURE STATUS section appears on the page to display the details of the future status.

Users who have permission to modify referrals will see a CANCEL THE FUTURE STATUS button; after this button is clicked, a green “Entity successfully deleted” banner will appear to confirm the deletion.

The logic for applying a future status is as follows:

• The system will store each future status and its date in a separate table and will check the table once per day for new statuses. If a new status for that day is found, the new status will be applied to the referral, and the associated record in the separate table will be deleted.
• If a referral has a future status, and a user enters a new status (with either a future or past date), the system will delete the previously-entered future status and display the following pop-up:  “By updating this referral status, this will remove the status update scheduled for <date>.” If the new status has a past date, the system will apply the new status as soon as it is saved.
• If a user selects a “Denied/Expired” future status and chooses to send the referral back to the Community Queue:
  • The future CQ referral won’t be created until the status date comes.
  • If the Community Queue has Automated removal from the Community Queue enabled, the system displays the following pop-up: “This future referral will occur regardless of client’s housed status.”

Required Action: None.

INVENTORY-Specific Updates for Modifiable Referral Dates

Updated: Unit Eligibility in Community Queue REASSIGN Section 

Overview: In the REASSIGN section of the Community Queue, the list of eligible Units displayed in the Openings drop-down list will be based on the Units’ current and future Unit Configuration Type (UCT) with respect to the Reassignment Date.



If the selected Reassignment Date is in the past, the system will not allow the user to create a pending occupancy that conflicts with an occupancy between that past date and today.

When the user clicks SAVE CHANGES, the system will display a pop-up message if the client does not meet eligibility criteria for the selected Reassignment Date. Refer to the Community Queue for End Users article for details.

Required Action: None.

New: Unit Queue Date Filter and Eligibility/Occupancy Checks

Overview: The Unit Queue now has a Start Date filter to allow users to view client eligibility according to the Unit Configuration for a specific date (past, current, or future).



When a user clicks ELIGIBILITY or Eligibility Override for a Bed/Unit on the Unit Queue, the system will look at current and future Unit Configuration with respect to the selected Start Date.

Eligibility Determination results will be displayed as follows: 

When a user clicks:	The system displays the following clients:
ELIGIBILITY	Clients eligible on the Start Date and in the future Clients eligible on the Start Date but not in the future
Eligibility Override	Clients eligible on the Start Date and in the future Clients eligible on the Start Date but not in the future Clients not eligible on the Start Date or in the future Clients not eligible on the Start Date but eligible in the future

If there are dates in the future for which a client is not eligible for that Unit/Bed, the system will display an information icon next to the client’s name as shown in the example below. 

Users can hover over the icon to view a tooltip with details of the client’s eligibility.

The icon’s color and tooltip text depend on the client’s eligibility for the Unit/Bed; refer to the Unit Queue for End Users article for details.

If a client with a Community Queue referral scheduled after the current date appears in the eligibility list for a Unit/Bed on the Unit Queue, the display will include the “Referral scheduled for <date>” label and CANCEL button described above.

 If the selected Start Date is in the past, the system will not allow the user to create a pending occupancy that conflicts with an occupancy between that past date and today.

If the selected Start Date is in the future, the system will allow users to create a pending occupancy for a Unit/Bed with a future-dated occupancy (as long as the Start Date for the pending occupancy does not fall within that future-dated occupancy), but will notify users of the need to make adjustments.

Refer to the Unit Queue for End Users article for details on these notifications, as well as the pop-up messages that are displayed when the client does not meet eligibility criteria on the selected Start Date.

Required Action: None.

Updated: Past/Future Dates on Units/Beds Tab 

Overview: On the Units/Beds tab within a client’s program enrollment, users can search for available Units/Beds according to the Unit Configuration on a past or future Start Date. 

A new Eligible for Partial Dates toggle has been added to the ADD UNIT/BED pop-up to allow users to see Units/Beds in the Available Units/Beds list for which the client will not be eligible at some point during the selected date range.

In the Available Units/Beds list, the date on which the client becomes ineligible for the Unit will be displayed after the Unit name. The format will be “Unit Name (<site name>, <building_name>) - Eligible until mm/dd/yyyy.”

Refer to the Eligibility Override article for details on the following:

• The logic for how the Eligibility Override toggle and the Eligible for Partial Dates toggle affect which Units/Beds will be displayed in the  Available Units/Beds list. 
• The pop-up messages that are displayed when the client does not meet eligibility criteria for the selected date range. 

Required Action: None.

Updated: INVENTORY Setup Modifiable Dates  

Overview: A Start Date field is now available in INVENTORY so that users may enter a past or future Start Date at the Site, Building, and Unit Configuration Type level. (The ability to enter a past or future start date at the Unit level was already available.)

• The system will display a pop-up warning in the following situations:
  • A user attempts to enter a Start Date at any level that is earlier than the Start Date of any of the level(s) above.
  • A user attempts to change the Start Date for an existing Site or Building to a date that is later than the Start Date of any level(s) below.
• Additional logic:
  • On the ADD A NEW UNIT page:
    • The Unit Configuration drop-down will be grayed out until a Unit Start Date is selected. 
    • Once the Unit Start Date is selected, the Unit Configuration drop-down list will show Unit Configuration Types that have a Start Date on or before the Unit Start Date.
    • If “Create New Unit Configuration” is selected from the Unit Configuration drop-down list, the Start Date field on the ADD NEW UNIT CONFIGURATION TYPE pop-up will be auto-populated with the Unit Start Date, but can be changed to an earlier date.
  • On the MODIFY UNIT page:
    • When a user moves a Unit Configuration Type to a Unit’s Upcoming Configurations section, the As Of Date on the ASSIGN UNIT CONFIGURATION pop-up must be on or after the Unit Start Date.
    • The Start Date of a Unit Configuration Type in a Unit’s Current Configuration section or Upcoming Configurations section can’t be changed. 
  • On the ELIGIBILITY page for a Site, Building, Funding Source, etc.:
    • The system will display the following pop-up warning whenever an eligibility criterion is added or edited: "Please note that modifying eligibility may impact clients already associated with this [site/building/funding source/program/etc] eligibility setting. Please confirm."
      
      

The Start Date will be recorded in all relevant audit logs.

For existing Sites/Buildings/Unit Configuration Types (UCTs), the system will check the Unit Start Date of any Units associated with the Site/Building/UCT, and fill the Start Date as follows:

In this situation:	The Start Date of Sites/Buildings/UCTs that existed prior to this update will be set to:
All Units associated with the Site/Building/UCT have a Unit Start Date that is after the date when the Site/Building/UCT was created	The date when the Site/Building/UCT was created
At least one Unit associated with the Site/Building/UCT has a Unit Start Date that is before the date when the Site/Building/UCT was created	The Unit Start Date

Required Action: None.

Updated: Warnings When Clients Are Not Eligible for Upcoming Unit Configuration 

Overview: This update concerns situations where a client will no longer be eligible for a Unit they are currently occupying because of an upcoming change to the Unit Configuration Type (UCT).

• When a user tries to assign a UCT to the Upcoming Configurations list for a Unit with an active occupancy that doesn’t meet the upcoming UCT’s eligibility criteria, the text of the pop-up warning is being updated from:

“This upcoming unit configuration conflicts with unit occupancy(ies) within the assignment period. Please confirm unit configuration assignment.”

to:

“Clients currently within this unit may no longer meet the eligibility requirements. Please make any necessary adjustments.”

• If the upcoming UCT was added to the Unit before the Unit was occupied, the system will check the eligibility when the UCT moves from an Upcoming Configuration to the Current Configuration. If at least one client occupying the Unit is not eligible for the upcoming UCT, the system will send the following email notification to the program assigned staff and the user who placed the client in the Unit:

"This client [hyperlink to client’s program Unit page] is currently within a unit where they no longer meet eligibility requirements due to a unit configuration change. Please review and update as appropriate."

Required Action: None.

New: Date Filter on INVENTORY Dashboard 

Overview: This update to the INVENTORY dashboard provides the ability to see what the occupancy status of the displayed Units will be on a specific date.

This function is provided by the As of filter that is accessed by clicking the filter icon in the upper right corner of the dashboard to display the Filters panel.

When a user selects a date for the As Of filter, all Units (except the ones that are hidden by other filters) will be listed on the left side of the screen, and their availability badge will indicate the occupancy status for the As of date. Additionally, if the Unit/Bed is currently occupied (regardless of whether the As of date is during or after the occupancy), the system will display the end date of the occupancy.

For example, consider a Unit that is occupied from October 11 until November 6. If today’s date is October 26:

• Example 1: A user looks at the INVENTORY dashboard today without selecting a date for the As of filter.
  
  The system will display an Occupied badge for that Unit, because the Unit is occupied today.
  
  

• Example 2: A user looks at the INVENTORY dashboard today and selects an As of date of December 1.
  
  

The system will display an Available badge for the Unit, because the Unit will be available on December 1. The end date of the current occupation is displayed beneath the badge.

An additional new feature for this update is that, when any of the filters in the Filters panel are selected, a badge will appear on the filter icon to indicate the number of filters that have been selected. This feature serves as a visual cue for users who have closed the Filters panel and might not remember that filters have been applied.

Required Action: None.

Additional Updates Not Related to Modifiable Referral Dates

 

Updated: DIT Update for 2024 XML Specs

Overview: The Data Import Tool (DIT) has been updated to process Clarity XML containing the FY2024 HUD HMIS Data Standard data elements (excluding project-level data elements which must be mapped, as before). The FY2022 HUD HMIS Data Standards compliant DIT upload capability has been removed.

Required Action: None.

Updated: Visibility of Edit/Delete Icons on the Client Search Page 

Overview: This update addresses the ability to access the Edit/Delete icons in Clarity Human Services, which appeared when users hover their mouse cursor over the item to be edited/deleted. With this update, the Edit/Delete icons on the Client Search page will be displayed without the need to hover over them, so that users of assistive screen-reading devices can use keyboard strokes to access the icons. 

Required Action: None.

Updated: User Access After Password/Access Role Changes

Overview: This release includes the following updates concerning a user’s ability to access the system:

• If, while a user is logged in, there is a change to their primary agency or their access role (either for their main role or for their role in an additional agency), the system will log the user out.
• When a user’s password is changed (either by the user or by a system administrator), the end user’s previous “session identifiers” (the unique numbers assigned by the server for the duration of the user’s session) are all made invalid.
  • Users who change their own passwords in their ACCOUNT SETTINGS will not be logged out of their current session.
• When a user resets their password using the FORGOT PASSWORD function, the system will log the user out wherever they are currently logged in. 

Required Action: None.

Updated: Referral History Type Adjustment

Overview: The details in the HISTORY section for referrals that are reassigned from a Community Queue are being updated as follows: 

Type of reassignment	How it will appear in the HISTORY section
Reassigned to a program (but not to a Unit/Bed)	Program Referral: <program_name>,  <agency_name>
Reassigned to a program and a Unit	Program Referral:  <unit_name>,  <program_name>,  <agency_name>
Reassigned to a program and a Bed within a Unit	Program Referral:  <bed_name>,  <unit_name>,  <program_name>,  <agency_name>

Required Action: None.

Updated: Duplicate {SIGNATURE} Fields Check 

Overview: For multiple signature boxes to function properly within a User Policy, Client Form, or Release of Information (ROI), each signature box must be a unique element ({$SIGNATURES.0}, {$SIGNATURES.1}, {$SIGNATURES.2}, etc.). To achieve this, the system automatically assigns a unique number to the element each time a user clicks the Signature button to add a signature box.

However, if duplicate signature fields such as those shown below are created by copying and pasting, or by manually editing the number to create a duplicate, the User Policy/Client Form/ROI will not function properly.

With this update, the system will not allow a User Policy/Client Form/ROI to be saved if it contains any duplicate signature boxes.

Also, this update will correct any existing User Policies/Client Forms/ROIs that have duplicate signature boxes.

Required Action: None.

Updated: Screen Update Logic

Overview: If a user clicks SAVE in the following places without actually making any changes, the system will not display the green "Changes successfully saved" banner, will not record the action in the Audit Log, and will not update the last_updated and ref_user_updated fields:

• Modifying a client assessment
• EDIT CLIENT LOCATION page
• EDIT FIELD INTERACTION page
• MODIFY FILE page
• EDIT CONTACT page
• LOCATION & OUTREACH SETTINGS page
• EDIT FILTER CRITERION page
• EDIT PROCESSOR page
• EDIT SUBTOTAL page
• EDIT POINT page
• EDIT CONDITION page
• EDIT ELIGIBILITY PRESET page
• EDIT LOCATION FILTER page
• EDIT NAVIGATION PROFILE page*

*This page does not yet have an Audit Log.

Required Action: None.

December Feature Preview   

The December release will include the ability to include a referral to a Unit/Bed when making a direct referral to a program, and the ability to enable or disable INVENTORY at the program level.

We Welcome Your Ideas

We encourage you to suggest improvements and new features for our products. You can create feature suggestions or vote, watch, and comment on existing suggestions at ideas.bitfocus.com. Refer to our Feature Suggestions article for additional details.  

New and Updated Help Center Content

 We’ve either updated or created the following articles in response to this Clarity Human Services update. 

Updated Pages	New Pages
The Global Referrals Tab Overview
Direct Referrals from the Client Referrals Tab
Direct Referrals from the Assessments Tab
Community Queue for End Users
Referral Details Glossary
Referrals: The Pending Tab
Referral Connections
Updating the Status of a Referral
Viewing a Referral’s History
The History Tab
Eligibility Override
Unit Queue for End Users
The Units/Beds Tab
INVENTORY: Sites
INVENTORY: Buildings
INVENTORY: Unit Configuration Type
INVENTORY: Units
Changing Unit Configuration Types
System Notifications
INVENTORY Dashboard
Completing an Assessment in the Client Record
How Do I Search for a Client?
Location Tab Overview
Working with Files in the Client Record
Client Contact Tab
Staff Member Administration
Accessing Clarity Human Services
System Advanced Options: Location & Outreach
Configuring Location Filters
System Advanced Options: Assessment Processors
System Advanced Options: Eligibility Preset Settings
System Advanced Options: Navigation Profiles
System Advanced Options: User Policy Enforcement
System Advanced Options: Client Forms
System Advanced Options: Release of Information (ROI)
Creating and Managing Program Enrollments

Updated: 11/1/2023