Query the Reporting API

The Reporting 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.

Based on your region, use one of the following URLs to connect to the Reporting API.

Region	Reporting API URL
Australia	https://au-reporting.promapp.io/odata
United States	https://us-reporting.promapp.io/odata
Europe	https://eu-reporting.promapp.io/odata
Canada	https://ca-reporting.promapp.io/odata
UAE	https://ae-reporting.promapp.io/odata

Filtering data

To add a filter to an OData URL, add $filter= to the end of the endpoint name.

Example URL	Description
https://au-reporting.promapp.io/odata/processes?$filter=PublishState eq 'Published'	Returns all published processes.
https://au-reporting.promapp.io/odata/processes?$filter=PublishState eq 'Published' and ProcessGroupName eq 'Finance'	Returns all published processes in the 'Finance' process group.
https://au-reporting.promapp.io/odata/Incident?$filter=Status eq 'New'	Returns all newly created incidents, so you can action them.
https://au-reporting.promapp.io/odata/Incident?$filter=Priority eq 'High' and PortfolioName ne 'Supplier issue'	Returns all incidents filtered by High priority for all portfolio names except 'Supplier issue'.
https://au-reporting.promapp.io/odata/Incident?$filter=PortfolioName ne 'Supplier issue'	Returns all incidents filtered by the portfolio name except 'Supplier issue'.
https://au-reporting.promapp.io/odata/ProcessViews?filter=ViewDate gt 2023-01-01T00:00:00Z	Returns all process views after January 1st 2023.

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.

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.

You must follow the rules described in the following table when using query string parameters in your GET requests.

You can use the following query string parameters:

Expanding and selecting properties

To expand the collection fields, use the $expand string parameter.

For example:

• https://au-reporting.promapp.io/odata/Incident?$expand=IncidentFields
• https://au-reporting.promapp.io/odata/Incident?$expand=IncidentActionPlans
• https://au-reporting.promapp.io/odata/Incident?$expand=IncidentActions
• https://au-reporting.promapp.io/odata/Incident?$expand=IncidentInvestigations

To select specific properties, use the $select string parameter.

For example: https://au-reporting.promapp.io/odata/IncidentAction?$select=CreatedDate,ActionType

Ordering the results

To order the returned results by a particular field, use the $orderby string parameter.

For example: https://au-reporting.promapp.io/odata/IncidentAction?$orderby=CreatedDate desc

Status codes

The API returns a status code in the response which can help you troubleshoot in case of errors.

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.

Example: Querying using Postman

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

Before you begin

• Ensure you have the API Key. For more information, see Create API Key.
• Download Postman from: https://www.getpostman.com/downloads/.
• Install and set up Postman. For more information, see https://learning.getpostman.com/.
• Go through the details in the API Reference section to understand the endpoint URLs and available fields. You can use Query string parameters and Filtering data to customize the requests.

Retrieve data using Postman

1. Open the Postman application and open a new HTTP request.
2. Click the Authorization tab.
3. From the Type drop-down list, select Basic Auth.
   

   Note: If your configuration uses multiple tenants then you must use bearer token authorization.

   Bearer token Authorization

   Replace steps 4 and 5 with the following steps:

   1. From the TYPE drop-down list, select Bearer Token.

   2. In the Token field, paste the API Key. For more information, see Create API Key.

      

4. Specify Promaster as the Username.
5. In the Password field, paste the API Key. For more information, see Create API Key.

   

6. Ensure you have selected the GET method and then type the Query in the field.

Based on your region, use one of the following URLs to connect to the Reporting API.

Region	Reporting API URL
Australia	https://au-reporting.promapp.io/odata
United States	https://us-reporting.promapp.io/odata
Europe	https://eu-reporting.promapp.io/odata
Canada	https://ca-reporting.promapp.io/odata
UAE	https://ae-reporting.promapp.io/odata

For example:

• https://au-reporting.promapp.io/odata/Incident: Returns the summary of the latest status for all incidents recorded in Nintex Process Manager.
• https://au-reporting.promapp.io/odata/processes: Returns a summary of the latest process data in Nintex Process Manager.

• https://au-reporting.promapp.io/odata/Incident?$filter=Priority eq 'High' and
  Status Ne 'Deleted'&$expand=IncidentFields&$orderby=ReportedDate: Returns the summary of the latest status for all incidents recorded in Nintex Process Manager with the following conditions applied:

  • Filter by High Priority
  • Exclude Deleted incidents
  • Order by Reported Date
  • Expand IncidentFields collection fields

• https://au-reporting.promapp.com/odata/processes?$filter=PublishState eq 'InProgress'&$orderby=CreatedDate: Returns summary data for all processes in Nintex Process Manager with the following conditions applied:

  • Filter by publish state 'InProgress'

  • Order by Created Date

7. Click Send.

The return payload is displayed in JSON format.

Query the Reporting API

Note: The Authentication method for the Reporting API has changed. In Postman, use Basic Authentication instead of Bearer Token.