Simployer Analytics API

How to use Analytics API

URL

OData endpoint:

• https://analytics-api.simployer.com/

Documentation/test site (for more information see Swagger UI section later in this document):

• https://analytics-api.simployer.com/swagger

Usage in Self-Service BI Tools

For specific SSBI tool, user should check if it supports OData Feed. Alternatively you can try to treat API as typical REST endpoints, but note, that API has a paging mechanism and a limit of results per query (see FAQ section for more details).

Authentication method

Analytics API supports SimplAuth authentication protocol.

See this page for more details: SimplAuth.

Excel, Power BI

Below you can find example how to authenticate and connect to Analytics API using Excel. For Power BI it is similar as both of these solutions use Power Query.

This is a good way to start your interaction with Analytics API. There's more detailed guide how to set up Power Query to authenticate and fetch data here: Connect API through Power Query.

Go to Data > Get Data > From Other Sources > From Web

In the popup select "Advanced" and provide necessary info like below:

New window should open with the data fetched:

Then you can drill down and turn that response into table.

OData Standard

Analytics API is a REST API based on open data protocol OData V4. This protocol allows users to use number of features:

• $filter - restricts the set of items returned. The maximum number of expressions is 100.
• $orderby - specifies the order in which items are returned.
• $top - limits the number of items returned from a collection.
• $skip - excludes the specified number of items of the queried collection from the result.
• $count - indicates whether the total count of items within a collection are returned in the result.
• $expand - indicates the related entities to be represented inline. The maximum depth is 2.
• $select - limits the properties returned in the result.

All of these features are described in OData documentation available here: https://www.odata.org/getting-started/basic-tutorial/. Below we will describe most common use cases for the solution.

Swagger UI

There is Swagger UI integrated in the solution which allows user to test the endpoints before connecting using any Self-Service BI solution.

Overall look at Swagger UI

All available endpoints are listed in Swagger UI, including corresponding schemas. Below there is an example with limited number of entities:

When expanding any of schemas, user will see detailed description of each property inside. If there are any references to other entities, user will also see them as expandable properties - see absences, immediateSupervisor, affiliationUnit, employees and directReports below. User can make use of these properties using $expand OData feature to include referenced entities to the result set.

Using Swagger UI

To use Swagger UI to make calls to the endpoints, user has to be authorized. To do so, he should use Authorize button just above endpoints declaration. User will be prompted to authorize.

Once authorized, user can test Analytics API endpoints using Try it out button (available when expanding each endpoint). Sample usage below:

According to the setup above, we want to fetch one Person (sk = 1) including his Affiliation Unit details. For both these entities we want to limit the properties returned to only few columns listed (this can be nested for $expand feature as shown above). Sample response from Analytics API below:

FAQ

I get Unauthorized (401) error when trying to connect to OData endpoint.

Please follow instructions specific to tool you’re using:

• Internet browser - Internet browser can not be used to utilize OData endpoint, it should be only utilized using specialized applications (Excel, Power BI, etc.). If you want to explore analytics model’s data or documentation using your browser, you can use Swagger UI which is available as separate endpoint (you can find it URL section of the document).
• any specialized BI tool - please refer to Excel, Power BI section of this document to check if you provided correct parameters when establishing the connection.
• Swagger UI - please make sure you provided correct token when clicking Authorize button before calling any endpoint.

Please make sure that you're targeting correct audience (https://analytics-api.simployer.com) when generating SimplAuth token. Tokens generated for different audience (e.g. HrConnect) won't be authorized in Analytics API.

Where can I find data model’s documentation?

Data model’s documentation is available in Swagger UI ("Schemas" paragraph, just below endpoints list).

How to use filter in the query?

To use filter feature, you have to use "$filter" keyword in your query. You can refer to the OData basic tutorial here, e.g. if you want to select only Person with first name "Anna", you can use this filter: v1/Person?$filter=firstName eq 'Anna'.

There are also other filter logical operators available, you can refer to OData URL Conventions document here to get a list of them.

How to include related entities in the results?

To use this feature, you have to use "$expand" keyword in your query. You can refer to the OData basic tutorial here. See Using Swagger UI section above, this approach can be used in any other tool capable to utilize OData endpoints. When you fetch data for entity that has some relationship set (e.g. Person as shown in one of previous paragraphs), you may also get extra columns in Excel (affiliationUnit in this example):

URL: https://analytics-api.simployer.com/v1/person?$filter=sk eq 1

but if you try to expand them by clicking, you will see that they’re not populated:

To fix it, you can include $expand keyword and state which entity you want to be expanded:

URL: https://analytics-api.simployer.com/v1/person?$filter=sk eq 1&$expand=affiliationUnit

My dataset is large, and it seems that I don’t get all the data from the endpoint. Why?

Our API use OData paging mechanism. It means that you can get limited number of records per one query. This limit is currently set to 100 000 rows. In general OData connectors (e.g. connector in Power BI) should handle it by their own. If you are utilizing API manually you have two options to handle it:

• use @odata.nextLink field from response to get URL for the next page of records
• use $skip keyword in your query to get the next page of records

I receive response code 429 (Too Many Requests)

Analytics API implements rate limiting rules to prevent abuse and maintain performance for all our clients - currently it allows for 30 requests each minute.