Calling a flow as a REST Service

Last Updated: 10/29/2018 Introduced in Version: 2.0

Summary

A flow can be made into a REST web service that supports either HTTP GET or POST methods. REST calls to a flow require either (1) valid user session ID, or (2) valid user authentication ID. The REST Service API shows instructions for calling the flow, as well as the output. The Actions menu for the flow provides REST service call URLs that are already populated with the necessary parameters.

 

Example

In this example we are going to use POST method to pass data into the flow using REST service call.

We begin in the Designer Folder by clicking Create Flow to create a new flow.

Next, we name the flow and click Create to proceed to the Flow Designer.

We need to create variables or data structures for our flow input to hold data that will be Posted to the flow.

In the Flow Designer select start step on the workspace. In the right panel we locate Flow Input Data box and click Add New link to add new input data to our flow.

 

We name our first input FirstName and select String type for it. In the same way we add second input and name it LastName. So our flow expecting two strings to be passed in.

 

Next, in the Flow Settings we check Create Service checkbox to create a new service for our flow.

On the workspace we connect flow’s start step to the end step. We select the end step to configure the output.

Under the Output options, we click Add New link to add new output data structure.

We name our Output and select String for its type. From the Mapping Type drop-down menu, we select Text Merge.Plain.

Next, we click Show Editor for Merged Text option.

 

We configure our Merged Text as follow. Click Ok when finished to save and close Editor for Merged Text.

This completes our flow. We can save and close it.

 

Back in the Designer Folder we locate the Thumbnail for our flow. On the thumbnail, we click Action >

Run [Advanced] > Integration > View Integration Details.

Note:

1. If you are calling a flow that may go async (assigning a task to someone or running a fire and forget flow) this result will be a flow tracking id instead of your expected result.
2. If you call the flow as a SOAP service, you will ALWAYS get flow tracking id which is different behavior than REST.

Integration Details for Services that we have created previously in this example for our flow opens.

We are going to use Named Session for the Credentials. In the Display Settings we leave REST option and click Show Service Api button to view settings that are needed to make a successful call to the service.

showServiceIntegration

Settings are being displayed on the same page. We are going to use POST method so we look at Call via POST section. We are going to need the URL and also we need to pass the parameters provided in this section. Mention that there is a XML Serialized Representation of Inputs. Our flow will accept the parameters only in this structured way or we will get a service error. Also we can see the Expected Output which is as well in XML. In this example, we are expecting outcome named Done with a variable named Output, and this variable will hold our string that we built in Merge Text Editor.

 

Authentication Credentials:

UserId/PW – Username and Password Credentials
Guest – We have a special Guest Account that can be enabled and access to folders can be granted to this user.
Current User Authentication – With this option System encrypts current user credentials into a String and passes it into the URL as a value for the authid parameter. This type of User Context is good to use when we want users to make service calls with our current Permissions.
Login – This will present a Login Screen to the User and not recommended for API
Session/Named Sessions – This is our most recommended approach for API Calls.

See the attached link:

Creating a Named Session

Next, we are going to test our call… Mention that we are passing desirable values in the parameters. Our flow will use those values after they are posted into flow.

testCall

And we are getting successful Response from the service with the desirable output…

result

Additional Resources