APIs CMO API Understanding Synchronous and Asynchronous operations

This page provides an overview of the Connection Management Orchestrator (CMO) API, focusing on the differences between synchronous and asynchronous operations.

Synchronous request - In the API, calls for operations like activating a SIM card happen immediately. The client application sends the request and waits for an immediate response.
Asynchronous request - CMO accepts the request for background processing and returns a monitor or task resource. Use the resource URL in href to retrieve its current state.

NOTE

Short summary:

  • Synchronous: Immediate response, 200 OK, and a modified product
  • Asynchronous: Background processing with a monitor or task resource for tracking progress

Here’s the table for MNO platforms that support the CMO API:

Platform NameSynchronous UpdatesAsynchronous Updates
TMSP✖✔
TMUS✔✖
INTELSAT✖✔
IOTA✔✖
JASPER✔✖
AIRLINQ✖✔
1NCE✔✖
STC✖✔
TURKCELL✖✔
GALAXY1✖✔
NOTE
  • The operations listed below are available in the CMO API but may not be supported by all platforms. Here is page for more information about the supported features.

Operation states

When CMO accepts an asynchronous operation, it returns a monitor or task resource with an href that you can retrieve to track its progress. A monitor tracks an asynchronous request for a specific product. A task represents a complex operation, such as a batch update.

Both resources use state to show whether the operation is still running and how it finished.

The top-level state reports the current overall state of the operation. A monitor can also contain a state in each item of its response array. This route-level state shows the outcome reported for a specific platform or account and is important when one request involves multiple routes.

StateWhat it meansWhat to do
IN_PROGRESSThe operation is still being processed. This is the only nonterminal state.Continue polling the monitor or task URL in href. Avoid sending an overlapping update for the same resource.
DONECMO reports the operation as completed.No further polling is required. Inspect the response or retrieve the product if you need to confirm the resulting values.
REJECTEDCMO reports that the operation was rejected before completion.Inspect the top-level errors[]. For a monitor, also inspect every item in response[]. Correct the reported cause before submitting a new operation.
FAILEDCMO reports that the operation could not complete or that its result could not be determined.Inspect the top-level errors[]. For a monitor, also inspect every route’s message, statusCode, and body in response[]. Resolve the reported cause before retrying.
TERMINATEDProcessing was stopped or cancelled before normal completion.Treat the operation as finished but not successfully completed. Submit a new operation if the change is still required.
NOTE

For monitor operations involving multiple platforms or accounts, route outcomes can differ. The top-level state does not replace the route details. Check every item in response[] together with the top-level errors[] to identify partial or mixed outcomes.

CMO treats DONE, REJECTED, FAILED, and TERMINATED as terminal states. Only an IN_PROGRESS operation is checked again when you retrieve its monitor or task.

Synchronous operations

The following operations are considered synchronous:

  • Custom properties assignment
  • SIM card status update for platforms that provide synchronous activation ()

Synchronous operations are defined by the fact that the change is being applied immediately. The response type is 200 OK and the body contains the result of the operation. Here are two examples of synchronous operations responses:

  • SIM card activation
  • Custom properties assignment
{
  "id": "JASPER-899xxxxxxxxxxxxxxx47",
  "href": "<api_url>/TENANT/product/JASPER-899xxxxxxxxxxxxxxx47",
  "isBundle": true,
  "startDate": "2020-04-01T20:00:00.000Z",
  "status": "INACTIVE",
  ...
}

{
  "id": "JASPER-899xxxxxxxxxxxxxxx47",
  ...
  "customProperty": [
    {
      "name": "MyFavoriteColour",
      "value": "Blue"
    }
  ],
  ...

Asynchronous operations

The following operations are considered asynchronous:

  • SIM card status update for platforms that provide asynchronous activation
  • SIM card transfer for platforms that provide the transfer capability

Asynchronous operations has response type 202 Accepted and the response body consist of a monitor object. The monitor can be used to track the status of the operation. Here is the example of asynchronous operations responses:

  • Headers
  • Body
{
  "Link": "<https://{cmo_api_url}/{tenant}/monitor/{monitorId}>; rel="related"; title="monitor", <https://{cmo_api_url}/{tenant}/product/{productId}>; rel="self", <https://{cmo_api_url}/{tenant}/product/{productId}>; rel="canonical""
}

{
  "id": "{iccid}-1747918290-monitor",
  "href": "{cmo_api_url}/{tenant}/monitor/{iccid}-1747918290-monitor",
  "sourceHref": "{cmo_api_url}/{tenant}/product/{platformName}-{iccid}-simCard",
  "state": "IN_PROGRESS",
  "request": {
    "method": "PATCH",
    "body": [
      {
        "op": "replace",
        "path": "/status",
        "value": "SUSPENDED"
      }
    ],
    "headers": [
      {
        "name": "accept",
        "value": "application/json"
      },
      {
        "name": "content-type",
        "value": "application/json-patch+json"
      }
    ]
  },
  "response": [
    {
      "platform": "{platformName}",
      "statusCode": 200,
      "message": "",
      "state": "IN_PROGRESS",
      "body": {
        // ... platform specific response ...
      },
      "headers": [
        {
          "name": "Content-Type",
          "value": "application/json"
        }
      ]
    }
  ],
  "@type": "monitor",
  "errors": [],
  "correlationId": "08cf2679-a736-45bb-936d-7c00d1628f38"
}

Note: Handling Asynchronous Update Requests

If you encounter an error such as “SIM is being processed by another request”, it indicates that multiple update requests were sent in parallel before the first asynchronous operation is completed, leading to request failures.

To ensure reliable execution:

  1. Track request status: Implement logic to monitor the status of ongoing update requests before initiating new ones. This can be done by awaiting the completion callback or polling a status endpoint (if available).
  2. Apply safe retries: Retry only after confirming that the previous request has completed (successfully or otherwise). Avoid triggering overlapping “in-flight” requests.
  3. Use monitoring tools: Leverage IoT Hub’s Monitor API to track and manage the state of update requests effectively.

Batch operations

Batch operations can combine synchronous and asynchronous updates. When CMO creates an asynchronous batch task, it returns 201 Created and a task resource. Retrieve the URL in href to track the task’s state. Here is an example response:

{
  "id": "{iccid}-{timestamp}-batchUpdate",
  "href": "https://{cmo_api_url}/{tenant}/task/{iccid}-{timestamp}-batchUpdate",
  "errors": [],
  "correlationId": "{correlationId}"
}