1. Service Capability Exposure Function User's Guide
  2. Device Status Query Troubleshooting API

7 Device Status Query Troubleshooting API

This section describes how to use Service Capability Exposure Function (SCEF) Device Status Query Troubleshooting Application Program Interface (API) and access REST interface URLs.

Device Status Query Troubleshooting API Overview

Device Status Query Troubleshooting Application Program Interface (API) can retrieve and delete IP and non-IP data corresponding to a device from Service Capability Exposure Function (SCEF).

Device Status Query Troubleshooting API provides the following APIs:

Understanding the APIs

You can access these APIs using any existing operator’s account that is used to log in to the Oracle Communications Service Gatekeeper (OCSG) Partner Relationship Management (PRM) portal. A new operator account can be created through the Weblogic Admin portal.

For creating users, refer to Create User Account.

NIDD Troubleshooting API

This API accepts the following query parameters to retrieve the data:
  • externalId
  • msisdn
  • imsi
  • tltrId
At least one query parameter is required to process the request. If more than one query parameter is present in the request, then the query parameters are processed in the following order of precedence:
  1. tltrId
  2. externalId
  3. msisdn
  4. imsi

For example, if all the four query parameters are present in the request, the API considers the tltrId parameter first to process the request. If the tltrId parameter is not provided, then API considers the next available parameter according to the order of precedence.

This API supports GET and DELETE methods.

Retrieving and Deleting Data

URL Format

https://<APPServer IP>:9002/troubleshooting/oam/nidd?<parameter=input value>

where, <parameter=input value> indicates the parameter name and its value.

Example of REST interface URLs
  • https://<APPServer IP>:9002/troubleshooting/oam/nidd?tltrId=5e66ed330f3200470000000d
  • https://<APPServer IP>:9002/troubleshooting/oam/nidd?externalId=extid1@oracle.com
  • https://<APPServer IP>:9002/troubleshooting/oam/nidd?msisdn=7799383911
  • https://<APPServer IP>:9002/troubleshooting/oam/nidd?imsi=123456789123456

GET Call Flow

This call flow explains different scenarios involved in retrieving non-IP delivery data corresponding to a device.

Figure 7-1 NIDD GET Call Flow

NIDD GET Call Flow

Sample Request

https://10.75.225.37:9002/troubleshooting/oam/nidd?msisdn=555555555

Sample Respose

{
  "niddDeviceInfo": [
    {
      "tltrId": "5f081abb01ca00ce00000006",
      "status": "Success",
      "data": {
        "version": 1,
        "recordStatus": "Created",
        "scsAsId": "SCSAS50",
        "imsi": "1234512351",
        "grantTime": "03/15/52 13:29:43",
        "apn": "apn50.test.com",
        "epsBearerId": "Not Set",
        "msisdn": "555555555",
        "mmeSgsnFqdn": "Not Set",
        "plmnId:mcc": 0,
        "plmnId:mnc": 0,
        "imei": "Not Set",
        "imeiSv": "Not Set",
        "ratType": 4294967295,
        "retransmissionTime": "Not Set",
        "ueAvailability": false,
        "servingPlmnRate": 0,
        "currentDownlinkApnRate": 0,
        "currentUplinkApnRate": 0,
        "currentPlmnRate": 0,
        "downlinkApnRateResetTime": "12/31/69 19:00:00",
        "uplinkApnRateResetTime": "12/31/69 19:00:00",
        "plmnRateResetTime": "12/31/69 19:00:00",
        "notificationUri": "http://10.75.224.65:10001/scs/resources/t8",
        "pdnEstablishmentOption": "WAIT_FOR_UE",
        "pdnConnectionTime": "12/31/69 19:00:00",
        "List of Pending Data": [
                     {
                                "ttrId": "1",
                                "data": "Hello from Network10",
                                "size": 20,
                               "priority": 1,
                               "maximumLatency": "08/12/20 14:00:00"
                     }
         ]
      }
    }
  ]
}

Note:

The following are some default values for the NIDD device information:
"mmeSgsnFqdn": "Not Set",
"plmnId:mcc": 0,
"plmnId:mnc": 0,
"imei": "Not Set",
"imeiSv": "Not Set",
"ratType": 4294967295,
"retransmissionTime": "Not Set",
"ueAvailability": false,
"servingPlmnRate": 0,
"currentDownlinkApnRate": 0,
"currentUplinkApnRate": 0,
"currentPlmnRate": 0,
"downlinkApnRateResetTime": "12/31/69 19:00:00",
"uplinkApnRateResetTime": "12/31/69 19:00:00",
"plmnRateResetTime": "12/31/69 19:00:00",
"recordStatus" could have the following values - Pending, Created or DeleteInProgress

DELETE Call Flow

