Clarity Human Services Operational API Early Access Program Info and FAQs

Explore a pre-release version of Operational API in Clarity Human Services through our Early Access Program (EAP).

We are excited to be nearing the release of our new Operational API in Clarity Human Services. Although still under active development, we invite you to explore a pre-release version through our Early Access Program (EAP). The EAP lets customers preview planned or future development efforts for existing or new Clarity Human Services product features or services. 

The purpose of this page is to: 

• help customers decide if the Operational API is right for their intended project,
• describe the Operational API Early Access Program, and to 
• provide general API capabilities information as a basis for writing a community use case.

Table of Contents:

What can you do with the Operational API (GraphQL specification)

What You Can Do with Data Analytics API (aka Looker) with REST specification

Comparison of Operational API with other existing Clarity features

When to use the Data Analysis/(aka Looker) APIs versus the Operational API

How to Sign Up for the Operational API Early Access Program

Important EAP Considerations

FAQs

What can you do with the Operational API (GraphQL specification)

1. Ability to query, modify, add and delete
   1. Clients - HMIS Universal Data Elements (UDEs)
   2. Households: both Profile (aka“Global”) and HMIS/Enrollment-level Households
   3. Enrollments
   4. Files: Client level Files (also can be attached to an ROI)
   5. Releases Of Information (ROI)
   6. Services (enrollment-level services only)
   7. Assessment responses: Client-level data, including custom and/or enrollment-level Assessments (the Assessment itself cannot be created with the API)
   8. Notes: Enrollment-level client notes (not client-level Notes outside an enrollment)
2. Ability to query
   1. Projects (limited Project information, see GraphQL schema)
   2. Picklist values (if you know the name of the picklist from the Field Editor in Clarity Human Services
3. There are no push notifications or “publish-subscribe” functionality yet.  All updates are currently obtained by polling.

What You Can Do with Data Analytics API (aka Looker) with REST specification

• Query (read-only) all client records stored in Clarity
• Access fresh data at most every two hours, currently
• see https://help.bitfocus.com/looker-api-introduction-and-resources for more details

Comparison of Operational API with other existing Clarity features

Compared the existing DIT XML import, HUDX-111 Pentaho reports, and existing Data Analysis/(aka Looker) APIs, the Operational API possesses these new capabilities:

• Read and search for real-time Clarity data
  Data Analysis/(aka Looker) APIs have specified refresh intervals of at least two hours, but GraphQL communicates with Clarity Human Services in real-time. The HUDX-111 Pentaho report is not API accessible, but it does read real-time Clarity data, unlike Data Analysis/(aka Looker) APIs.
  
  
• Delete or edit non-HMIS Data Standard and custom records
  With DIT CSV (manual only), and with the DIT XML API (manual as well), HMIS Data Standard elements can be deleted. However, non-HMIS Data Standard and custom records can not be deleted. Client record updates, even for non-HMIS and custom data elements, are not quite as powerful with the DIT as it is for the Operational API. Updating in the DIT requires a newer record to be imported for the update to take effect.  However, with the Operational API, record editing can modify an older record in place (directly by record ID), without requiring a new record to be added.
  
  
• Create, delete, or edit more types of Clarity-specific data elements
  • Profile Households and Profile Household memberships (as opposed to enrollment-level households)
  • Program-level Notes
  • Releases Of Information (ROIs) with file attachments

The only other way to access the above elements is manually via the Clarity web interface.

• Granular, not bulk, operations
  With the Operational API, the focus is on quick changes or additions to just a small set of records, as it is designed for quick interactions. The DIT is designed for bulk, periodic updates.

When to use the Data Analysis/(aka Looker) APIs versus the Operational API

The Data Analysis/(aka Looker) APIs are appropriate for: 

• Applications where customers are only reading data (for example, for a report or dashboard), and not modifying data. The refresh rates of the Data Analysis API are listed at https://help.bitfocus.com/data-refresh-rate. 
• Large, complex queries (read-only).

The Operational API may be appropriate for:

• Small, quick queries where the overall purpose is to update or add data.
• Situations where a customer needs a faster refresh rate.
  

The use case discussion within the Early Access Program application steps will help to decide whether to use Data Analysis/(aka Looker) APIs versus the Operational API.

How to Sign Up for the Operational API Early Access Program

Here are the steps to sign up:

1. Use the API capabilities described on this page to write an application use case. Please keep it simple and high-level; there is no need for much detail at this point.
2. Meet with your BFF or Community Admin lead to review your use case. We will evaluate your use case to ensure the Operational API is the best tool to use, and to make sure it doesn’t violate Bitfocus usage policies.
3. Review and accept program terms as detailed in the EAP agreement (participation in the EAP is voluntary and comes with inherent risk. By participating, you acknowledge and assume these risks.)
4. Identify a representative who has professional API programming experience with basic GraphQL familiarity. We will work with this person to achieve user authentication and a successful read-only (non-data changing) request. Additional  support beyond these milestones requires an additional paid support package.
5. Approach your use case with caution. The Operational API and data integration in general allow for the alteration of many records very quickly. We strongly recommend taking an iterative approach by starting small and testing thoroughly as you proceed with your integration.
6. Active participation -- give us feedback! 
7. Tell us where the gaps are.

Important EAP Considerations

1. You will need someone who can program with web APIs, as we are unable to teach that.
2. Please keep in mind that the EAP specifies “Customer agrees to limit their use of EAP features and services to the use case(s) reviewed with Bitfocus and further agrees to disclose any significant changes to their intended or actual use case(s).”
3. We recommend installing the Operational API on a training Clarity instance, while developing and testing your app. Once your app is vetted by your development process, then the app can be run against a live Clarity instance with the Operational API installed.

FAQs

Q: Why does Bitfocus have to review my use case?

A: Bitfocus needs to review the use case so we can:

1. Help you determine if this is the right tool for the job 
2. Have a common understanding of the use of the API, so that it meets our API and Clarity usage guidelines.
3. Learn what customers want to do with our APIs, regardless of the technical details. This helps us improve the APIs.

Q: Why can’t I have direct access to the Operational API’s GraphQL Schema, before I start writing my use case?

A: The general capabilities of the Operational API are all that are necessary for developing an effective use case. We don’t require close use-case precision to actual API capabilities, and your use case goals may assist us in adding new functionality.