Create a custom connector in Microsoft Power Automate to call the K2 Workflow REST API

KB002870

You can call the K2 Workflow REST API from Microsoft Power Automate to build custom flows that take advantage of both platforms. Microsoft Power Automate provides triggers from and connections to Microsoft 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.

Use this article to learn how to create a custom connection from Microsoft Power Automate 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 Power Automate, and links to How-To articles describing different integration scenarios.

At the time of writing, the K2 Workflow connection available from Microsoft Power Automate'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 Power Automate for details on using the K2 Workflow connection.

Prerequisites

To add a connection from Microsoft Power Automate to K2 and access the K2 workflow actions, you must:

• Have an active Microsoft 365 subscription with an Azure Active Directory subsription.
• 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 Power Automate 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.

1. 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 Power Automate
2. In Microsoft Power Automate expand Data and select Custom Connectors
   
3. Select the Import an OpenAPI file from the + New custom connector drop down
   
4. Specify a name for your custom connector, then click Import to load your K2 Workflow REST API JSON file
   
5. Add an icon and description to your custom connector, then click Security -> to continue
   
6. Select OAuth 2.0 from the Authentication type drop down
   
7. Select Azure Active Directory as the Identity Provider
8. 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).
9. 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:
   
10. 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
11. Click Definition -> to continue. (The JSON file you uploaded in Step 4 contains the full definition needed for integration with K2)
12. Click Create connector
    
13. Wait while the connector is created
14. Select the Security tab
15. Click Edit at the bottom of the page
16. Specify https://api.k2.com/ as the Resource URL, and copy the value for Redirect URL into a text file
    
17. Paste the Redirect URL from Step 16 as a new Reply URL in your AAD app's Reply URLs list in Azure Portal
    
18. Back in Microsoft Power Automate, click Update connector
    
19. Select the Test tab and click + New connection
    
20. Use your login details to authenticate the connection. Once authenticated, the connection is automatically selected in the Connections drop down
21. Select the GetWorkflows operation
22. Specify Startable as the type and click Test operation
    
23. The Response tab shows that the K2 Workflow REST API connection is working. From this point, you can use this custom connection in Microsoft Power Automate 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:

Tasks

You can use Microsoft Power Automate 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 Power Automate. 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 a flow only needs the number. See How to: Use the K2 Workflow REST Feed with Microsoft Power Automate 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.

Server Events

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 Power Automate 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

Workflows

You can start a K2 workflow from Microsoft Power Automate.  See How to: Use the K2 Workflow REST Feed with Microsoft Power Automate 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

Considerations

• 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 Power Automate 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.