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

Last Updated: 08/22/2018 Introduced in Version: 2.0

OVERVIEW

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.

 

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.

Figure 1

 

 

 

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

 

clickOnTestFormService

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

getFormData

 

 

 

On the next page we select WebService Option and click Show to see how we can integrate with this service…

showWebService

Here we are able to see URL that we need to use when we Add Web Service Reference to our ASP.NET form…

webServiceInformationIntegration

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:

 Next, in our External Form code we are going to define constant PasswordCredentialsUserContext:

 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.

addOutcome

 

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

 

 

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

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

outcomeFinished

 

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

 

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

 

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

 

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

fileContent

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

pickTextFile

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

pickFileFromExplorer

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

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

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

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

dragDisplayFileForm

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

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

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

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

 

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

editAssignment

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

addnewAssignmentAcc

 

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

pickAccount

Click Done to save and close Assignment window.

assignmentCompleted

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 Shot

debugFlow

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

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

editedText

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:

 

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

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

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

flowRanWithNoIssues

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

 

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

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

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)

Additional Resources