APIs Work with connectivity groups

This tutorial will guide you on how to work with Connectivity groups using the CMO and DMO APIs. You’ll learn the fundamental CRUD operations and how to view your Connectivity groups and Connection products.

NOTE
  • “Connectivity groups” are applicable only to Satellite Connect at this time.

You will learn how to

  • Retrieve a list of connection products
  • Fetch two specific products
  • Create a connectivity group
  • Check the connectivity group you create
  • Retrieve your connectivity group
  • Update your connectivity group
  • Delete your connectivity group

Prerequisites

Before we begin, ensure you complete the initial tutorial, “Connecting Your Application to the T IoT Hub”.

Make sure that you:

  1. Register your application in Application Access Management
  2. Configure a request to fetch the API access token
  3. Register an Application Entity (AE) in your environment.
  4. 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 connection products to create your group

If you need clarification on which product to create a group with, you can use this request to fetch a list of all your connected products. From this list, select the products you want to group. 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:

    curl --version
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.
  • Open cURL or your preferred HTTP client.
  • Retrieve the list of connection products with the following cURL command
  • Copy & paste
  • Output
# Enter your tenant name
TENANT="<your_tenant_name>"
ACCESS_TOKEN="<access_token>"

curl --location 'https://hub.iot.telekom.com/api-gw/connection-management-orchestrator/v5/$TENANT/product?pageSize=5&fields=id%2CconnectivityType%2Cstatus' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'

{
    "entities": [
        {
            //the ID of a connectivity product.
            //Copy the "id" for the next step.
            "id": "JASPER-89xxxxxxxxxxxxxx747",
            "status": "ACTIVE",
            "connectivityType": "CELLULAR"
        },
        {
            //the ID of a connectivity product
            //Copy the "id" for the next step.
            "id": "JASPER-89xxxxxxxxxxxxxx749",
            "status": "ACTIVE",
            "connectivityType": "CELLULAR"
        }
    ],
    "statistics": {
            "currentPage": 1,
            "pageSize": 1
            },
    "links": [
        {
            "type": "self",
            "url": "https://hub.iot.telekom.com/api-gw/connection-management-orchestrator/eos/product?pageSize=5&fields=id,connectivityType,status"
        }
    ]
}
  • An example of an ID can be “JASPER-8997112212741433749”.*

Step 2. Fetch specific products to create a group (Using product ID)

If you know the network ID’s of your products. Use this request to fetch their respective product ID´s. In this case, we will be using cURL to execute operations.

  • Copy & paste
  • Output
PRODUCT_ID="<your_product_id>"

curl --location 'https://hub.iot.telekom.com/api-gw/connection-management-orchestrator/v5/$TENANT/product/find' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $ACCESS_TOKEN' \
  --data '{
    "iccidList": [
      "$PRODUCT_ID"
    ],
    "terminalSNList": [
      "$PRODUCT_ID"
    ]
  }'

{
    "entities": [
        {
            "id": "INTELSAT-1234",
            "href": "https://hub.iot.telekom.com/api-gw/connection-management-orchestrator/v5/TENANT/product/INTELSAT-1234",
            "status": "ACTIVE",
            "connectivityType": "SATELLITE",
            "isBundle": true,
            "isCustomerVisible": true,
            "productCharacteristic": [
                {
                    "name": "system",
                    "value": "INTELSAT"
                },
                {
                    "name": "account_index",
                    "value": "1"
                }
            ],
            "name": "",
            "startDate": "2023-05-18T00:00:00.000Z",
            "billingAccount": {
                "id": ""
            },
            "productOffering": {
                "name": "FlexEnterprise Global"
            },
            "relatedParty": [
                {
                    "id": "340",
                    "name": "intelsat_test",
                    "role": "customer"
                }
            ],
            "@baseType": "product",
            "@type": "IoTConnection",
            "productRelationship": [
                {
                    "type": "BUNDLED",
                    "product": {
                        "id": "INTELSAT-1234-terminal",
                        "href": "https://hub.iot.telekom.com/api-gw/connection-management-orchestrator/v5/TENANT/product/INTELSAT-1234-terminal",
                        "isBundle": false,
                        "isCustomerVisible": true,
                        "productCharacteristic": [
                            {
                                "name": "serialNumber",
                                "value": "1234"
                            },
                            {
                                "name": "name",
                                "value": "LW01-Media_Mobil-1234"
                            },
                            {
                                "name": "latitude",
                                "value": "53.11050000"
                            },
                            {
                                "name": "longitude",
                                "value": "8.88130000"
                            },
                            {
                                "name": "model",
                                "value": "TIV-iQDesktop-1234-GS"
                            },
                            {
                                "name": "state",
                                "value": "synced"
                            },
                            {
                                "name": "mobilityType",
                                "value": "Fixed"
                            },
                            {
                                "name": "imoNumber",
                                "value": "0"
                            },
                            {
                                "name": "mmsi",
                                "value": ""
                            },
                            {
                                "name": "antennaCode",
                                "value": ""
                            },
                            {
                                "name": "lastUpdated",
                                "value": "2023-05-18T15:56:51.000Z"
                            },
                            {
                                "name": "lastSync",
                                "value": "2023-05-18T15:56:51.000Z"
                            }
                        ],
                        "customProperty": [],
                        "@baseType": "product",
                        "@type": "terminal",
                        "status": "ACTIVE"
                    }
                },
                {
                    "type": "BUNDLED",
                    "product": {
                        "id": "INTELSAT-1234-usageVolume-data",
                        "href": "https://hub.iot.telekom.com/api-gw/connection-management-orchestrator/v5/TENANT/product/INTELSAT-1234-usageVolume-data",
                        "isShared": false,
                        "isBundle": false,
                        "usageType": "DATA",
                        "@baseType": "product",
                        "@type": "usageVolume",
                        "bucketCounter": [
                            {
                                "valueName": "1401626.776576 KB",
                                "value": {
                                    "amount": 1401626.776576,
                                    "units": "KB"
                                },
                                "consumptionPeriod": {
                                    "startDateTime": "2023-05-18T16:08:35.000Z",
                                    "endDateTime": "2023-06-09T08:36:31.696Z"
                                },
                                "counterType": "USED"
                            }
                        ]
                    }
                }
            ],
            "correlationId": "dbe56aa9-a0c1-4b91-b2b8-1fb3141dd191"
        }
    ],
    "errors": [
        {
            "type": "Not Found",
            "status": 404,
            "title": "Error",
            "detail": "Product with iccid 8907160000000000533 not found",
            "instance": "https://hub.iot.telekom.com/api-gw/connection-management-orchestrator/v5/eos/product/TENANT/product/find",
            "externalErrors": [],
            "@type": "problem",
            "traceId": "15ff4b9d-cbcc-4180-96d3-e2fe7cdcbd4e"
        }
    ]
}

