APIs CMO API Work with custom properties

In this guide, we will show you how to view and create custom properties of an IoT Connection product using the Connection Management Orchestrator (CMO) APIs with cURL. We’ll be focusing on a SIM card, but the same process can be applied to both satellite and SIM cards.

NOTE
  • The API Access Token has an expiration time of 300 seconds (5 minutes). If you get error 401 when trying to make a request this is most likely an expired token.

You will learn how to:

  • Retrieve a list of IoT Connectivity Products
  • Retrieve the fixed and custom properties of your Connection products.
  • Create a custom property for your Connection product.

Prerequisites

Before we begin, ensure you’ve completed the initial tutorial, “Connecting Your Application to the T IoT Hub”. Confirm that:

  1. Register your application in Application Access Management
  2. Configure a request to fetch the API access token
  3. Possess an HTTP Client, such as Postman or cURL .
NOTE
  • This tutorial will refer to the use of cURL. If you use a different platform, the setup might vary.

Step 1. Retrieve a list of IoT Connectivity Products

First, we need to identify the Connectivity product that you want to create and view properties for. In our case, we will be using cURL to execute operations. To check if cURL is installed on your hardware, open a terminal or CMD and run:

  • Retrieve a list of IoT connectivity products with the following cURL command
  • Copy & paste
  • Output
# Replace <api_url> below with the API URL (click chain icon next to API version in Application Management UI to copy it to clipboard)
API_URL="<api_url>"
curl --location "$API_URL/connection-management-orchestrator/v5/$TENANT/product?pageSize=10&fields=id" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $ACCESS_TOKEN"

{
  "entities": [
    {
      "id": "JASPER-8997xxxxxxxxxxxx745"
    },
    {
      "id": "JASPER-8997xxxxxxxxxxxx746"
    },
    {
      "id": "JASPER-8997xxxxxxxxxxxx747"
    },
    {
      "id": "JASPER-8997xxxxxxxxxxxx748"
    },
    {
      "id": "JASPER-8997xxxxxxxxxxxx749"
    },
    {
      "id": "TMUS-8901xxxxxxxxxxxx850"
    },
    {
      "id": "TMUS-8901xxxxxxxxxxxx158"
    },
    {
      "id": "TMUS-8901xxxxxxxxxxxx182"
    },
    {
      "id": "TMUS-8901xxxxxxxxxxxx190"
    },
    {
      "id": "TMUS-8901xxxxxxxxxxxx174"
    }
  ],
  "errors": [],
  "statistics": {
    "currentPage": 1,
    "pageSize": 10
  },
  "links": [
    {
      "type": "self",
      "url": "https://api.telekom.de/t-iot-hub/connection-management-orchestrator/v5/eos/product?pageSize=5&fields=id"
    }
  ]
}
NOTE
  • The pageSize refers to the number of Connectivity products you wish to retrieve from the first page. In our case, we are retrieving 10 products. You can also use pageNumber to refer to a specific page. Play around with the pageSize number to retrieve more or fewer products.

Step 2. View properties of an IoT Connection Product

Now that we have the id number of our IoT Connection Product we can use the id number of the SIM card to access its fixed and custom properties.

  • Retrieve the details of an IoT Connection Product with the following cURL command
  • Copy & paste
  • Output
PRODUCT_ID="<your_product_id>"
# Replace <api_url> below with the API URL (click chain icon next to API version in Application Management UI to copy it to clipboard)
API_URL="<api_url>"
curl --location "$API_URL/connection-management-orchestrator/v5/$TENANT/product/${PRODUCT_ID}-simCard" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $ACCESS_TOKEN"

{
  "id": "JASPER-8997xxxxxxxxxxxx745-simCard",
  "href": "https://api.telekom.de/t-iot-hub/connection-management-orchestrator/v5/TENANT/product/JASPER-8997xxxxxxxxxxxx745-simCard",
  "isBundle": false,
  "status": "ACTIVE",
  "productCharacteristic": [
    {
      "name": "dateActivated",
      "value": "2021-03-23T17:12:51.871Z"
    },
    //and so on for other properties
  ],
  "@baseType": "product",
  "@type": "simCard",
  "correlationId": "569219dc-4de8-47f0-92eb-d46cbbc13500"
}
  • The reason we append to the -simCard at the end of the request path is that we have multiple substructures inside a connectivity product. -dataConnectivity is another example of a request path.
  • Below the productCharacteristic you will see all the properties of your Connection Product. In our case, we used a SIM card. This is also the area where you would see your custom properties once they are added.

Step 3. Creating a custom property

To create a custom property we can use the id number of the SIM card to send a patch request that will add the property for you.

  • Create the custom property with the following cURL command
  • Copy & paste
  • Output
# Replace <api_url> below with the API URL (click chain icon next to API version in Application Management UI to copy it to clipboard)
API_URL="<api_url>"
curl --request PATCH --location "$API_URL/connection-management-orchestrator/v5/$TENANT/product/${PRODUCT_ID}-simCard" \
  --header 'Content-Type: application/json-patch-query+json' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data '[
    {
      "op": "add",
      "path": "customProperty",
      "value": {
        "name": "<your_property_name>",
        "value": "<your_property_value>"
      }
    }
]'

{
  // other properties...
  "customProperty": [
    {
      "name": "MyFavoriteColour",
      "value": "Blue"
    }
  ],
  "@baseType": "product",
  "@type": "simCard",
  "correlationId": "32490aa9-4113-46ee-9483-a95df66ac6c8"
}
  • Once you have successfully added your custom property, the SIM card body will include a new attribute named customProperty** with your new custom property added.
NOTE
  • Your custom property can also be accessed through the GUI of the T IoT Hub on the Connectivity Management page.