Overview
We are going to cover how to add an integration action to our workflow.
Example Scenario
In this example scenario, we are going to pretend to be realtors who are going to be adding house listings to a backend table containing all of the houses we are going to sell.
There needs to be a table that is created somewhere in the admin system that we will add to. For this demonstration, these are the table schema details:
Field | Type | Description |
|---|---|---|
Record Key | string | Default Record Identifier |
Street Name | string | Street Name of House |
City | string | City of House |
State | string | State of House |
ZIP | string | ZIP Code of House |
Color | string | Color of House |
SqFt | integer | Square Feet of House |
All fields are required to be entered for a record to be created in this scenario. The data table that will be referenced throughout the rest of this demonstration will be called Integration Action DEMO (Adam).
Creating an Integration Action
We need to create an integration action that will allow us to add a record to the data table. This integration action will be referenced somewhere later in our workflow. When you create your integration action, make sure that you choose the correct action request type. In this scenario, we are going to be performing a data table request.
Once this is saved, navigate to the REQUEST tab. This is where we can set the action/request type and specify which data table we are modifying. In this scenario, we are going to be Adding a record to the table using our form, so we need to make sure to select that request type.
The last part of setting our integration action, will be to specify the values that will be gathered from the table. The type of each field will be input parameters, which means that the value will come from an input on our form.
Each value will need to be set manually. You can easily set an input parameter by clicking "Add an Input Parameter" - within this window, all you need to do is select SAVE and your input parameter will be ready to go.
Once all of your input parameters are set, your REQUEST window should look like this:
It may be valuable to test the integration action prior to linking it to your workflow. When you test the action, a record will be added to the data table (you may want to delete this later). Navigate to the TEST tab and enter values that make sense. For the record key, you can enter pretty much anything - we will specify what this value needs to be later.
After you run your test, you should see something like this:
In my data table, I can see that the record was successfully added:
Setting Up the Main Form
We must set up our form so that the fields that we want to enter into the table, are present. This is crucial because we need to map our fields to the integration action.
Recall that we need to add the following fields
Street Name
City
State
ZIP
Color
SqFt
Record - Key (DO NOT ADD YET)
After adding these fields to your form you should see something that looks like the following:
REMINDER: Make sure to name your fields something that corresponds to the field in the table, it will make future steps easier.
Adding the Integration Action to the Workflow
Now that we have successfully created an integration action, and created a simple form with some fields, we need to link this to our workflow.
The first step is going to be creating a transaction that we can link to a button on our main form. We can call this transaction "Add House" or something similar. We do not need to connect this transaction to any status, because we are going to link this to a button later.
The transaction will now show up in the transaction pane on the left side of the screen:
Now that we have the transaction created, we can add the integration action. On the right side of the screen (with the transaction selected) we can add an integration action by selecting the "Integration Actions" tab, and hitting the "+" button.
Once the "+" is selected, find the integration action that was created earlier
This is when it's important to make sure that you have the main form set up correctly. We are going to make sure that we map each form field to the input parameter on the integration action.
Here is an example for the Street Name field. First, select the calculation option (Σ) for the row that has "Street-Name*" listed on the backend field. Once inside the calculation window, we need to proceed to set the value equal to the value of the field on the form.
Change "constant" to "field"
Switch the context from Transition to Form
Select the street field
Select "OK"
Once you have done this, you should see "string calculation" under the value column for this field:
Now, repeat this for the rest of the fields EXCEPT Record-Key. Once you have all of those complete, your integration action window should look like the following:
The reason we waited for Record Key is to explain what the purpose of this field is, and understand an option for the value. A record key is a UNIQUE key that is specific to a row in the backend data table. It would be really complicated to memorize which key values that we have already used, so it may be valuable to create a record key as a combination of a few fields. For our record key, we are going to combine the Street, City, State, and SqFt fields. In the real world, there may another set-up for the record key, but this way we can try and ensure that we are not going to duplicate keys.
To set that calculation we need to do the following within the Record Key calculation
Change "constant" to "join-list-of-strings"
Set the join(unset) constant to a single dash ("-")
Click on the list option
In the first constant, add the Street field (making sure to switch context from Transition to Form)
Change "constant" to "field"
In the second constant, add the City field (making sure to switch context from Transition to Form)
Change "constant" to "field"
Hit the "+" button. Add the State field (making sure to switch context from Transition to Form)
Change 'constant" to "field"
Hit the "+" button. Change the integer constant to SqFt field (making sure to switch context from Transition to Form)
Change "constant" to "format-integer" and leave all the fields alone besides the first integer option.
After completing all of these things, your calculation should look something like this:
This may look complex, but remember, all we're doing is concatenating 4 fields using a "-" here. After you complete your Record Key calculation, your integration action should look like the following:
Once we click "OK" we can see that an integration action was successfully added.
Linking the Integration Action to a Button
Now that we have our integration action setup within our "Add House" transaction, we need a way to connect this to the main form. Let's create a Workflow Transition Button on our form. There are some horizontal spaces and additional styling set on the button, but after adding the button (before connecting the integration action) our form should look like the following:
If you need help on styling your button, make sure to view the Styling a Button document.
Once we have the button in the form, we must change the settings to link our integration action. All this really means is that when we run our form and click the button, something is actually going to happen. Navigate to the Control Properties - there will be an option to set the Transition Name. Select the Add House option.
Once we have the transition connected to the button, we are ready to proceed to testing to see if the button actually adds a record to the form.
Testing the Integration Action in Form Inbox
Let's start by creating a new version of our form:
Enter some sample values into the form:
Click the "Add Record" button and select "OK"
This should have worked! To double check, let's go back and check our backend data table.
We can see our record added to the top of the table. We can also see that the Record Key successfully concatenated our Street Name, City, State, and SqFt fields.