This call flow explains different scenarios involved in deleting the non-IP delivery data corresponding to a device.

Figure 7-2 NIDD DELETE Call Flow

NIDD DELETE Call Flow

Sample Request

https://10.75.225.37:9002/troubleshooting/oam/nidd?msisdn=555555555

Sample Response
{
    "niddDeleteResult": [
        {
            "status": "200 OK",
            "tltriId": "5f081abb01ca00ce00000006"
        }
    ]
}

Note:

When several contexts exist for a given device, response is provided with all Tltrid’s and their operation status for each.

MONTE Troubleshooting Non-IP API

This API accepts the following query parameters to retrieve the data:
  • externalId
  • msisdn
  • tltrId
At least one query parameter is required to process the request. If more than one query parameter is present in the request, then the query parameters are processed in the following order of precedence:
  1. tltrId
  2. externalId
  3. msisdn

For example, if all the three query parameters are present in the request, the API considers the tltrId parameter first to process the request. If the tltrId parameter is not provided, then API considers the next available parameter according to the order of precedence.

This API supports GET and DELETE methods.

Retrieving and Deleting Data

URL Format

https://<APPServer IP>:9002/troubleshooting/oam/me-nonip?<parameter=input value>

where, <parameter=input value> indicates the parameter name and its value.

Example of REST Interface URLs:
  • https://<APPServer IP>:9002/troubleshooting/oam/me-nonip?tltrId=5e66ed330f3200470000000d
  • https://<APPServer IP>:9002/troubleshooting/oam/me-nonip?externalId=extid1@oracle.com
  • https://<APPServer IP>:9002/troubleshooting/oam/me-nonip?msisdn=7799383911 3.2.2

GET Call Flow

This call flow explains different scenarios involved in retrieving non-IP delivery data corresponding to a device.

Figure 7-3 MONTE Non-IP GET Call Flow

MONTE Non-IP GET Call Flow

Sample Request

https://10.75.225.37:9002/troubleshooting/oam/me-nonip?msisdn=1234567890

Sample Response

{
  "monitoringDeviceInfo": [
    {
      "subscriptionId": "5f0822a801ca00ce0000000a",
      "status": "Success",
      "data": {
        "version": 1,
        "recordStatus": "Created",
        "scefReferenceId": 10,
        "scsAsId": "SCSAS50",
        "notificationUri": "http://10.10.10.6:8787/configurations/notification",
        "monitoringType": "UE_REACHABILITY",
        "reachabilityType": "SMS",
        "maxLatencyPresent": false,
        "maxRespTimePresent": false,
        "numDlPacketsPresent": false,
        "monitorExpireTime": "Not Set",
        "maxAllowedReportCount": 1,
        "currentReportCount": 0,
        "userIdentityInUse": "ExternalIdentifier",
        "externalId": "56789112@StreetLight-BLR-22.com",
        "msisdn": "988739322222",
        "hssRealm": "oracle.com",
        "hssFqdn": "peer1.oracle.com"
      }
    },
    {
      "subscriptionId": "5f08241501ca00ce0000000d",
      "status": "Success",
      "data": {
        "version": 1,
        "recordStatus": "Created",
        "scefReferenceId": 13,
        "scsAsId": "SCSAS70",
        "notificationUri": "http://10.75.225.37:10001/configurations/notification",
        "monitoringType": "AVAILABILITY_AFTER_DDN_FAILURE",
        "idleStatusIndicationPresent": true,
        "monitorExpireTime": "Not Set",
        "maxAllowedReportCount": 100,
        "currentReportCount": 10,
        "userIdentityInUse": "ExternalIdentifier",
        "externalId": "111111111111@StreetLight-BLR-10.com",
        "hssRealm": "oracle.com",
        "hssFqdn": "peer1.oracle.com"
      }
    }
  ]
}

DELETE Call Flow

This call flow explains different scenarios involved in deleting the non-IP delivery data corresponding to a device.

Figure 7-4 MONTE Non-IP DELETE Call Flow

MONTE Non-IP DELETE Call Flow

Sample Request

https://10.75.225.37:9002/troubleshooting/oam/me-nonip?msisdn=1234567890

Sample Response

{
    "monteDeleteResult": [
        {
            "status": "204 No Content",
            "subscriptionId": "5f0822a801ca00ce0000000a"
        },
        {
            "status": "204 No Content",
            "subscriptionId": "5f08241501ca00ce0000000d"
        }
    ]
}

Note:

When several contexts exist for a given device, response is provided with all Tltrid’s and their operation status for each.

MONTE Troubleshooting IP API

This API accepts the following query parameters to retrieve the data:
  • externalId
  • msisdn
  • imsi
  • ip
  • subscriptionid
