Import Usage by API

Usage can be imported into the system using the v6/DataImport/Usage API. This API can post data to the system with the one or more usage records contained in the API body. The posted usage records will then be transformed as needed, mediated and rated.

Posting a Record

The DataImport/Usage API call needs to be submitted a with usage feed value matching a usage feed that is configured in the system. This can be either the usage feed's Name or its ID.

{{URL}}ResourceServer/api/{{apiVersion}}/internal/DataImport/Usage/{{udrFeedId}}

The usage feed configured in the system will be set to use a particular data profile (a sample data profile is shown below).

The data profile will determine how the usage record contained in the API request is transformed.

Request

The API body will contain the usage data. This data can be in csv or columnar format (this is determined by the data profile configuration that the usage feed has been setup to use). Below the request body contains data in csv format.

Note: Up to 1,000 rows (records) can be supplied in the request body.

{
    "data": [
        "2022-05-01T01:01:00.01,Unknown,4038675309,4038675345,648-688-4180,94,False,False,data_class,Data_1,2022-05-01T01:01:00.01"
    ]
}

Response

The API response will include a trackingId which can uniquely identify the request in the system.

{
    "trackingId": "0298f4fc-5e63-4406-95ef-e622f1f578a0",
    "type": "create",
    "results": {
        "totalCount": 2,
        "items": [
            {
                "action": "messageSent",
                "dtoTypeKey": "sendUsage",
                "instance": {
                    "trackingId": "e1ce1452-64a1-41f8-b9e0-becfbb60889e",
                    "udrFeedId": 1
                }
            },
            {
                "action": "created",
                "dtoTypeKey": "dataImportRequestTracking",
                "instance": {
                    "trackingId": "e1ce1452-64a1-41f8-b9e0-becfbb60889e",
                    "udrFeedId": 1
                }
            }
        ]
    }
}

Processing

Upon a successful request the usage records submitted will be:

Collected by the system and batched
Sent to be mediated in groups up to 1,000 records. Batches will be sent after waiting at most 30 seconds
During mediation a unique batch ID will be assigned to the data as an additional tracking resource for tracking usage record processing
The mediated data will then be passed to the rating engine to be rated
Any issues rating the usage will generate a rating exception that will be logged and can be reprocessed

Tracking Record Processing

The system provides tools to track import, mediation and rating activities to ensure the process completed successfully or to troubleshoot issues.

To ensure the usage data was imported and mediated successfully you can access the Setup / Mediation / Import History screen and switch the view to show API Import activity.

If API data import exceptions have occurred they will be listed.

The listed errors will indicate why the import failed so that you can address the issue. Clicking the icon will display the full import exception message. The trackingId returned in the API response can be used here to locate the data import exception.

If the usage records were imported and mediated without issue but failed to rate, then the Setup / Usage Rating / Exceptions screen will display usage exceptions. Once the issue that caused the rating exception to occur is fixed the same screen can be used to Reprocess the exception to attempt to rate the usage again.

v10 Documentation