Executive Summary

The Scantron integration consists of two pieces:

• Eligibility: A “Call External API” Behavior that uses a Template to construct an API call, notifying Scantron of a candidate’s eligibility to test

• Scheduling: An AWS Lambda that receives scheduling information and can store that information in Workflow attributes

This document describes the technical architecture of the integration and the instructions for implementing it.

Setting up the integration takes approximately <TODO>.

Technical summary

Scantron makes a single, nightly API call containing a batch of all members who have completed the Scantron Eligibility process. This endpoint is protected by Basic Authentication and accepts the Candidate Exams payload format.

To support the performance and security requirements of the integration, the following components have been created.

1. AWS Http Gateway - HTTP GATEWAY Receives requests for he scheduling process. Configured to use the LearningBuilder-Basic-Authorizer for security and to call the LearningBuilder-Queue lambda.

2. Simple Queuing Service - SQS Receives messages from the LearningBuilder-Queue lambda. Configured to send messages to the LearningBuilder-Scantron lambda.

3. ScantronConfig - DYNAMODB Stores the configuration data for the scantron process. Uses stages to support multiple clients.

4. LearningBuilder-Basic-Authorizer - LAMBDA UNIVERSAL Extracts a LearningBuilder API Key from the Basic Auth header and confirms it has the rights to complete the process. For Scantron, it needs to be able to call the Perform Workflow Step API and OData.

5. LearningBuilder-Queue - LAMBDA UNIVERSAL Copies the content of the REST call onto a pre-defined SQS queue.

6. LearningBuilder.Scantron - LAMBDA

   1. Parses the batch payload into individual scheduling updates

   2. For each update, calls a series of LearningBuilder API endpoints to perform Workflow Actions¹ that store the scheduling data and, optionally, trigger additional Behaviors

For each scheduling update, the Lambda calls two LearningBuilder APIs:

• OData² - obtains the ActivityInstanceId and WorkflowInstanceId values

• PerformStep/ - Executes a specific Workflow Action. The WorkflowActionId is configured in AWS. (See below)

Configuration Instructions

Step 1: LearningBuilder Authentication Configuration

We are using the built in API Keys to manage security for the feature.

1. Create a new Authorization Rule Set (/SysAdmin/Authorization/Rules) for Scantron.

   1. Determine who needs to be able to run the feature and add the appropriate role. If Scantron does not have an account inside LearningBuilder, you may want to restrict it to System Administrators.

   2. Add the PERFORM_WORKFLOW_STEP permission and add a custom permission called SCANTRON

      Open

      

2. Create a new OData Entity (/SysAdmin/Odata/Entities)

   1. Add view vRPT_LearningPlanInstance to LearningBuilder

   2. Expost vRPT_LearningPlanInstance as a new OData Entity and make it accessible to the SCANTRON permission added in step #1.

      Open

      

3. Create an API Key (/Admin/Profile/ApiKey) for the account that will be used to process scheduling event

   1. Create a Key for the Scantron Authorization Rule Set

       

Step 2: LearningBuilder Workflow Configuration

1. Add Scheduling Attributes to the Learning Plan Workflow Step that is awaiting the Test Results.

Step 3: Configure AWS

3.1: Configure DynamoDb

1. Add Configuration to DynamoDb table ScantronConfig in AWS

   1. Add Stage that uses the client’s Client ID

   2. Add the LearningPlanId and ActionId values. The Perform Step Action needs to know which Learning Plan Definition and Action to use.

   3. Add LbDomain of the LearningBuilder Instance

   4. Add the Attribute Mappings for each Attribute we want to set. The Mappings include the attribute name and the XPath value of where the value is located in the Registration Status Export.

3.2: Configure authentication

1. Confirm that the LearningBuilder-Scantron and LearningBuilder-Basic-Authorizer AWS lambdas have been installed. Production only needs a single instance of both lambdas.

2. Confirm that the LearningBuilder-Scantron-API API Gateway has been installed.

   1. There should be routes defined for Scheduling and Health

   2. Both routes should be protected by the LearningBuilder-Basic-Authorizer AWS lambda as an authorizer

   3. Both routes should be configured to integrate with the LearningBuilder-Scantron AWS lambda

3. Add a Stage to the LearningBuilder-Scantron-API API Gateway that matches the client ID of the LearningBuilder Instance

   1. Add a Stage variable of credential_validator that points to an API for the target LearningBuilder instance.

   2. Enable Automatic Deployment so that the stage always uses the latest version of the lambdas.

Appendix A: Scantron Scheduling Logging

All the Scantron Scheduling Logs are located in CloudWatch. Each component has its own Log Group. AWS lambdas LearningBuilder-Scantron and LearningBuilder-Basic-Authorizer. Each Registration Status Export triggers the following log messages.

1. Scheduling. We store everything that is sent to the endpoint before any processing or analysis occurs. This prevents us from losing any data that is sent to the lambdas.

2. GetWorkflowInstanceId. Using our OData endpoint, we find the Workflow Instance Id for the Learning Plan Instance for the given Unique Id. The Learning Plan Instance must be have a Completion Status of “Incomplete”, belongs to the Learning Plan Definition defined in the DynamoDb Config, and is on the step where the Workflow Action defined in the DynamoDb Config resides.

3. ProcessSchedule. We log the request of the Perform Step API for each record.

4. ProcessResponse. We log the response of the Perform Step API for each record.