Simployer Analytics API

Analytics API is a REST API that enable our customers to read and then analyze their Simployer HRM data. Analytics API implements OData open standard. It can be accessed using various third party tools e.g. Excel, Power BI, as well as consumed by customer’s internal systems.

How to use Analytics API

URL

OData endpoint:

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

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 methods

Analytics API supports multiple authentication methods to support various integration tools. Users can choose to use:

  • X-ApiKey header and provide API key as it’s value
  • Basic authentication and provide API key as password, leaving user name empty
  • api-key query parameter and provide API key as parameter value. This means you put it into URL (i.e. https://analytics-api.simployer.com/v1/person?$top=1&api-key={api-key-here}). Note that it may lead to leakage of api-key. Web browsers save query parameters in browser history, it may also be logged by some network monitors, etc.

Excel, Power BI

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

Basic authentication

Go to Data > Get Data > From Other Sources > From OData Feed (Power BI: Home > Get Data > OData feed)

In the pop up, provide Analytics API endpoint URL and press OK: https://analytics-api.simployer.com/v1/person

User will be prompted for credentials. Switch to "Basic" tab and provide API key in the "Password" box, leaving "User name" empty:

Click "Connect" and the data should be fetched from the Analytics API.

Web API

Go to Data > Get Data > From Other Sources > Blank Query (Power BI: Home > Get Data > Blank Query)

In the formula bar, provide OData Feed function with proper Analytics API URL and press Enter:

= OData.Feed("https://analytics-api.simployer.com/v1/person", null, [ApiKeyName="api-key"])

User will be prompted for credentials.

Click "Edit Credentials", switch to "Web API" tab and provide API key in the "Key" box.

Click "Connect" and the data should be fetched from the Analytics API.

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 provide API key which is unique for each of our customer.

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 {"error":"Missing API key"} 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 (note: API key name "api-key" has to be provided, not only URL).
  • Swagger UI - please make sure you provided correct API key when clicking Authorize button before calling any endpoint.

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.

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):

= OData.Feed("https://analytics-api.simployer.com/v1/person?$filter=sk eq 1", null, [ApiKeyName="api-key"])

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:

= OData.Feed("https://analytics-api.simployer.com/v1/person?$filter=sk eq 1&$expand=affiliationUnit", null, [ApiKeyName="api-key"])

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

Documentation:

Analytics API