Welcome to the Janison Insights help portal
Integration
Janison uses Microsoft Azure Event Hub & Microsoft Azure Service Bus integration to deliver document workflow state transitions to our clients as third-party consumers.
To read more about these messaging services and the purpose of each one, visit the Microsoft product documentation here.
Clients can receive two categories of messages; document workflow state transitions and test delivery messages.
If event hub and/or service bus is configured, then messages are sent when:
Event Hub and Service Bus need to be configured at the tenant level. This task should be undertaken by experienced admins only. Your Janison account manager will facilitate this configuration.
Navigate to Settings > Tenant Settings and open the Event Settings expandable.
The following configuration settings are an example of how this could look.
Events are identical for Event Hub and Service Bus and are based on test attempt actions and configured workflow transitions. These topics are detailed above.
Service Bus can be used independently or in conjunction with Event Hub and vice versa.
Event Hub is a big data streaming platform and event ingestion service. Read more.
Service Bus is a fully managed enterprise message broker with message queues and publish-subscribe topics. Read more.
Let’s take a closer look at the options available for each category.
You will need to activate these options at the global tenant level.
Navigate to Settings > Workflow definitions.
Select the relevant workflow. In the below example, we’ve selected the Assessment Event Workflow.
For any tenant that has an Event Hub and/or Service Bus connection configured (see below for config), then enabling notifications for a specific workflow transition will trigger a notification to be sent when that workflow transition is triggered.
To enable the options, go into edit mode and make your selections in the Notifications column and Save.
Workflow state transition event messages have the following structure:
{
Id: "54283202-1004-4D32-B730-9F28E4F8C238",
Entity: "AssessmentEvent",
Event: "DocumentStateTransition",
TransitionFrom: "Draft",
TransitionTo: "Delivery",
TransitionName: "Commence Delivery"
}
Property | Description |
---|---|
ID | string (36). System assigned unique identifier of the entity being transitioned |
Entity | string (128). Name of the entity type being transitioned, possible values are defined in workflow definitions (/admin/workflow/index) |
Event | string(64). Will always be ‘DocumentStateTransition ‘ for workflow state transition messages |
TransitionFrom | string(128). Name of the workflow state transition being transitioned from |
TransitionTo | string(128). Name of the workflow state transition being transitioned to |
TransitionName | string(128). Name of the workflow state transition being triggered |
Admins can configure test delivery messages to send notifications at a tenant level.
Navigate to Settings > Tenant Settings.
Open the Event Settings expandable to view the available notifications.
Enable Login Confirmation – If this is enabled, a ‘login’ confirmation will be included in the event message when a user confirms their identity upon login.
Enable Start Confirmation – If this is enabled, a ‘start’ confirmation will be included in the event message when a user enters the main body of a test for the first time.
Enable First Start Confirmation – a message is sent when main body of a test is entered for the first time. Whilst similar to start, this is only sent once per assessment event enrolment.
Enable Submit Confirmation – If this is enabled, a ‘submit’ confirmation will be included in the event message when an attempt is submitted by the user or admin.
Additional Submit Confirmation Items – If added here, item custom attributes can be included in the ‘submit’ confirmation messages when an attempt is submitted by the user or admin.
To be available for the selection, custom attributes need to be linked directly to the item and be one of the following types: boolean, integer, float, string, list, date
Enable Reopen Confirmation – If this is enabled, a ‘reopen’ confirmation will be included in the event message when an attempt is reopened by the user or admin.
Any tenant that has an event hub and/or service bus connection configured will send messages for any configured test player events. See example message payloads below.
{
Id: "54283202-1004-4D32-B730-9F28E4F8C238",
Entity: "TestAttempt",
Event: "Login"
}
Property | Description |
---|---|
Id | string (36). System assigned unique identifier of the test attempt. |
Entity | string(64). Always ‘TestAttempt’ for test delivery messages |
Event | string (64). Type of event being triggered available values Login, Start or Reopen |
{
"Id": "4e96cd9e-2dc8-ed11-a000-ec086b08fe56",
"Entity": "TestAttempt",
"Event": "FirstStart",
"DateStarted": "2023-03-24T00:01:17.0997404Z",
"OrgUnitId": "7cd8f2cd-498d-ec11-991b-acb30ea8de22",
"OrgUnitIdentifier": "oup-organisation-guid",
"GroupId": "7e9065a8-6b40-ee11-b727-00155df53dae",
"AssessmentEventId": "8510459a-a50c-ec11-862c-b38465c83433"
}
Property | Description |
---|---|
Id | string (36). System assigned unique identifier of the test attempt. |
Entity | string(64). Always ‘TestAttempt’ for test delivery messages |
Event | string (64). Type of event being triggered available values FirstStart |
DateStarted | string (28). UTC date string of when attempt was started. |
OrgUnitId | string (36). System assigned unique identifier of the org unit linked to the test attempt. Org unit where attempt is taken. If not set value will be null. |
OrgUnitIdentifier | string (510). User assigned unique identifier of the org unit linked to the test attempt. If not set value will be null. |
GroupId | string (36). Unique identifier of the group linked to the test attempt. Set when attempt is created from a group enrolment. If not set value will be null. |
AssessmentEventId | string (36). Unique identifier of the assessment event linked to the test attempt. |
{
"DateStarted": "2023-07-12T23:26:57.4951063Z",
"DateCompleted": "2023-07-12T23:27:32.4786313Z",
"AnswerScores": [
{
"QuestionId": "58a040cf-880f-ec11-9a18-38baf811fd72",
"Score": 1,
"MaxScore": 1,
"Response": "00101",
"QuestionData": {
"question-no": "1"
}
}
],
"Score": 1,
"MaxScore": 1,
"Id": "a33fe07a-0b21-ee11-b714-f4267980d21f",
"Entity": "TestAttempt",
"Event": "Submit"
}
Property | Description |
---|---|
Id | string (36). System assigned unique identifier of the test attempt. |
Entity | string(64). Always ‘TestAttempt’ for test delivery messages |
Event | string (64). Type of event being triggered available values Login, Start or Reopen |
DateStarted | string (28). UTC date string of when attempt was started. |
DateCompleted | string (28). UTC date string of when attempt was completed. |
Score | double. Sum of answer scores for attempt will be null if the attempt is not fully marked. |
MaxScore | double. Maximum achievable score for the attempt. |
AnswerScores | array of AnswerScore. Array of answer details for all markable main body question in the attempt. |
Property | Description |
---|---|
QuestionId | string (36). System assigned unique identifier of the question linked to the answer. |
Score | double. Score awarded for answer, null if not marked. |
MaxScore | double. Maximum achievable score for the answer. |
Response | string. Users raw answer. Only returned for the following question types:
All other question types return null |
QuestionData | object. An object containing a collection of key value pairs as defined in Additional Submit Confirmation Items. Will return null if no Additional Submit Confirmation Items are configured or if the question contains no data for the configured items. |
The following details will be provided by client manager after being received from the operations team:
Install the Azure.Messaging.ServiceBus NuGet package.
Use the following C# code example to receive messages added to the queue.
using Azure.Messaging.ServiceBus;
using System;
using System.Threading.Tasks;
namespace ServiceBus.Testing
{
internal class Program
{
static async Task Main(string[] args)
{
// Replace with your Service Bus connection string and queue name
string connectionString = "your-connection-string";
string queueName = "your-queue-name";
// Create a ServiceBusClient
ServiceBusClient client = new ServiceBusClient(connectionString);
// Create a ServiceBusReceiver to receive messages
ServiceBusReceiver receiver = client.CreateReceiver(queueName);
Console.WriteLine("Listening for messages...");
try
{
while (true)
{
// Receive a batch of messages (adjust the max messages and max wait time as needed)
var messageBatch = await receiver.ReceiveMessagesAsync(
maxMessages: 10, // Adjust as needed
maxWaitTime: TimeSpan.FromSeconds(60)); // Adjust as needed
foreach (ServiceBusReceivedMessage m in messageBatch)
{
try
{
// Process the message here
Console.WriteLine($"Received message: {m.Body}");
// Complete the message to remove it from the queue
await receiver.CompleteMessageAsync(m);
}
catch (Exception)
{
// Moves message to dead-letter queue if processing fails
// Dead-letter messages can be processed from the dead-letter queue later
// To access messages from the dead-letter queue,
// create a receiver using the ServiceBusOptions.DefaultReceiveMode = ReceiveMode.DeadLetter in the CreateReceiver() method
await receiver.DeadLetterMessageAsync(m);
}
}
}
}
catch (Exception ex)
{
Console.WriteLine($"Error: {ex.Message}");
}
// Remember to manually dispose of the objects when done
await receiver.CloseAsync();
}
}
}
The following details will be provided by client manager after being received from the operations team:
Install the Azure.Messaging.EventHubs NuGet package.
Install the Azure.Messaging.EventHubs.Processor NuGet package.
Install the Azure.Storage.Blobs NuGet package.
Use the following C# code example to receive event added to the hub. To use this code an Azure.Storage account is required to hold checkpoint information.
using Azure.Messaging.EventHubs;
using Azure.Messaging.EventHubs.Consumer;
using Azure.Messaging.EventHubs.Processor;
using Azure.Storage.Blobs;
using System;
using System.Text;
using System.Threading.Tasks;
class Program
{
static async Task Main(string[] args)
{
string eventHubName = "your-event-hub-name";
string connectionString = "your-event-hub-connection-string";
string storageConnectionString = "your-storage-connection-string";
string storageContainerName = "your-storage-container-name";
BlobContainerClient storageClient = new BlobContainerClient(storageConnectionString, storageContainerName);
// Create an event processor client to process events in the event hub using the default consumer group
var processor = new EventProcessorClient(
storageClient,
EventHubConsumerClient.DefaultConsumerGroupName,
connectionString,
eventHubName);
// Register handlers for processing events and handling errors
processor.ProcessEventAsync += ProcessEventHandler;
processor.ProcessErrorAsync += ProcessErrorHandler;
Console.WriteLine("Starting the event processor...");
// Start the processing events will continue to be received until the processor is stopped
await processor.StartProcessingAsync();
Console.WriteLine("Press any key to stop the processor...");
Console.ReadKey();
Console.WriteLine("Stopping the event processor...");
await processor.StopProcessingAsync();
}
private static async Task ProcessEventHandler(ProcessEventArgs eventArgs)
{
try
{
// Perform the application-specific processing for an event
Console.WriteLine("\tReceived event: {0}", Encoding.UTF8.GetString(eventArgs.Data.Body.ToArray()));
// update the checkpoint in the blob storage so that the app receives only new events the next time it's run
await eventArgs.UpdateCheckpointAsync();
}
catch
{
// Handle the exception from handler code
}
}
private static Task ProcessErrorHandler(ProcessErrorEventArgs eventArgs)
{
try
{
// Perform the application-specific processing for an error
Console.WriteLine($"\tPartition '{eventArgs.PartitionId}': an unhandled exception was encountered. This was not expected to happen.");
Console.WriteLine(eventArgs.Exception.Message);
}
catch
{
// Handle the exception from handler code;
}
return Task.CompletedTask;
}
}
1300 857 687 (Australia)
+61 2 6652 9850 (International)
ACN 091 302 975
ABN 35 081 897 494
© 2024 Janison
Janison acknowledges the traditional owners of the land on which we work and meet. We acknowledge the continuous care of the land, animals and waterways. We pay our respects to Elders past, present and emerging.