Configuring the Workflow REST API

Microsoft Azure Active Directory is now Microsoft Entra ID

Use the Workflow REST API to manage workflows, workflow instances, events, and tasks in custom ASP.NET pages, custom apps, and third party tools, such as Microsoft Power Automate.

The page shows the configuration options once the API is enabled.

For information on enabling and using Workflow REST API logging, see the Workflow REST API and OData API Logging topic in the Installation and Configuration Guide.
The REST Broker cannot be used to interact with the Workflow REST API
See the following resources for more information:

You must turn on the Workflow API feature before using the service. Click the Slider to activate the Workflow REST API preview.

Select the Workflow REST API version to use on your system. Selecting the version changes the value of the Workflow API URLs, all other settings apply globally to all versions of the endpoint. This provides backward compatibility for any 3rd party solutions developed using earlier versions of the API. The version is reflected in the Swagger URL and Base URL.

The Swagger file describes the Workflow REST endpoints to third party software, such as Microsoft Power Automate. Click on Copy to copy the Swagger file URL address to your clipboard.

Click on Open Link to open the workflow Api swagger page and access the list of operations, tasks, and workflow functions.

Click on Download to open a new web page displaying the JSON swagger file. Then use File - Save As from your browser to save the descriptor file. You can now use the descriptor file in a third party application, like Microsoft Power Automate.

The swagger file is instance specific, and describes the current instance of the server.

Swagger Page

Use the swagger page to test, use, or familiarize yourself with the endpoint functions.

Function Description
Operations
GET op/{operation} This function is reserved for system use
Server Events
GET serverEvents/{serialNumber} Returns a list of server events available to you from the server. Use this function to identify the serialNumber value to be used in the following function
POST serverEvents/{serialNumber}/finish Completes the server event identified by the serialNumber. Enter Data fields, XML fields, or Item References as required in the JSON
Tasks
GET tasks Returns a list of tasks assigned to you. You can use this function to identify the serial number values used in the following functions
GET tasks/{serialNumber} Returns a description of the task associated with the serial number
GET tasks/{serialNumber}/actions Returns a list of actions available for the task associated with the serial number
POST tasks/{serialNumber}/actions/redirect Redirects the task to the specified user
POST tasks/{serialNumber}/actions/sleep Sends the task into sleep mode for the duration specified. Only one of the body functions can be used, either SleepFor: nnn or SleepUntil : DateTime
POST tasks/{serialNumber}/actions/release Releases an Open task back to the assignment pool
POST tasks/{serialNumber}/actions/wake Returns a sleeping task back to Open status
POST tasks/{serialNumber}/actions/assign Assigns the task to the specified user
POST tasks/{serialNumber}/actions/{customAction} Performs the specified workflow action. Use the GET tasks/{serialNumber}/actions function to list the possible actions of the task
Workflows
GET workFlows Returns a list of workflows available to you
GET workFlows/{id} Returns in JSON format the parameters of the specified workflow. Use this function to identify Datafield, XML fields, and Reference Items needed in the POST workflows/{id} function
POST workFlows/{id} Starts a new instance of the specified workflow. You can send specific properties identified in the GET workflows/{id} function
GET workFlows/{id}/schema Returns the parameters of the specified workflow in JSON String Format, ready for use in third party applications, like Microsoft Power Automate

You can use the Try it out! button on the swagger page to get a JSON response from the web service. For example, the Get Workflows GET function will return the number of workflows on the server, and give the id, defaultVersionID, name, folder, and systemName values for each workflow.

A POST swagger function may require parameters and instance data. For example, the Start Workfow POST function needs the workflow id number. Body values can be entered; use the Example Value JSON examples to guide your construction, or use empty brackets {} to enter no data. Add Data fields, XML fields, and Item References where needed. A full schema of a workflow is available from the GET workflows/{id} function. The GET workflows/{id}/schema function provides JSON schema formatted as a string ready for Microsoft Power Automate.

The Base URL contains the server address followed by the API path and version, such as https://k2.denallix.com/api/workflow/v1. Click on the Copy "@" icon to copy the Workflow REST API endpoint URL.

Add domains to the CORS list to enable those Apps or Web services to use the Workflow REST API calls.

Click on the plus icon to add a new domain. Select a domain and click on the trash can to delete it. Click on the refresh icon to reload the list of allowed domains.

When adding and removing URLs from the CORS list, you must click the Apply Changes button for the changes to take effect.

  • If you leave the page without clicking Apply Changes, the changes will be lost.
  • If you click on the Refresh icon before clicking Apply Changes, a warning popup display
    • If you click ok, the changes (addition or removal) will be lost.
    • If you click cancel, the pop up will close and nothing will happen.

The service uses Basic and OAuth Authentication.

You cannot log in to the Workflow REST API and the SmartObject OData API using Basic Authentication with an Azure Active Directory account that has Multi-Factor Authentication (MFA) enabled. Turn off Multi-Factor Authentication before granting consent. You can then turn MFA back on once consent has been granted.

You must use a custom connector when using OAuth for authentication.

If you are authenticating with Azure Active Directory (AAD), you will need to grant consent for Nintex K2 to access AAD by clicking the SETUP AAD CONSENT button on the Integration > APIs node. See AAD Consent for more information.

For more information see Authentication with the Workflow REST API.