Post to Flow BehaviorLast Updated: 07/21/2016 Introduced in Verision: 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.
REST service call requires passing parameters to the flow in a strictly structured xml encoded way. Post to Flow flow behavior was designed in Decisions to post data into the flow in the more flexible query key=value style. The key difference from the regular REST service call is that we do not have to know what data is expected to be input in our flow when we are making the call.
Example
We begin in Designer Folder by clicking Create Flow to create a new flow.
Next, we name our flow. Under the Behavior dropdown we select Post to Flow Behavior. We click Create to proceed to the Flow Designer.
Flow Designer opens with Flow Designer Wizard on the workspace. We use the Wizard’s Search bar to locate ForEach Step. We select it and click Add to add it to our Flow.
Next, the Wizard asks us to pick a collection ForEach Step will iterate through. We expand CallData and select QueryString, because it is a collection of all key – value pairs that are going to be passed to our flow. We click Add to map this collection to our ForEach Step.
We decided for this example to post to the flow two values using query string. To find these values among all query strings in the collection we can use rules. Here, we are going to create a first rule that will alert our flow when our ForEach Step returns us a query string with FirstName key. In the Wizard we expand Flows, Rules, Forms and Reports > Rules category and select [Pick or Create Rule] step. We give our step First Name Rule so it will reflect the task that needs to be done by this Rule. We click Add to add this step to our flow.
Next, our Wizard asks us to configure this step. We click Pick or Create Rule link on top of the pop-up window. We name our Rule and click Create to proceed to the Rule Designer. When Rule Designer opens we click Add New link to create new Rule Input Data.
We name our Input Data and search for DataPair type because it is the type of the QueryString our ForEach Step returns to us. We save and close our Rule Input Data editor.
Next, we click Add New Rule Step to start building our rule.
Our Rule is designed as follow. It simply checks if QueryString.Name contains FirstName string. When finished we save and close our Rule Designer to return back to our Flow Designer.
Back in the Flow Designer, if our First Name Rule finds desirable query string we are going to create a new variable to hold our First Name value. To do it we are going to use Wizard’s Search bar and locate Create or Copy Data step. We select it when found and click Add to add it to our Flow.
Next, the Wizard asks us to define Data for this step. We click Add to add new Data Definition.
We give our Data name and pick String type for it. Next, we click Ok to save and close our Data Definition window.
Next, we click Add to add this Data Definition to our Create or Copy Data step.
In the Flow Designer we select Show Mapping Editor from our Create or Copy Data step…
We are going to use Text Merge.Plain mapping type for our FirstNameOut field.
Next, we click Show Editor for Merged text field to build up the value that will be stored in our FirstNameOut variable.
In the Text Merge Editor we are going to expand Item data because it is a single query string returned to us from the ForEach step, and it is filtered for us with First Name Rule. We drag its Name and OutputValue fields to the workspace. These fields satisfy our String variable because they both String type. We click Ok to save and close Text Merge Editor.
Back in the Flow Designer we connect our flow steps as follows… Next, we select Show Mapping Editor for our First Name Rule step.
In the Mapping Editor we simply need to connect Item (which is a single QueryString from the collection ForEach Step iterates through) to our QueryString field in our Rule. We click Ok to save and close this Mapping Editor.
Our First Name Rule Step has second outcome named False. The Flow will execute on this path if FirstName query string was not find at current iteration loop. Here we need to create a second Rule to check if current query string contains LastName key which is the second value that is going to be passed to our flow through the query strings. We expand Flows, Rules, Forms and Reports > Rules category in the Flow Designer’s Wizard and select [Pick or Create Rule] step. We name this step Last Name Rule and click Add to add it to our Flow.
We create this Rule exactly the same way we have created First Name Rule in this tutorial except this time our rule will check if QueryString.Name contains LastName string in it.
When the rule is created and we are back to the Flow Designer’s Wizard we add another Create or Copy Data step just like we did it for the first Rule in this tutorial. We use Wizard’s Search bar to locate Create or Copy Data Step. When found we select it and click Add to add it to our Last Name Rule’s True outcome.
Next, we add new Data Definition for this Create or Copy Data Step. We name it and give it a String type. We click Ok to save and close Add DataDefinitions pop-up window.
Next, we click Add to add this Data Definition to our Create or Copy Data Step.
Back in our Flow Designer Wizard’s main menu we expand Steps In This Flow category and select ForEach Step. We click Connect to connect our Create or Copy Data Step’s Done outcome to ForEach Step.
Next, we select Show Mapping Editor for our Last Name Rule Step…
In the Mapping Editor we connect Item (Data field that is coming out of our ForEach Step) and connect it to our Rule’s QueryString field like we did for the First Name Rule in this tutorial.
Next, we connect our Flow’s outcomes as follow and select Show Mapping Editor from our second Create or Copy Data Step Option’s menu.
The mapping for this step is exactly the same as for the first Create or Copy Data step in this example. We select Merge Text.Plain for the mapping type and then click Show Editor. Text Merge Editor configured the same way because we know that our Last Name Rule step filters for us all query strings and passes to this step the one that we need. We save and close Mapping Editor when finished.
Our Flow needs to output some data to be shown in the Response when called. In the workspace we select the end step to configure its outputs. In the right panel locate Output configuration and click Add New link to add new output.
In the resulting pop-up window we name our output and give it a String type. We click Ok to save and close this pop-up window.
Mention that now we have an alert message informing us that we need to provide our Output with Mapping type and Value. We select Text Merge.Plain from Mapping type dropdown menu.
Next, we click Show Editor to build our Output’s value…
In the Text Merge Editor we use the outcomes from our Create or Copy Data steps and PayloadData. PayloadData is data that is going to be Posted as a message to our flow not using query string style. We click Ok to save and close Text Merge Editor.
The last step is to check Create Service checkbox from our flow’s settings to be able to call our flow using services.
This completes our flow… We can save and close it.
Back in the Designer Folder where our flow was created we locate its Thumbnail and select Action > Edit Post Settings.
In the resulting pop-up menu we check Use Named Session checkbox…
Next, we pick the desirable Named Session... We save and close this pop-up window.
To get the information on how to Post data into our flow using REST service we click Action > Run [Advanced] > Integration > View Integration Details from our flow’s Thumbnail.
The Integration page opens… We select Post Data Display Type and POST as a method. We click Show Service Api to see what is available. We are going to use the URL parameter to make a call.
Our test call is set up as follow…
And it gives us the following Response…
