What a “Proper” Janus Integration Means
A proper Janus integration aligns directly with the Janus Assessment Lifecycle, treating each phase as a distinct, state-driven interaction rather than a single synchronous workflow. Janus is intentionally asynchronous, event-driven, and resource-oriented. Integrations that perform well respect these design principles rather than attempting to force synchronous, blocking calls.
Janus defines an assessment as the application of a measure to a respondent, progressing through:
Session creation
Data Gathering
Evaluation
Optional Enrichment
Optional Enrichment Transformation
Each phase produces explicit artifacts (Observation Sets, Outcome Sets, Enrichment Results) that become inputs to later phases.
1. Sessions: Establishing the Assessment
What a Session Does:
The Session establishes parameters and general behaviors for the assessment throughout its lifecycle. Typically, one sessions contains one assessment for one person. If a second assessment is needed for the same person, or if two people are taking similar assessments for the same measure, then these are recommended to be separate sessions.
2. Data Gathering: Collecting Respondent Inputs
What Data Gathering Does:
The Data Gathering phase is responsible for collecting respondent input via a provisioned assessment form. This phase produces Observation Item Sets, which are the authoritative inputs for scoring and reporting.
Key behaviors:
A Data Gathering instance is created via the Data Gatherer endpoint.
Janus returns two URLs:
An HTML URL for the rater to complete the assessment.
A JSON URL to retrieve the completed results.
Observation data cannot be retrieved until the assessment is completed.
Partial results are not available.
A well-designed integration:
Treats the Data Gathering URL as a long-lived, user-facing resource.
Stores the returned dataGatheringID and result URL.
Subscribes to events so the system knows when completion occurs rather than polling blindly.
Avoids updating immutable properties once a rater has started the assessment, in accordance with resource state rules.
3. Evaluation: Turning Observations into Outcomes
What Evaluation Does:
The Evaluation phase (sometimes referred to as scoring) transforms Observation Item Sets into Outcome Item Sets. This phase is required for every assessment and represents the point where the measure’s scoring logic is applied.
Key behaviors:
Evaluation consumes Observation Item Sets generated during Data Gathering.
The result is one or more Outcome Item Sets.
Evaluation is an explicit API call and not performed automatically when data gathering completes.
A well-designed integration:
Initiates Evaluation only after Data Gathering completion is confirmed (typically via an event).
Treats Evaluation as asynchronous and waits for completion signals.
Persists Outcome Set identifiers for later enrichment and transformation use.
This separation allows Evaluation to be retried safely if necessary, as long as the same inputs are used.
4. Enrichment: Producing Human-Readable Results
What Enrichment Does:
Enrichment is an optional phase that produces narrative or visual reports (e.g., PDF, DOCX, XLSX) based on the evaluated results.
Key behaviors:
Enrichment consumes Evaluation outputs.
A single Enrichment instance can generate multiple files.
Enrichment Results are addressable resources with their own identifiers.
Enrichment supports event subscriptions so consumers can be notified when reports are ready.
A well-designed integration:
Triggers Enrichment only after Evaluation completion.
Does not assume immediate availability of files.
Uses event notifications to retrieve generated report links rather than aggressive polling.
5. Enrichment Transformer: Producing Comparative and Aggregated Results
What Makes the Enrichment Transformer Different:
The Enrichment Transformer is a specialized enrichment endpoint designed to combine data from multiple sessions into a single output.
Key behaviors:
It accepts a list of “Session Data” objects, each containing Observation and Outcome Item Sets.
It requires control parameters such as measureID, enrichmentID, and directives.
Outputs are links to generated reports (PDF, XLSX, CSV).
Typical use cases include:
Scored datasets
Multi-rater reports
Progress reports.
A well-designed integration:
Treats the Enrichment Transformer as a post-processing stage, not part of an individual assessment.
Collects finalized session outputs over time.
Submits only completed and evaluated session data.
Consumes generated links asynchronously once the transformer completes.
This makes the transformer ideal for longitudinal analysis, comparisons, and bulk reporting rather than single-assessment output.
6. Using Web Events to Drive the Workflow
Janus explicitly supports events as a first-class mechanism for integration orchestration.
Events notify the caller when asynchronous processing completes.
Webhooks are recommended to understand when assessments are completed, evaluations finish, or enrichment results are ready.
An Effective Event Strategy:
Subscribes to events during resource creation.
Uses events to advance lifecycle stages (e.g., Data Gathering → Evaluation).
Treats events as authoritative state changes, not just hints.
This minimizes wasted calls and aligns with Janus’s asynchronous model.
7. Retry and Efficiency Strategies
While Janus documentation does not prescribe retry algorithms, its resource-based and asynchronous design implies safe retry patterns.
Many endpoints return processing links rather than immediate results.
Results may not be immediately available.
Events exist specifically to reduce polling.
Recommended Practices (Architectural Guidance):
Avoid retrying completed lifecycle steps.
Prefer event-driven retries over time-based polling.
Implement exponential backoff when polling is unavoidable.
These practices ensure integrations are efficient without overwhelming Janus endpoints.
Closing Perspective
A proper Janus integration is not just about calling endpoints in the right order—it’s about respecting the lifecycle, embracing asynchrony, and using events as the backbone of orchestration. Teams that follow this model tend to build integrations that are more reliable, more scalable, and easier to extend with advanced capabilities like Enrichment Transformers.