Step 3. Create your connectivity group

When you find the products you want to create a group with through the list or specific find, you will need the product ID number, Connectivity type, and Network ID number. To retrieve this information, use either the GET Connection Products request or the FIND Connection Product request we used earlier. In this case, we will be using cURL to execute operations.

  • Create a group with the following cURL command and replace the values of <your_product_id_number>,<your_product_group_number>, <your_network_id_number>, <your_router_serial_number>, <your_priority_product_id_number>, <your_fallback_product_id_number>, <your_threshold_level> and <your_group_name> with your data.
  • Copy & paste
  • Output
curl --location 'https://hub.iot.telekom.com/api-gw/device-management-orchestrator/v3/$TENANT/connectivityGroups' \
  --header 'Content-Type: application/json;ty=28' \
  --header 'X-M2M-Origin: CPDemo' \
  --header 'X-M2M-RI: 123' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $ACCESS_TOKEN' \
  --data '{
    "dtiot:conGp": {
    "cnd": "com.telekom.iot.orchestrator.connectivityGroup",
    "conPs": [
        {
            "coPID": "<your_product_id_number>",
            "coPTe": <your_connectivity_type>,
            "netID": "your_network_id_number"
        },
        {
            "coPID": "<your_product_id_number>",
            "coPTe": <your_connectivity_type>,
            "netID": "your_network_id_number"
        }
    ],
        "liCRr": "<your_router_serial_number>",
        "priRe": {
          "prPID": "<your_priority_product_id_number>",
          "faPID": "your_fallback_product_id_number",
          "priTd": <your_threshold_level>
        },
        "updTe": 0,
        "errMe": "",
        "rn": "<your_group_name>"
    }
}'

{
  "dtiot:conGp": {
    "cnd": "com.telekom.iot.orchestrator.connectivityGroup",
    "conPs": [
      {
        "coPID": "<your_product_id_number>",
        "coPTe": 1,
        "netID": "your_network_id_number"
      }
    ],
    "liCRr": "<your_router_serial_number>",
    "priRe": {
      "prPID": "<your_priority_product_id_number>",
      "faPID": "your_fallback_product_id_number",
      "priTd": 6
    },
    "updTe": 0,
    "errMe": "",
    "rn": "connectivityGroup_1",
    "ty": 28,
    "cr": "CPDemo",
    "st": 0,
    "ri": "64a816836e874776979410ba",
    "pi": "64a580864238880cfd551557",
    "ct": "20230707T134331,108000",
    "lt": "20230707T134331,108000"
  }
}
NOTE
  • The Threshold level can be from 1-6 (1 = better, 6 = worse).
NOTE
  • updTe = Status update (Shows if the process was executed successfully)
    • 0 = The operation hasn’t been executed
    • 2 = The operation was succesfull
  • errMe = Error message(Shows you an error message if something failed during the process)
  • rn = Group name(The name of the group of products)
  • coPID = Product ID Number
  • coPTe = Connectivity type
  • netID = Network ID Number

Step 4. Check your group is added to your connectivity groups

Next, we want to check if the connectivity group you made was successfully added to the list of groups. Again, we will be using cURL to execute operations.

  • Fetch the list of connectivity groups with the following cURL command and replace the value of <your_application_name> with your data.
  • Copy & paste
  • Output
