Migrate to Trusted Device microservice
The Trusted Device microservice and its endpoint, POST /orchestration-commands-v2, provide a range of error responses in connection with orchestration.
To start using the new error handling in a mobile application based on the Orchestration SDK, the application needs to be reconfigured to communicate with the POST /orchestration-commands-v2 endpoint.
The endpoint is fully backwards compatible when handling successful requests. The format of the error messages is also backwards compatible, existing error callback methods can therefore be also used to handle failed requests. Nevertheless, new and different error messages are to be expected, therefore the error handling of your mobile application will need an update to accommodate these error strings.
If more context or additional information is required when handling failed requests, additional error handling source code can be introduced at the HTTP level (see Handle error responses at the HTTP level (optional)).
Switch to POST /orchestration-commands-v2 endpoint
To start using the improved error handling, the mobile application needs to be reconfigured to connect to the POST /orchestration-commands-v2 endpoint of your tenant's Platform API.
https://example-tenant.sdb.tid.onespan.cloud/v1/orchestration-commands-v2
Using the Orchestration SDK sample application as reference, adapt the following variables to create the connection:
| Operating system, language | File name | Variable or getter |
|---|---|---|
| Android, Java | Constants.java | ENDPOINT_URL |
| iOS, Objective-C | Constants.m | ENDPOINT_URL |
| iOS, Swift | Constants.swift | URLs::endpoint |
Handle error responses at the HTTP level (optional)
If the HTTP response received from the POST /orchestration-commands-v2 endpoint deserializes into the TrustedDeviceErrroOutputDto object, the following error information can be obtained in the HTTP handler of the mobile application:
- errorCategory
- errorCode
- message
- logCorrelationId
- timestamp
- validationErrors
You can implement error handling upon checking if the errorCode field exists inside the object representing the JSON response. Using the Orchestration SDK sample application as reference, adapt the following methods:
| Operating system, language | File name | Method |
|---|---|---|
| Android, Java | HttpUtils.java | performJSONRequest |
| iOS, Objective-C | HttpUtils.m | performJsonRequestOnServerUrl |
| iOS, Swift | HttpUtils.swift | performJsonRequestOnServerUrl |
At this point, the error handler could either abort the processing of the error response or continue the flow by passing the value of the command field into the execute method of the Orchestrator object. This triggers a callback and visualizes the error response for the user.
Handle error responses as callbacks
After processing the HTTP response and passing the value of the command field into the execute method of the Orchestrator object, the Orchestration SDK decodes the received data. If the decoded data contains an error payload received from the POST /orchestration-commands-v2 endpoint, the Orchestrator object constructs the OrchestrationServerError object. This error object is then passed into the appropriate callback method of an activity using OrchestrationErrorCallback (Android) or a controller using OrchestrationErrorDelegate (iOS).
The following error information can be obtained from the OrchestrationServerError object:
- readableMessage
- customPayload (optional)
You can implement error handling based on the string value of the error message. Using the Orchestration SDK sample application as reference, adapt the following methods:
| Operating system, language | File name | Method |
|---|---|---|
| Android, Java | SampleOrchestrationCallback.java | onOrchestrationServerError |
| iOS, Objective-C | SampleOrchestrationDelegate.m | orchestrationServerError |
| iOS, Swift | OrchestrationSampleDelegate.swift | orchestrator(with OrchestrationServerError input) |