SurpassLocal - Disaster Recovery

This article will detail how to export results from a SurpassLocal server and import them into Surpass Central. If an organisation uses SurpassLocal to deliver tests, there might be a situation where a test centre it delivers tests from cannot communicate with the Surpass Central server. If the candidates responses have not been synchronised back to Surpass Central, then the candidates that have taken tests at this centre will not be able to be certified until this issue has been resolved.

The SurpassLocal API allows an organisation to extract and save encrypted responses, move this information to a location with an active internet connection and upload this using the CMS API. This will ensure that any candidate certification SLA can be met in the case of an emergency. Prior to using this functionality, it would be expected that the following has been attempted to try and synchronise the responses:
  • The user has tried to identify, diagnose, and resolve the issue on the server by inspecting the log files and contacting support, if successful the results would automatically upload to Surpass.
  • The user has found an alternative network connection source that SurpassLocal can utilise to communicate with Surpass central.
If the above cannot be completed or resolved, then the disaster recovery process will allow organisations an alternative route to upload candidate responses.

The Disaster Recovery process is as follows:
  1. A test centre user or system will be setup to be able to extract candidates responses from the SurpassLocal API resource CompletedExamResponseExport. Successful requests will extract all tests that are in a 'Finished' state.
  2. The encrypted data can then be saved, and taken to a secure internet connection away from the SurpassLocal server.
  3. The information can then be uploaded to the CMS API. CMS will send the test responses and data to the relevant Surpass instances and the results will be available on Surpass Central.
Further information about the SurpassLocal API method used to extract result data can be found here.

Uploading result data

To upload result data to Surpass central in the disaster recovery process a user or external system must call the CMS API. The request should be built as follows:

Request URL: POST https://cmspublic.{CMS environment}.com/api/ImportCompletedExams

Authorisation: Basic Authentication encoding the following string: {CMS Username}:{CMS Password}

Required header: content-Type:application/XML | application/JSON

Request Body: The contents of the body should include all of the information inside the "response" collection returned from the SurpassLocal API method: GET CompletedExamResponseExport. Example response has been provided below, the response information has been removed.

    {
      "centreInfo": [
        {
          "reference": "BTLSFTest",
          "instanceInfo": [
            {
              "instanceName": "demo",
              "examInformation": {
                "examSessions": [
                  {
                    "id": 1,
                    "originalId": 4761,
                    "examState": "Finished",
                    "structureXml": "...",
                    "examStateInformation": "",
                    "clientInformation": "..."
                  }
                ],
                "itemResponses": [
                  {
                    "id": 1,
                    "originalExamSessionId": 4761,
                    "itemId": "5016P13641",
                    "itemVersion": 6,
                    "itemResponseData": "...",
                    "markerResponseData": "..."
                  },
                  {
                    "id": 2,
                    "originalExamSessionId": 4761,
                    "itemId": "5016P15739",
                    "itemVersion": 3,
                    "itemResponseData": "...",
                    "markerResponseData": "..."
                  }
                ],
                "examDocuments": [],
                "candidateInteractions": [],
                "examStateChanges": [
                  {
                    "id": 1,
                    "originalExamSessionId": 4761,
                    "newState": "ScheduledButLocked",
                    "stateChangeDate": "2016-11-22T10:28:36.81",
                    "stateInformation": ""
                  },
                  {
                    "id": 2,
                    "originalExamSessionId": 4761,
                    "newState": "Ready",
                    "stateChangeDate": "2016-11-22T10:29:03.86",
                    "stateInformation": ""
                  },
                  {
                    "id": 3,
                    "originalExamSessionId": 4761,
                    "newState": "InProgress",
                    "stateChangeDate": "2016-11-22T10:30:43.89",
                    "stateInformation": ""
                  },
                  {
                    "id": 4,
                    "originalExamSessionId": 4761,
                    "newState": "Finished",
                    "stateChangeDate": "2016-11-22T10:31:07.33",
                    "stateInformation": ""
                  }
                ]
              }
            }
          ]
        }
      ]
    } 

Successful Response: 200

It is worth checking the Surpass Central UI after this process to confirm that the tests have been uploaded as expected. Additional resilience has been built into this process to ensure that the API ignores results have already been successfully imported, as this process could be used more than once during a SurpassLocal test centres downtime. Once the SurpassLocal connection has been restored any uploaded tests will be updated in the SurpassLocal database so they are not resent.



Feedback and Knowledge Base