At least one query parameter is required to process the request. If more than one query parameter is present in the request, then the query parameters are processed in the following order of precedence:
  1. externalId
  2. msisdn
  3. imsi
  4. ip
  5. subscriptionid

For example, if all the five query parameters are present in the request, the API considers the externalId parameter first to process the request. If the externalId parameter is not provided, then API considers the next available parameter according to the order of precedence.

Note:

The subscriptionid parameter mentioned in the query parameter must be of only application subscriptions. Device SubscriptionId is not accepted.

This API supports GET and DELETE methods.

Retrieving and Deleting Data

In MONTE IP GET, when subscriptionid is provided as an input query parameter, then the device of that subscription is searched, and subscriptions data, such as App subscriptions, Device subscriptions, and Buffered messages, are retrieved for the given device.

In MONTE IP DELETE, when subscriptionid is provided as an input query parameter, then the device of that subscription is searched, and subscriptions data, such as App subscriptions and Device subscriptions, are deleted for the given device.

URL Format

https://<APPServer IP>:9002/troubleshooting/oam/me-ip?<parameter=input value>

where <parameter=input value> indicates the parameter name and its value.

Examples of REST interface URLs

  • https://<APPServer IP>:9002/troubleshooting/oam/me-ip?externalId=extid1@oracle.com
  • https://<APPServer IP>:9002/troubleshooting/oam/me-ip?msisdn=7799383911
  • https://<APPServer IP>:9002/troubleshooting/oam/me-ip?imsi=7799383911
  • https://<APPServer IP>:9002/troubleshooting/oam/me-ip?ip=10.75.224.61
  • https://<APPServer IP>:9002/troubleshooting/oam/me-ip?subscriptionid=046b6c7a-0b8b-43b9-b35c-6489e6daee92

GET Call Flow

Table 7-1 Device Status

Status Description
Not Connected Device is never connected to MQTT Broker
Connected Device is connected to MQTT Broker
Disconnected Device is not connected to MQTT Broker

This call flow explains different scenarios involved in retrieving IP data corresponding to a device.

Figure 7-5 MONTE IP GET Call Flow

MONTE IP GET Call Flow

Sample Request

https://10.75.225.37:9002/troubleshooting/oam/me-ip?msisdn=7829139111

Sample Response

{
    "ipDevices": [
        {
            "apn": "test.ashok3.com",
            "applicationSubscription": [
                {
                    "appId": "partner1-scefapp",
                    "deviceInfo": "7829139111",
                    "subscribedTopic": "tracking/batterylevel/#",
                    "subscriptionId": "b23a82eb-ef45-41fe-9004-e7c695731d92"
                }
            ],
            "bufferedMessages": [
                {
                    "bufferedData": "ashok sent at 10:58ampm on 07102020",
                    "publishedTopic": "tracking/batterylevel/ashok",
                    "subscribedTopic": "tracking/batterylevel/ashok"
                }
            ],
            "deviceId": "Ashok3",
            "deviceSubscription": [
                {
                    "subscribedTopic": "tracking/batterylevel/ashok",
                    "subscriptionId": "72739d0d-b89b-4b4c-8a29-b66c0ef9b7e6"
                }
            ],
            "deviceType": "MQTT",
            "externalId": "7829139111@StreetLight-BLR-5",
            "imsi": 7829139111,
            "msisdn": 7829139111,
            "sessionId": ".;1096298392;1",
            "status": "Disconnected"
        }
    ]
}

DELETE Call Flow

This call flow explains different scenarios involved in deleting the IP data corresponding to a device.

MONTE IP DELETE deletes the device subscriptions and application subscriptions. If the device is connected to the Message Queuing Telemetry Transport (MQTT) broker, it remains in the connected state.

Figure 7-6 MONTE IP DELETE Call Flow

MONTE IP DELETE Call Flow

Sample Request

https://10.75.225.37:9002/troubleshooting/oam/me-ip?msisdn=7829139111

Sample Response

200 OK

Device Status Query Troubleshooting API Configuration

Device Troubleshooting Query APIs expose Management bean that can be accessed through the OCSG Admin portal.

To modify the default values:
  1. Navigate to the Management bean: Service-gatekeeper-domain, and then OCSG, and then AppServerX, and then Communication Services, and then SCEFDTS_Configuration.
    The following screen appears:

    Figure 7-7 Management Bean

    Management Bean
  2. Change the default values as required.
  3. Click on Update Attributes.

Table 7-2 Attribute Description

Name Description Scope
ReadTimeOut Read time out in ms.

The default value is 2000 ms.

 Cluster, Shared across AppServers.

Changes made on one AppServer reflects on all other AppServers.
ConnectTimeOut Connect time out in ms.

The default value is 30000 ms.

 Cluster, Shared across AppServers.

Changes made on one AppServer reflects on all other AppServers.