Integrations for use in a Workflow Integration Step

Within a workflow, you and your app administrators have the option of using an Integration Step that will enable an app to send information from Kuali to an external system. The Integration Step allows you to select from a list of pre-configured integrations. .

The purpose of this guide is to walk a developer through creating this type of integration on the backend.

• Configuration
• How Data is Processed

Configuration

The following information includes instructions and recommendations to consider when configuring an integration for the workflow integration step. If you have not yet created an integration, refer to the  Create an API Integration article for more information on how to create an integration. 

When establishing an integration for the purpose of an integration step, the following settings should be used:

• Type of Integration: Use in Workflow
• HTTP Method: Select either PUT or POST.
  • POST is more commonly selected here. In order for the integration to work, you will need to set up an HTTP server that would be able to respond to this call.
• Integration URL: Input the URL to where the service will be called. Refer to the source's documentation for the source's URL. 
• Authentication Type: Provide the authentication type details to access (if any). Refer to your data source's documentation, and select the type of authentication stipulated. 
• Headers: If you need additional headers, you can configure them here.

Once the configuration is setup in Kuali, you will need to have a server running that will respond to these requests. When an app contains an integration step within the workflow and a submitted form reaches that step, it will call that service you set up here to send the data.

You can preview what the data being sent will look like by using the Workflow Simulator. When viewing the step in the simulator, you can click on the View JSON (Advanced) link and you will be able to view the JSON that will be sent. 

How Data is Processed

When a submitted form reaches the integration step in a workflow, it will send all of the data in an HTTP request that you've configured in System API Integrations.

The HTTP request will contain the Authorization header as well as the document data in the request body in JSON format. In addition to this, it will also include a header X-Response-URL.

When your service responds, the response must include a 200 response code (or anything in the 200-299 range) within 5 seconds if it was successful. If any other status code is returned, it will result in an error in the workflow, and it will need to be retried or skipped by an app administrator.

If your integration needs to take more than 5 seconds, there is an option for you to call back into Kuali at a later time. If that is the case, you must respond to the integration request with a 202 status code within 5 seconds. Then when your process is complete, make an HTTP POST request to the url provided on the X-Response-URL header. If you would like to provide a status code other than 200, you can set the X-Status-Code header with the value of the status code you would like to convey to Kuali.