Usage Transparency Service¶

Usage Transparency (UTS) provides an API to get information about provider app usage and to import application usages by users/assets/tenants for billing, reporting, quota checking purposes.

UTS accepts all the data that is sent in the valid format and payload does not exceed the limit of usages count per request. In case the rules are configured for certain usage units, the corresponding usage data is verified as per the configuration. If the data verification fails, the data will be rejected and is not aggregated. Users can query for the status of the data sent using /usagesJobs endpoint. A rule is necessary for the usages to be billed.

This information can be displayed and analyzed using the Usage Transparency UI.

Access¶

For accessing this service you need to have the respective roles listed in Usage Transparency Service roles and scopes.

Features¶

Usage Transparency Service exposes its API for the following task:

• Usage: Sending application specific data to the UTS backend.
• Usage Jobs Traceability: Add usages of one or more tenants, users and application to UTS for storage and processing and get information about the query status, processing status and processing errors of the added usages.
• Aggregated monthly Usage: Get aggregated monthly usage data for provider tenant and consumer tenant.

UTS accepts the data only if the following checkpoints are verified:

1. A Rule has to be configured for the appname and usage unit.
2. Tenant claim in the token has to be either Developer tenant or Operator tenant.
3. Tenant claim in token and the tenantID in the Customer ID should be same or Tenant in the payload must be an IoT-tenant of an Operator and the app in the payload is provisioned to that IoT tenant.

Limitations¶

• The maximum usages that can be added to UTS in a single request is 200.
• The maximum jobs that can be queried at a time by a user is 1000.
• The amount of operations that can be performed at a time are limited.

Terms¶

• Rules: Rules are created in UTS to define which valid data will be accepted as usage.
• KPIS: KPI are created in UTS to define how the accepted usage data will be aggregated and made available for consumer.

Error codes¶

The following error codes might occur at any of the specified operations. Generic errors are prefixed with mdsp.core.generic..

• 204: noContent
• 400: invalidParameter
• 400: invalidRequestBodyProperty
• 400: missingParameter
• 400: missingRequestBodyProperty
• 401: unauthorized
• 403: forbidden
• 404: noMatch
• 413: payloadTooLarge
• 415: unsupportedMediaType
• 429: tooManyRequests
• 500: internalServerError

Example Scenario¶

A provider offers an application with which customers can connect industrial hardware devices to Insights Hub. They want to charge an initial fee for onboarding new hardware devices and a monthly fee per device. They use the Usage Transparency within the application to send user information to the central usage service, where it can be accessed using the UI when preparing the bills.