Usage Transparency Service – Samples¶

Adding usages to UTS¶

This API can be used by operators and applications to create a job that adds application specific usages (for example, the number of created report pages, assets configured, etc.) of multiple tenants and users to UTS.

Add usages to UTS using the following endpoint:

POST /usagesJobs

Sample Request:

{
  "users": [
    {
      "tenantId": "siemenshcops",
      "userId": "john.doe@healthcare.siemens.com",
      "userType": "user",
      "resources": [
        {
          "application": "manage-my-machines",
          "alias": "analyze-my-performance",
          "resource": "asset-id-1",
          "usages": [
            {
              "value": 20,
              "unit": "mmm-recurring-unit",
              "datetime": "2011-07-14T19:43:37Z"
            }
          ]
        }
      ]
    }
  ]
}

Sample Response:

{
  "id": "35a4cb01-2497-4191-ad1c-551a1942c409-20190520131",
  "time": "2011-07-14T19:43:37Z",
  "status": "ACCEPTED",
  "usagesCount": 7
}

Retrieving query status¶

This API gives the overall status summary of the jobs and optionally the usages added using /UsagesJobs or /usages APIs. Description of job status is as follows:

• ACCEPTED: A job is created and the usages has been accepted.
• INPROGRESS: Processing is on-going for at least one of the usages added by the job.
• ERRORS: There is at least one error encountered while processing the usages.
• COMPLETED: All the processes applicable to the usages have been completed.

Retrieve query status from UTS using the following endpoint:

GET /usagesJobs

Sample Response:

{
  "jobs": [
    {
      "id": "35a4cb01-2497-4191-ad1c-551a1942c409-20190520131",
      "time": "2011-07-14T19:43:37Z",
      "status": "ACCEPTED",
      "usagesCount": 7
    }
  ],
  "page": {
    "number": 2,
    "size": 10,
    "totalElements": 40,
    "totalPages": 4
  }
}

Retrieving query status of usages¶

This API gives the status summary of the usages added using /UsagesJobs or /usages APIs. Description of Usages status is as follows:

• ACCEPTED: Usages have been accepted.
• VERIFIED: Usages have been verified against the rules configured in rule engine, if applicable.
• VERIFICATIONFAILED: Verification of at least one of the usages is failed.
• NOVERIFICATION: No applicable rule was found and hence no verification was done.
• AGGREGATED: Usages have been aggregated into a running daily aggregate value based on the aggregation function defined in rule. In case no rule is applicable, default aggregation function 'SUM' is used. The aggregation is performed every hour and the daily aggregate is updated. Once aggregated, the UTS is queried to report the usages through UI or data endpoints.
• SENTFORBILLING: If billing is enabled for the usages, the data has been sent successfully to the billing system.
• FAILEDTOSENDFORBILLING: Errors were encountered while sending the data to billing. These could be network issues or other internal errors.
• RECEIVEDFORBILLING: Data sent for billing is verified to be received in the billing system.

Retrieve query status of the usages using the following endpoint:

GET /usagesJobs/{id}

Sample Response:

{
  "id": "35a4cb01-2497-4191-ad1c-551a1942c409-20190520131",
  "time": "2011-07-14T19:43:37Z",
  "status": "ACCEPTED",
  "usagesCount": 7,
  "usagesSummary": [
    {
      "application": "manage-my-machine",
      "unit": "mm-onboarding-unit",
      "usagesCount": 2,
      "processStatus": "ACCEPTED"
    }
  ],
  "page": {
    "number": 2,
    "size": 10,
    "totalElements": 40,
    "totalPages": 4
  }
}

Retrieving processing errors¶

This API gives the processing errors associated with the set of usages that were received by the identified job. In case of 'Verification Errors’, the list of usages that failed the verification is part of the errors. In case of 'Billing Errors’, billing ids are part of the error data. To resolve the issues, contact the support team.

Retrieve processing errors for the usages using the following endpoint:

GET /usagesJobs/{id}/errors

Sample Response:

{
  "errors": [
    {
      "code": "mdsp.<provider>.<service/app>.<errorid>",
      "message": "<error message in english>",
      "messageParameters": [
        {
          "name": "name1",
          "value": "value1"
        }
      ],
      "logref": "0bff7e7a-cd25-4576-9908-4180ef086174",
      "errorType": "ValidationError",
      "info": "http://developer.mindsphere.io/uts/documentation/billing"
    }
  ],
  "page": {
    "number": 2,
    "size": 10,
    "totalElements": 40,
    "totalPages": 4
  }
}