Upgrade Guide
When upgrading from the Janus 2020-04 version to the 2022-10 version, there are several changes that must be made. This section aims to document in detail the steps that must be taken to upgrade to the 2022-10 version.
1) The Session Endpoint
Beginning with the 2022-10 version, the Janus API introduced improved session management through the use of several Session endpoints. Sessions logically group related Janus resources, tying together the Janus lifecycle into a single Assessment per session. Sessions are a requirement in this version of Janus, and must be created prior to making any other request to the API using the “POST Session” endpoint.
For details on how to set up a Session request, view the section linked below.
→ See: Session Endpoints
2) Templates and Resources
Introduced in the 2022-10 API version are Resources. Resources are the created instances of a Template. For example, whenever an Enrichment is generated, a PDF report (Resource) is created using a specific Template chosen through the use of an EnrichmentID. Therefore, for each Resource created within a session, a unique ResourceID is generated for that specific instance. This will be used in multiple places in the 2022-10 API, including request URLs, response bodies, and events.
3) URL Changes
The URLs for the Evaluate and Enrichment endpoints, as well as the URLs used to fetch Enrichment results, have changed in the 2022-10 version of Janus. See the list of old and new URLs below.
Evaluate
| Old | https://services.mhs.com/JANUS/2020-04/Evaluate |
| New | https://services.mhs.com/JANUS/2022-10/sessions/{sessionID}/evaluators |
Enrichment
| Old | https://services.mhs.com/JANUS/2020-04/Enrichment |
| New | https://services.mhs.com/JANUS/2022-10/sessions/{sessionID}/enrichments |
Retrieve Enrichment
| Old | https://services.mhs.com/Janus/2020-07/measures/{measureID}/sessions/{sessionID}/enrichments/{enrichmentID}?format={format} |
| New | https://services.mhs.com/JANUS/2022-10/sessions/{sessionID}/enrichments/{enrichmentID}/instances/{enrichmentResultsID}?measureID={measureID}&format={format} |
These URL changes are also described in the API schema:
→ See: Create Evaluate Schema
→ See: Create Enrichment Schema
→ See: Get Enrichment Schema
4) Schema Changes
Both the Evaluate and Enrichment endpoints have schema changes to the request and response JSON:
Firstly, all request and response properties are now in Camel Case (ex. measureID) rather than Pascal Case (ex. MeasureID).
Secondly, many of the properties in the request are now contained in an array, called “evaluations” in the case of the Evaluate endpoint and “enrichmentResults” in the case of the Enrichment endpoint. This array will allow for a future update, where multiple evaluations/enrichments may be generated from a single request (this functionality is currently not available, only the first item in the array will be processed).
Thirdly, some properties have undergone name changes. These are:
| Old Name | New Name | Affected Endpoints |
|---|---|---|
| SourceData | observationItemSets | Evaluate, Enrichment |
| Scales | outcomeItemSets | Evaluate, Enrichment |
| ID | outcomeSetID | Evaluate, Enrichment |
Lastly, some properties within the request and response have moved, and several new properties have been added. Please refer to the Evaluate and Enrichment endpoint sections for more details.
→ See: Evaluate Endpoints
→ See: Enrichment Endpoints
5) Events and Webhooks
While events were included in the 2020-04 version of Janus, they were introduced later in the version’s life and may not be implemented. Events play a crucial role in the Janus lifecycle, notifying the calling system when specific processes complete (for example, an enrichment has generated successfully or a data gatherer has been completed by a rater). Implementation of a webhook to receive events is highly recommended.
→ See: Events
6) Data Gatherers
The 2022-10 version of Janus introduced a Data Gatherer service built as a web application that works alongside the API. Upon making the Data Gatherer API request, a URL will be returned. This URL points to a standalone web application integrated with Janus, where a Rater can take the chosen assessment. Upon completion, an event will be sent to the caller’s webhook notifying them that the assessment has been completed. At this point, the resulting Observation Item Sets can be retrieved. By using this Data Gatherer, the Observation Item Sets will be assembled and ready for the subsequent Evaluate call, and the calling system does not need to have a Data Gatherer built into it.
→ See: Data Gatherer Endpoints
7) Enrichment Transformer (Optional)
Also introduced in the 2022-10 version is the Enrichment Transformer endpoint. This endpoint introduced multi-session enrichments, such as comparative CSV reports between multiple raters/respondents, or progress reports for looking at the same respondent over time. The types of reports available are dependent on the specific measure.