Once you set up your app, the next step is to populate it with templates. They are the workflows composed of different steps which represent activities, like Actions and Triggers. Template building is relatively easier than app creation. The purpose of this article is to walk you through the basics of the template creation process. Your dashboard, under the Templates tab, displays templates you have already created along with a Create a Template button. Click it and you will be directed to the New Template page. Time to define template workflow.
Template Workflow
Every template consists of two or more steps in a particular sequence. These steps could be any type of activities that you have previously created and configured during the app creation. There are a bunch of activities that you can choose from like Actions, Triggers, Queries, etc. These will be discussed in detail in this chapter.
A step is added by choosing the Add Step button in the template builder.
Clicking on it will give you multiple options that you can use as steps. These options look like this:
The above steps from left to right are:
Trigger, Action, Query, Adapter, Filter, Loop, Setup, IF Condition, Scheduler.
Note that only the Trigger and the Action step's details will be discussed in this article, the rest of the steps have their own help guides that you can visit by clicking on the respective embedded links.
Once you select a step, that step will be added to your template and a detailed configuration window for that step will be opened, as shown below.
On the top right side of this box are two buttons.
The toggle button controls the visibility of the respective step. If you turn this button on, this step will be visible to the user at the time of integration.
The second green button gives you the option to collapse a step. Clicking on it closes the details of the step and shrinks it to only its name (activity type and app name). This allows you to save space and make sense of the workflow between different steps. A collapsed step will look like this:
Hovering your mouse over a collapsed step will also show you a few icons as shown below.
The numbered icons work as follows:
- Edit step: Expands the template step and allows you to configure the details.
- Remove step: Deletes the corresponding step.
- Add step: Adds a child step below the corresponding step.
Many activities can have multiple child steps. It depends on you how many steps you want to add and how you want to compose your template’s algorithm.
The trigger step
The first step of building your template is usually to add a trigger. To do so you need to complete the following steps which are:
- Select App: Select from the list of apps as shown below. Cannot find the app you're looking for? Contact us at hello@integry.io!
- Select Trigger: Select from the list of triggers of the selected app as shown below. Cannot find the trigger you're looking for? Contact us at hello@integry.io!
Configuring Template Fields
The data that needs to be provided for this particular trigger to work is defined through trigger fields. The Activity Fields configured while setting up your app will display here. The figure below shows the fields. The important points are highlighted and numbered for your understanding.
In the example above, we need to provide the Asana Project details. The project where the task is created. The data is mapped between the apps in this step. Leaving the field empty here will let it pick the default value of projects from the linked Asana account. The different features in this step are described below.
- Field Type: The field-type tells us what kind of input will this field take. This field is a drop-down menu. There are other field types as well, like text fields, hidden etc.
- Editable Description: The description of the activity field can be edited by clicking this icon. In the above example, you can change the text, “Select the workspace” that is written as the default description.
- Add tags: This allows you to select an attribute from the trigger output andmap it to the respective activity field. This is mostly used in actionswhen an action takes the output of the trigger.
- Field Visibility: You can toggle the visibility of the field with this button. This visibility option will decide if the field will appear to the user at the time of integration configuration in the SDK.
- Field Requirement: With this toggle button, you can set the field as required or optional.
- Show Advanced Options: Clicking on this will give you a few extra options, as shown below.
You can provide a help icon along with a description on hover for any step. This will be rendered in the SDK for the user if the step is visible to them. You can also add custom styling to the step by providing a CSS class yourself. Additionally, you can introduce manual field actions to control what will happen when a fields value changes.
Additional UI options inside fields
You can also choose from a number of additional configuration options that appear in a bar on the right side of your activity field configuration.
The additional options that you can find on the bar on the right side are: Add Section, Add Tab, Add HTML, Add Template, Add Button, Delete.
You can add a section before an activity field that is visible to the user, and that field will be rendered in a separate section in the SDK. You can provide a section heading and description for the user as well. Tabs also work in a similar way as sections. You can add multiple tabs inside a section and each tab can consist of its own activity field for the user. You can add multiple tabs and sections anywhere in the template. The image below shows an example of a section and tabs rendered in the SDK.
Select your list is the name of the section that encompasses two tabs (pointed in the figure). The user can click on any tab and provide their input.
After adding a section to a template step, you can click on Show Advanced Options to see the additional options as shown below.
Here, you can customize the Save button for the section that will be shown to the user. You can also set a custom icon for the section step that will appear to the user on the left side of its heading.
Just like tags and sections, you can use the Add HTML button to add HTML markups in your template. You can write a chunk of HTML here and it will render in the SDK for the user.
The HTML you provide can also use the template tags for any other steps and render their output in the SDK. You can also provide the tag of an input field here and use the values collected from the user in your HTML.
The Add Template button allows you to add a manual template within your template and adjust how the user sees it. More info on manual templates can be found here.
Body of the trigger
Once you add and configure a trigger step, you can add other steps, like an Action, in the body of the trigger. So the action step will be a child step of this trigger and will only execute when the trigger will run. So if you have multiple triggers in a template, each can have its own body which will contain its set of specific steps. Let's see the above example for the Asana trigger that we created.
The highlighted button above will allow you to add steps in the body of the trigger.
You can add as many steps as you like inside a trigger. An example of an action and a utility step added inside a trigger is shown below.
So for the above example, when a new task is created in Asana, an issue will be created in Github and also, the value will be stored in Storage. For multiple triggers, we can make the current example two-way sync. The simplified version of two triggers with their bodies will look like this in the template:
The Action Step
Next, we’ll see how to add an action. As indicated above, you can always add an action inside a trigger step. Click the first icon after clicking the Add Step button and an action form will appear in front of you.
- Select App: Select from the list of apps as shown below. Cannot find the app you're looking for? Contact us at hello@integry.io!
- Select Action: Select from the list of actions of the selected app as shown below. Cannot find the action you're looking for? Contact us at hello@integry.io!
A template can have more than one action. The fields associated with “Create Task” action are shown below. It takes the name of the task that will be added in Doneday. We are mapping the task created in Todoist Project to the task that will be added in Doneday.
To map data between apps, we add a tag to that particular field. You can see the Add Tag button in the bottom left corner of the Task field. A list of tags will appear when you click it. In this scenario, we want to post a to-do item in Doneday when a to-do item is added in Todoist. We will select “{event_name}” as our tag so the task name is mapped and communicated between both apps.
These tag values are extracted from trigger payload. When an event (trigger) takes place in another app, the Webhook we receive is parsed and and passed onto action.
Mapping Activity Fields using Objects
Another way to map data between triggers and actions is through Objects. Objects enable one-click-mapping. Using objects, you do not need to map each field individually. Map an object, and the field are automatically mapped. Learn how to map fields using objects.
Moving and dragging tasks
You can change the position of any step in the template simply by dragging and dropping it. The step can be on any level in the template, it can be a parent or a child step. The tags within the step will automatically change and adjust to the new position.
To move any task, just click and hold the display icon on the left side of the step.
Now just drag and drop the step to its new position, as shown in the images below.
Whenever you move a step, all of the other steps in the template that are calling data from this step undergo changes in their tags to adjust to the new position of this step.
Your data will always stay consistent and the tags will stay valid throughout the template whenever you move any task. You do not need to worry about manually changing any field tags or other information while moving tasks around.
Degrees of freedom for step movement:
You can potentially move a step almost anywhere you want in a template. But in case you want to know the possible movements, they are mentioned below.
Movement within the same level
A step can be moved within its current level. For example, inside the body of a trigger or a loop. This normally means that the step stays under the same parent (if any) and also does not go to a deeper level (become child to a step below it).
Within the same level, you can move a step in two directions:
- Movement from higher index to lower index (down to up) e.g. steps.3 to steps.1
- Movement from lower index to higher index (up to down) e.g. steps.1 to steps.5
Movement to a different level
A step can be moved to a deeper or a higher level. This means that the step changes its parent or gets out of a parent step completely.
Within different levels, you can move a step in the following directions:
- Movement into a sub-level, the step becomes child of another step. In this, the step can be moved in both directions to become child of another step (up or down).
- Movement out of the sub-level. This is also movement in both directions. Step can move up and out of its parent, and the step can move down and out of its parent.
Conditions
Conditions can be added at any point in a template. You can craft multiple flows of integrations with these conditions. They work the same way as simple if-statements work in code. To learn more about IF Conditions and how to add them to a template, click here.
Template Metadata
Once you create the workflow the next step is to define the template information that will appear in the SDK inside your app. This is talked about in detail here.
Template Wizard
If the Wizard toggle button is turned on, the template will be multiple-step wizard. Learn more.
Lastly, click the Continue button to move to the Deployments page.
Happy Integrating!