External Form - Send and Receive File via Web Service Call (ASP.NET)
  • Updated on 05 Mar 2019
  • 8 minutes to read
  • Print
  • Dark
    Light

External Form - Send and Receive File via Web Service Call (ASP.NET)

  • Print
  • Dark
    Light

OVERVIEW

TheExternal 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.

External Form used for this tutorial can be downloaded from here: Send and Receive File via Web Service Call (ASP.NET)

Example

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.
2018-08-17_134534.jpg

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. 
2018-08-17_140110.jpg

Select Integration and view integration details. 
2018-08-17_134743.jpg

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).

clickOnTestFormService.png

Next Page asks us which Operation we would like to get information about. And we click on GetFormData link...
getFormData.png

On the next page we select WebService Option and click Show to see how we can integrate with this service...
showWebService.png
Here we are able to see URL that we need to use when we Add Web Service Reference to our ASP.NET form...
webServiceInformationIntegration.png

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 = "admin@decisions.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 .
addOutcome1.png

In the resulting pop-up window we name our outcome path and click Add New link to add outcome parameter.completeOutcome.png

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.
defineOutcomeParam.png

Our Outcome Path should look like this. We click Ok to save it and return back to the Flow Designer.
outcomeFinished.png

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.
exposeDataFile.png

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.
exposeFileData.png

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.
defineURL.png

Next, we need to pick a file that we want to sent to our external form. Our file's content is as follow...
fileContent.png

Under our TextFileSent variable's settings we select Constant for Mapping Type . In the Value field we click file picker.
pickTextFile.png

We browse to our file and click Open to add it as the value for our variable.
pickFileFromExplorer.png

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.
dragGetStringFromBytes.png

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.
showMappingForGetString.png

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.
mappingForGetStringFromBytes.png

The formDisplay File were created for this example. We drag it to our workspace from ToolBox > Forms[Interactio] > [Current Folder].
dragDisplayFileForm.png

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.
displayFileFormView.png

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.
showMappingForForm.png

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.
mappingForForm.png

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 .
assignedForm.png

Next, we need to add assignees. To accomplish it we click [edit] in the Assignment menu.
editAssignment.png

In the resulting pop-up window underAssign To Users we click Add New link to add new account to the list.
addnewAssignmentAcc.png

Next we pick account and click Ok to add it to the list.
pickAccount.png

Click Done to save and close Assignment window.
assignmentCompleted.png

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.
3.5-Test-Flow-Shot3.png

debugFlow.png

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.
formOpenedInDebugger.png

We edit our text in the external form and click Done to submit form and send a new edited file back to Decisions .
editedText.png

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");
        client.Open();
        FlowExecutionStateInstruction flowexecutionstateinstruction = client.CompleteComplete(myContext, flowId, stepId, myFile);
        client.Close();
        Response.Write("<script>window.close()</script>");
    }

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.
formIsAssigned.png

Display File form opens with the content of the file provided in the external form. We click Done to close this Display File form.
decisionsFormOpens.png

Our Flow's Diagram shows that flow ran to the end step with no issues.
flowRanWithNoIssues.png

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...
externalFormInputs.png

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...
externalFormOutputs.png

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.
stringOutput.png

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 .
Was this article helpful?