Nintex Insights OData query cheat sheet

The Nintex Insights OData API uses the OData 4.0 protocol. For more information, see OData.org and Oasis: OData Version 4.0 Protocol. This topic describes the query string parameters and filter expressions you can use to customize your queries to return the required data.

Follow these steps to create the personal access token:

  1. On the upper-right of the Nintex Insights workspace home page, click Settings.
  2. Click Personal access token in the side navigation menu.
  3. In the Personal access token section, click Add token.
  4. Click Copy token and store the personal access token in a secure location.

    5. Caution: The personal access token cannot be viewed again after you close the dialog box. The personal access token is valid for one year.

  5. Click Close. The Personal access token is created and displayed in the list. The following details for the personal access token are displayed: Status, Created on, and Expires. The Add token button is disabled.
  1. On the upper-right of your Nintex Insights workspace home page, click Insights.
  2. Click Workflows in the side navigation menu.
  3. Search for or select and open the workflow for which you want to retrieve the OData API URL from the Workflows list.

    4. Note: Only workflows with Beacon actions will display the OData button.

  4. In the Workflow details section, click OData. The Workflow OData dialog box displays the OData API URLs for the following endpoints.
  1. Click Copy URL next to the respective fields to copy the required URL.

Query Nintex Insights OData API using Postman

You can use Postman to send GET requests to the Nintex InsightsOData API and receive the JSON data.

Retrieve data using Postman

  1. Open the Postman application and click Authorization.
  2. From the TYPE drop-down list, select Bearer Token.
  3. In the Token field, paste the Personal access token you copied as described in Step 1: Create a personal access token.
  4. Select the GET method from the drop-down list.
  5. Paste the OData API URL you copied as described in Step 2: Copy the OData API URL.
    6. Example: https://<Nintex Insights OData API URL>/WorkflowInstances:The WorkflowInstances endpoint provides a list of all workflow executions for the associated workflow. These would typically be modelled to represent a business event, for example, an expense claim. A workflow instance is an execution of the sequence of actions described by a workflow, which includes and has a time of initiation, length of time logged messages, and other metrics.
  1. Click Send.

The return payload is displayed in JSON format.

Query string parameters

System query options are query string parameters that control the amount and order of the data returned for the resource identified by the URL. The names of all system query options are prefixed with a $ (dollar) character.

Supported query string parameters

Query string parameter

Description

Example URL
$filter Filters a collection of resources that are addressed by a request URL. To add a filter to an OData URL, add $filter= to the end of the endpoint name. For more information, see Filter expressions. //https://na-odata.xyz.com/v1/odata/workflow/xxxxxxxx-xxxx-xxxx-xxxx- xxxxxxxxxxxx/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/xxxxxxxx-xxxx-xxxx-xxxx- xxxxxxxxxxxx/ProcessStages?$filter=workflowInstanceId eq '0fad4af3-7d5f-40af-84 6b-70c3bb6385ce'
$skip Returns the number of items in the queried collection that are to be skipped and not included in the result. //https://na-odata.xyz.com/v1/odata/workflow/xxxxxxxx-xxxx-xxxx-xxxx- xxxxxxxxxxxx/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/xxxxxxxx-xxxx-xxxx-xxxx- xxxxxxxxxxxx/ProcessStages?$skip=30
$top Returns the number of items in the queried collection to be included in the result. //https://na-odata.xyz.com/v1/odata/workflow/xxxxxxxx-xxxx-xxxx-xxxx- xxxxxxxxxxxx/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/xxxxxxxx-xxxx-xxxx-xxxx- xxxxxxxxxxxx/ProcessStages?$top=0

Filter expressions

You must use the appropriate notation for different data types with filter expressions.

  • String values must be delimited by single quotation marks.
  • Numeric values require no delimiters.
  • DateTime values must be delimited by single quotation marks and preceded by the word datetime. For example: datetime'2010-01-25T02:13:40.1374695Z'.

Filter operation

Term used
Equal eq
Select a range of values lt, gt
And and
Or or
Less than lt
Greater than gt
Greater than or equal to ge
Less than or equal to le
Different from (not equal) ne
To lower tolower
To upper toupper
Trim trim
Concatenate concat
Day day
Month month
Year year
Hour hour
Minute minute
Second second
Round round
Floor floor
Ceiling ceiling

Status codes

The OData API returns a status code in the response which can help you troubleshoot in case of errors. The following table describes the status codes:

Status

Code

Description
200 OK Request was successful.
400 Bad Request The request is not in the correct format. For more information, see the error message returned by the API.
403 Forbidden There is an authentication error. Verify if you are using a valid authentication token or credentials.
404 Not found The requested resource does not exist. Verify if you have entered the correct endpoint name.
405 Not allowed The requested resource action is not allowed. For example: This error might be caused due to a missing required parameter or incorrect syntax.
500 Internal Server Error The server has encountered an unexpected condition that does not allow successful parsing of the request.

For more information or if you need support, contact Nintex Support.