Definition from from https://www.odata.org/
OData (Open Data Protocol) is an ISO/IEC approved, OASIS standard that defines a set of best practices for building and consuming RESTful APIs. OData helps you focus on your business logic while building RESTful APIs without having to worry about the various approaches to define request and response headers, status codes, HTTP methods, URL conventions, media types, payload formats, query options, etc. OData also provides guidance for tracking changes, defining functions/actions for reusable procedures, and sending asynchronous/batch requests.
OData RESTful APIs are easy to consume. The OData metadata, a machine-readable description of the data model of the APIs, enables the creation of powerful generic client proxies and tools.
OData in Nimbus
The full history of completed Nimbus sessions (according to retention policy) and their attributes, is exposed through an OData interface. This means that in order to extract the historical data available for your tenant, it is necessary to connect with a connector that supports OData, and query such data using OData syntax. There are various tools that can be used to achieve this. One example is given in the Use Case - Connecting to OData via Postman.
💡An OData connector is also used for pulling data into Power BI – more on this below.
Preconditions: Accessing the OData feed
To access the Nimbus OData feed, you require:
- Any of the Reporting Roles assigned to your Nimbus User account. Note that the Organization Unit assigned to that account determines the data you can query with that account.
- Optionally a Contact Center license can be assigned to allow access to detailed User States reporting data. This is also needed so the User can access the Nimbus Portal Role as “User Supervisor” and perform Supervision tasks.
💡Best Practice: If you want to use a reporting Service account to access all OData data in Nimbus, it is best to configure it as follows:
- In your Azure AD, create a user account and call it "Reporting Service Account"
- In your Nimbus User Administration, add (= create) this User account so it can get Nimbus privileges assigned.
- On the General User Settings, add a Contact Center license.
- Within the User Administration, manually assign one of the following Portal Roles1
- User Supervisor (tenant level)
- Service Supervisor (tenant level)
- Service Owner (for every Enterprise Routing Service in MS-Teams)
1 Portal Roles – as their name implies – allow access for the user account to the Nimbus User Portal. As such, they also get Reporting Roles granted automatically alongside, with corresponding access to the Odata interface an Nimbus Reporting Session.
☝GDPR and Data Privacy Note
- Do not add Reporting Service Accounts to the Nimbus Tenant Administrator Security group, as this would grant access rights to all Tenant settings and allow further self-elevation.
- Also keep in mind that this User can access any Service in the Organization Units (OU) for which they have the role in, including any sub-OU structures and Services added thereunder at later points in time. A regular review of the Service account privileges is therefore highly advised.
Nimbus OData Connector URLs and Power BI Report
If you don't want to create your own methods to access OData the Nimbus Power BI Template – in conjunction with User credentials in one of the Nimbus Reporting Roles – also allows you access to the Nimbus OData feed. The OData connection is already pre-programmed for you in the Nimbus Power BI Template, so all you have to do, is add the URL relevant to your tenant, from the ones listed below.
Once connected via the provided OData URI ServiceUri, the User is presented with the set of entities available from the Nimbus Reporting Model .
INC Nimbus OData Connector URLs
| Switzerland 01 | https://api.ch-01.luware.cloud/v1/odata |
|---|---|
| Switzerland 02 | https://api.ch-02.luware.cloud/v1/odata |
| Germany 01 | https://api.dewe-01.luware.cloud/v1/odata |
| Germany 02 | https://api.dewe-02.luware.cloud/v1/odata |
| United Kingdom 01 | https://api.ukso-01.luware.cloud/v1/odata |
| Australia 01 | https://api.aue-01.luware.cloud/v1/odata |
| West Europe 01 | https://api.euwe-01.luware.cloud/v1/odata |
| East United States 01 | https://api.use-01.luware.cloud/v1/odata |
✅ Make sure to configure your web proxies to allow access to these domains or whitelist the complete *.luware.cloud domain.
💡Good to know: Our Nimbus Power BI Template will be regularly updated to make use the latest OData interface features. Make sure to check back on the Nimbus BI Template Release Notes to follow changes on our Nimbus Reporting Model and – in extension – the Template and Odata feed itself.
Odata Tables
Below is a list of OData tables available by connection string, as well as related Knowledge Base pages explaining the concepts behind.
| Odata Table | Where to find details | Related Knowledge Base pages |
|---|---|---|
| Callers | Slowly Changing Dimensions > Callers | - |
| DistributionAlgorithm | Static Dimensions > Distribution Algorithm | Task Queue and Distribution |
| DistributionPriorityType | Slowly Changing Dimensions > DistributionPriority | Task Priority |
| DistributionType | Static Dimensions > Distribution Type | Distribution Types |
| ModalityTypes | Static Dimensions > Modality | Supported Modalities |
| NotAvailableReasons | Slowly Changing Dimensions > NotAvailableReasons | Not Available Reasons |
| OpeningHoursTypes | Slowly Changing Dimensions > Opening Hours | Opening Hours |
| OrganizationUnits | Slowly Changing Dimensions > Organization Units | Organization Units |
| PrimaryCodes | Slowly Changing Dimensions > Codes | Codes |
| ResponsibilityProfiles | Slowly Changing Dimensions > ResponsibliltyProfiles | Responsibility Profiles |
| SecondaryCodes | Slowly Changing Dimensions > Codes | Codes |
| ServiceDataPermissions | - | Reporting Roles |
| ServiceSessionOutcomeGroups | Static Dimensions > Service Session Outcomes | Historical Sessions |
| ServiceSessionOutcomes | Static Dimensions > Service Session Outcomes | Historical Sessions |
| ServiceSessions | Facts > Service Sessions | Facts - Columns and Data Types |
| Services | Slowly Changing Dimensions > Services | Service Administration |
| ServiceSessionTags | Facts > Service Session Tags | Facts - Columns and Data Types |
| ServiceSessionTagStrings | Facts > Service Session Tag Strings | |
| Tags | Slowly Changing Dimensions > Tags | Tags |
| TaskDirections | Slowly Changing Dimensions > Tasks | Task Queue and Distribution / Outbound Call |
| TaskType |
Slowly Changing Dimensions > Tasks Static Dimensions > Task Type |
Task Queue and Distribution |
| TaskTypeGroups | Static Dimensions > Transfer Sessions | |
| TransferSessionDestinationTypes | Static Dimensions > Transfer Sessions | |
| TransferSessionOutcomes | Static Dimensions > Transfer Sessions | |
| TransferSessionTypes | Static Dimensions > Transfer Sessions | |
| TransferSessions | Static Dimensions > Transfer Sessions | |
| UnifiedSessions | Facts > Unified Sessions | Nimbus Reporting > Unified Sessions |
| UserDataPermissions | - | Reporting Roles |
| UserSessionActionGroups | Static Dimensions > User Session Outcomes | |
| UserSessionOutcomeHandledTexts | Static Dimensions > User Session Outcomes | |
| UserSessionOutcomes | Static Dimensions > User Session Outcomes | |
| UserSessions | Facts > User Sessions | Nimbus Reporting > User Sessions |
| UserStateTypes | Static Dimensions > User State Type | User States |
| UserStates | Facts > User States | |
| UserTransferActionTypes | Static Dimensions > Transfer Sessions | |
| Users | Slowly Changing Dimensions > Users | User Administration |
| UserSessionTags | Facts > User Session Tags | Facts - Columns and Data Types |
| UserSessionTagStrings | Facts > Service Session Tags |