External Form – Send and Receive File via Web Service Call (ASP.NET)Last Updated: 08/22/2018 Introduced in Version: 2.0
The External Form step was designed in Decisions to interact with forms using HTML methods or service calls. External Form step could be found in the Flow Designer in the Tool Box under the Forms[Interaction] category. This method can also pass data into the External Form and retrieve data from the external form. In this example we are going to pass text file from Decisions to an external ASP.NET web form, display its contents, edit its contents, send a newly edited text file back to Decisions and display edited content in Decisions’ form.
Navigate to the designer folder and create a flow. In the flow designer navigate to the Steps Tab and locate External Form Step. Locate Flows, Rules, Forms and Reports > Forms[Interaction] and select the External Form Step. On the right side of the flow designer or the quick add step, edit the settings for the External Form, under Common Properties and under Service Definition, locate Generate Service checkbox and check it. Notice, Service Name field and give the service a name.
If we select View Integration from the orange action panel on the top bar and a link with detail link for our External Form displays with useful information on how can we integrate our External Form with the Web Service we have just generated for this step.
Select Integration form top orange action bar.
Select Integration and view integration details.
When Integration Detail Page opens we click on TestFormService link to get information on how to integrate with our Service. (Note: TestFormService is Name that was used in this example while Generate Service checkbox was checked).
Next Page asks us which Operation we would like to get information about. And we click on GetFormData link…
On the next page we select WebService Option and click Show to see how we can integrate with this service…
Here we are able to see URL that we need to use when we Add Web Service Reference to our ASP.NET form…
Here, from the previous screenshot, we can see that in order to be able to get Data from this Service we need to pass userContext, flowTrackingId, and stepTrackingID into GetFormData method…
We can easily obtain flowTrackingId and stepTrackingID parameters in our Form from the URL sent to our Form from Decisions:
string stepId = Request.QueryString["stepTrackingId"];
string flowId = Request.QueryString["flowTrackingId"];
Next, in our External Form code we are going to define constant PasswordCredentialsUserContext:
TestService.PasswordCredentialsUserContext myContext = new TestService.PasswordCredentialsUserContext();
myContext.UserID = "email@example.com";
myContext.Password = "admin";
Finally, to be able to communicate with the Service we need to create a client. The previous screenshot shows us the way we can do it.
Back to our Flow set-up…
In the Service Definition section under Service Outcomes box, we have a warning saying that we must to include at least one outcome path. We click Add New link to define our Outcome Path.
In the resulting pop-up window we name our outcome path and click Add New link to add outcome parameter.
We provide our parameter with name and define its type as FileData because we are expecting text file to come back from our external form. When finished click Ok to save our parameter and return to our Outcome Path definition.
Our Outcome Path should look like this. We click Ok to save it and return back to the Flow Designer.
As well we need to send text file to our External Form. To accomplish it we click Add New link under Expose Data On Service box.
In the resulting pop-up window we name our parameter name and define its type as FileData. This variable will hold our file that we will send to our external form. Click Ok to save and close this Data Definition window.
Next, we need to provide our External Form step with Url to our external form. Under Url settings we select Constant from Mapping Type dropdown.
In the Value field we insert url to our external form.
Next, we need to pick a file that we want to sent to our external form. Our file’s content is as follow…
Under our TextFileSent variable’s settings we select Constant for Mapping Type. In the Value field we click file picker.
We browse to our file and click Open to add it as the value for our variable.
We are finished setting our External Form step. Next, in the Flow Designer’s ToolBox use search bar to locate Get String From Bytes step. We drag this step to our workspace.
Next, connect External Form’s outcome to Get String From Bytes step. Get String From Bytes step will convert the byte array content of file that we will receive back from our external form into String. Click Show Mapping Editor from Get String From Bytes’ options menu.
In the Mapping Editor we expand TextFileReceived and connect Contents field to bytes field. This completes our mapping for Get String From Bytes step. We click Ok to save and close Mapping Editor.
The form Display File were created for this example. We drag it to our workspace from ToolBox > Forms[Interactio] > [Current Folder].
Display File form was designed as follow. It has a Text Block element to display the content of the file we will receive back from external form. And it has Action Button Done to close this form.
Next, we connect the Outcome from Get String From Bytes step to our Display File form and the Outcome from Display File form to the flow’s end step. From our Display File form’s options select Show Mapping Editor.
In the Mapping Editor we connect GetStringFromBytes1_Output to fileToDisplay which is the name of our Text Block. This completes our mapping for Display File form. Click Ok to save and close mapping editor.
Finally, to make our Display File form work correctly we need to assign it.
In the Display File forms options in the right panel we locate Assignment Setup and change Assignment Type from InSession to Assigned.
Next, we need to add assignees. To accomplish it we click  in the Assignment menu.
In the resulting pop-up window under Assign To Users we click Add New link to add new account to the list.
Next we pick account and click Ok to add it to the list.
Click Done to save and close Assignment window.
This completes our Flow. From the top panel in the Flow Designer click Debug Flow to test our flow.
Note that in Decisions version 3.5 and above, you’ll need to click Test Flow to access the Debugger.
When debugger opens we can see that our file was passed to the external form. Our external form opens in a new window and our file’s content displayed.
We edit our text in the external form and click Done to submit form and send a new edited file back to Decisions.
The logic that is triggered when we press Done button in our External Form is that it creates new FileData instance that is Decisions type.
Next we populate this instance with all required fields including Content. Contents field of this Datatype requires the array of bites so we need to read our user’s input from the Form and then convert it into array of bytes. After we done we call our WebService again, but this time we use different method that includes our Datatype as one of the parameters:
protected void btnSend_Click(object sender, EventArgs e)
FileData myFile = new FileData();
myFile.FileName = "OutcomeText.txt";
myFile.Contents = ASCIIEncoding.ASCII.GetBytes(Request.Form["TextArea1"].ToCharArray());
TestFormServiceClient client = new TestFormServiceClient("BasicHttpBinding_ITestFormService");
FlowExecutionStateInstruction flowexecutionstateinstruction = client.CompleteComplete(myContext, flowId, stepId, myFile);
After we clicked Done in our external form it closed down and our flow continues to Display File form step. Assignment Notification pops up and the flow pauses. To continue our flow and open Display File form we click on the Assignment Notification and click Fill in Form Display File.
Display File form opens with the content of the file provided in the external form. We click Done to close this Display File form.
Our Flow’s Diagram shows that flow ran to the end step with no issues.
If we examine Data tab in the debugger we can see that the file that we picked was sent to the url address we provided for our external form…
Next, after we edited our file in the external form we can see that new file was sent back to Decisions from the external form…
Finally GetStringFromBytes step processed received file’s content and generated a string from the received byte array. Next, this string was simply passed to our Display File form’s text block.
Note: This will not work on in crossdomain environment. For example if Portal Base URL in format [machine name]/decisions/Primary and we try to call Form on localhost.
External Form used for this tutorial can be downloaded from here: Send and Receive File via Web Service Call (ASP.NET)