curl --location 'https://hub.iot.telekom.com/api-gw/device-management-orchestrator/v3/$TENANT/connectivityGroups?rcn=4&ty=28' \
  --header 'Content-Type: application/json' \
  --header 'X-M2M-Origin: <your_application_name>' \
  --header 'X-M2M-RI: 123' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'

{
  "m2m:cnt": {
    "mbs": 10000,
    "mni": 10,
    "rn": "connectivityGroups",
    "ty": 3,
    "st": 0,
    "cbs": 0,
    "cni": 0,
    "cr": "CAdmin",
    "ri": "64a580864238880cfd551557",
    "pi": "<your_tenant>",
    "ct": "20230705T143903,060000",
    "lt": "20230705T143903,060000",
    "dtiot:conGp": [
      {
        "cnd": "com.telekom.iot.orchestrator.connectivityGroup",
        "conPs": [
          {
            "coPID": "<your_product_id_number>",
            "coPTe": 1,
            "netID": "your_network_id_number"
          }
        ],
        "liCRr": "<your_router_serial_number>",
        "priRe": {
          "prPID": "<your_priority_product_id_number>",
          "faPID": "your_fallback_product_id_number",
          "priTd": 6
        },
        "updTe": 3,
        "errMe": "command is required.",
        "rn": "connectivityGroup_1",
        "ty": 28,
        "cr": "CPDemo",
        "st": 1,
        "ri": "64a816836e874776979410ba",
        "pi": "64a580864238880cfd551557",
        "ct": "20230707T134331,108000",
        "lt": "20230707T134332,308000"
      }
    ]
  }
}

Step 5. Retrieve your connectivity group (Read)

To retrieve your connectivity group, you can use the following cURL command and replace the value of <your_group_name> and <your_application_name> with your data.

  • Copy & paste
  • Output
curl --location 'https://hub.iot.telekom.com/api-gw/device-management-orchestrator/v3/$TENANT/connectivityGroups/<your_group_name>' \
  --header 'Content-Type: application/json' \
  --header 'X-M2M-Origin: <your_application_name>' \
  --header 'X-M2M-RI: 123' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'

{
  "dtiot:conGp": {
    "cnd": "com.telekom.iot.orchestrator.connectivityGroup",
    "conPs": [
      {
        "coPID": "<your_product_id_number>",
        "coPTe": 1,
        "netID": "your_network_id_number"
      }
    ],
    "liCRr": "<your_router_serial_number>",
    "priRe": {
      "prPID": "<your_priority_product_id_number>",
      "faPID": "your_fallback_product_id_number",
      "priTd": 6
    },
    "updTe": 3,
    "errMe": "command is required.",
    "rn": "connectivityGroup_1",
    "ty": 28,
    "cr": "CPDemo",
    "st": 1,
    "ri": "64a816836e874776979410ba",
    "pi": "64a580864238880cfd551557",
    "ct": "20230707T134331,108000",
    "lt": "20230707T134332,308000"
  }
}

Step 6. Update your connectivity group (Update)

If you update your recently created group, you only need to change the POST request we made earlier to create a group to a PUT request. Again, cURL will be used to execute operations.

  • Copy the information from the previous command to create a group and replace the POST request with a PUT request. Make sure you replace <your_group_name> with your data and make the changes you wish to update.
  • Copy & paste
  • Output
curl --request PUT --location 'https://hub.iot.telekom.com/api-gw/device-management-orchestrator/v3/$TENANT/connectivityGroups/<your_group_name>'

{
  "dtiot:conGp": {
    "cnd": "com.telekom.iot.orchestrator.connectivityGroup",
    "conPs": [
      {
        "coPID": "<updated_product_id_number>",
        "coPTe": 1,
        "netID": "<updated_network_id_number>"
      }
    ],
    "liCRr": "<updated_router_serial_number>",
    "priRe": {
      "prPID": "<your_priority_product_id_number>",
      "faPID": "your_fallback_product_id_number",
      "priTd": 6
    },
    "updTe": 3,
    "errMe": "command is required.",
    "rn": "connectivityGroup_1",
    "ty": 28,
    "cr": "CPDemo",
    "st": 2,
    "ri": "64a816836e874776979410ba",
    "pi": "64a580864238880cfd551557",
    "ct": "20230707T134331,108000",
    "lt": "20230707T142746,777000"
  }
}

Step 7. Delete your connectivity group (Delete)

If you want to delete your group, you only need to change the GET request created earlier to retrieve your group into a DELETE request.

  • To delete your connectivity group you can use the following cURL command and replace <your_group_name>, and <your_application_name> with your data.
  • Copy & paste
  • Output
curl --request DELETE --location 'https://hub.iot.telekom.com/api-gw/device-management-orchestrator/v3/$TENANT/connectivityGroups/<your_group_name>' \
  --header 'Content-Type: application/json' \
  --header 'X-M2M-Origin: <your_application_name>' \
  --header 'X-M2M-RI: 123' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'

on success the response body is empty