You can call the K2 Workflow REST API from Microsoft Flow to build custom flows that take advantage of both platforms. Microsoft Flow provides triggers from and connections to Office 365 applications and services. Combining those with K2 workflows allows you to, for example, post a message to your Microsoft Teams group, or start a workflow when a SharePoint list item is created, or redirect a K2 task when an email arrives in an Outlook folder.
The screenshots and instructions for third-party software are accurate at the time of publication. Third-party vendors may have changed or updated aspects of their systems (such as user interfaces, functionality, and security). As a result, this content may be outdated.
Use this article to learn how to create a custom connection from Microsoft Flow to the K2 Workflow REST API that uses OAuth for authorization. At the end of this article, there is a list of available workflow actions defined by the API to help you understand the workflow actions you can use when integrating with Microsoft Flow, and links to How-To articles describing different integration scenarios.
At the time of writing, the K2 Workflow
connection available from Microsoft Flow's Connections
listing uses Basic Authentication. You cannot log in to the Workflow REST API using Basic Authentication with an Azure tenant that has Multi-Factor Authentication (MFA) enabled. If you have MFA enabled, you must use the custom connection configured with OAuth as described in this article.
Use Basic Authentication when you want to test with static credentials, such as for a temporary, proof-of-concept exercise. See the article Using the K2 Workflow Connector in Microsoft Flow
for details on using the K2 Workflow connection.
To add a connection from Microsoft Flow to K2 and access the K2 workflow actions, you must:
- Have an active Office 365 subscription with access to build flows in Microsoft Flow.
- Enable the Workflow REST API in K2 Management site. See Configuring the Workflow REST API for more information.
- Configure your Azure Active Directory (AAD) app to include the K2 API permission which enables the proper OAuth token flow. See Configure AAD and K2 Services for Inbound OAuth for more information.
- In February 2019, Microsoft changed Custom Connectors in MS Flow from a Standard Feature to a Premium Feature, but this change was not yet enforced. As of 31 January 2020, this requirement is enforced, which means you may need a Premium Microsoft subscription to use custom connectors.
Add a K2 Workflow API Custom Connection
Use the following steps to configure a K2 Workflow REST API custom connection with OAuth.
- Launch the K2 Management site and browse to Integration > K2 APIs > Workflow REST API, and save the K2 Workflow REST API JSON file. See Configuring the Workflow REST API for detailed information. You use this file to create the custom connector in Microsoft Flow
- In Microsoft Flow click the settings icon and select Custom Connectors
- Select the Import an OpenAPI file from the + Create custom connector drop down
- Specify a name for your custom connector, then click Import to load your K2 Workflow REST API JSON file
- Add an icon and description to your custom connector, then click Security -> to continue
- Select OAuth 2.0 from the Authentication type drop down
- Keep Generic Oauth 2 as the Identity Provider
- Specify your Client id and Client secret from your AAD app (see Configure AAD and K2 Services for Inbound OAuth for information on getting these values).
- Specify your Authorization URL, Token URL, and Refresh URL. If you don't already know these values, click the Endpoints toolbar button on the Azure Portal > Azure Active Directory > App Registrations page, or follow the pattern in the following image, replacing the blurred values with values from your environment:
- Leave Scope empty
Once your custom connector is created you must return to the Security tab to specify the Resource URL, and copy the Redirect URL to add to your AAD app's Reply URLs list
- Click Definition -> to continue. (The JSON file you uploaded in Step 4 contains the full definition needed for integration with K2)
- Click Create connector
- Wait while the connector is created
- Select the Security tab
- Click Edit at the bottom of the page
- Specify https://api.k2.com/ as the Resource URL, and copy the value for Redirect URL into a text file
- Paste the Redirect URL from Step 16 as a new Reply URL in your AAD app's Reply URLs list in Azure Portal
- Back in Microsoft Flow, click Update connector
- Select the Test tab and click + New connection
- Use your login details to authenticate the connection. Once authenticated, the connection is automaically selected in the Connections drop down
- Select the GetWorkflows operation
- Specify Startable as the type and click Test operation
- The Response tab shows that the K2 Workflow REST API connection is working. From this point, you can use this custom connection in Microsoft Flow events to integrate with K2 workflows.
Available K2 Actions
The following actions are available on the K2 Workflow REST API endpoint and described below the image in three parts: Tasks, Server Events, and Workflows:
You can use Microsoft Flow to action and manage K2 tasks. Integration with a task requires its unique serial number. For example, when using an Outlook trigger, you can configure the subject of the task notification in your workflow definition to send the serial number to Microsoft Flow. When creating your task notification, use the task SerialNumber field from the Workflow Context Browser in a Replace function to remove the SN= portion of the serial number context as Flow only needs the number. See How to: Use the K2 Workflow REST Feed with Microsoft Flow to Redirect a K2 Task for an example of redirecting a task.
The following task-related actions are available:
- Get Tasks: Returns a list of tasks
- Get Task: Returns information about a specific task
- Get Task Actions: Returns a list of actions available for the task, such as Approve or Decline as defined in the workflow
- Redirect Task: Sends the selected task to another person for completion. Once you redirect a task, it is removed from your task list and appears on the other person's task list
- Sleep Task: Pauses or suspends a work item for either the specified duration or until the specified date
- Release Task: Sends the task back to be available to someone else, such as someone you've shared the task with or some other recipient of the task
- Wake Task: Returns a sleeping task to active
- Assign Task: Sends the selected task to another person for completion
- Action Task: Completes the action. You can use the Get Task Actions action to get the list of actions available, then use this action to complete the task.
The POST task actions (redirect, sleep, release, wake, assign, and action) have default and further HTTP Status options. See Workflow REST API: Tasks for more information.
You can use server events to interact with a K2 workflow step. Configure your flow to wait for the workflow step server event which sends a JSON string. Use the information from the JSON string to perform other flow tasks, and when they are complete, use the Finish Server Event to notify K2 that the workflow step is complete and the K2 workflow can continue. See How to: Use the K2 Workflow REST API Server Events in Microsoft Flow for examples of using server events.
The following server event actions are available:
- Get Server Event: Returns a server event JSON definition string
- Finish Server Event: Sends a finish response to an async server task awaiting a response
You can start a K2 workflow from Microsoft Flow. See How to: Use the K2 Workflow REST Feed with Microsoft Flow to Start a Workflow for examples of using SharePoint and Outlook triggers to start a workflow.
The following workflow actions are available:
- Get Workflows: Returns a list of available K2 workflows
- Get Workflow: Returns the workflow metadata definition from a specific workflow
- Start Workflow: Creates and starts a new instance of the workflow
- You must enable the Workflow API in K2 Management site before the API will be available for integration. See Configuring the Workflow REST API for more information.
- While setting up a custom connection is recommended, it is not necessary for testing purposes. See Using the K2 Workflow Connector in Microsoft Flow for more information on using the built-in K2 Workflow Connector.
- You cannot log in to the Workflow REST API using Basic Authentication with an Azure Active Directory account that has Multi-Factor Authentication (MFA) enabled. If you have MFA enabled, you must use OAuth to connect to the K2 Workflow REST API as described in this article.