Overview
When setting up a list in Mirata, there are, by default, transitions that are run to perform actions on a list. Those actions can be replaced with custom transitions. This article will outline the 4 types of list transitions and how to configure them for customized transitions. These are useful if needing to run an integration action (ex: data table query) instead of performing actions locally on the list.
Types of List Transitions
Within Mirata there are 4 types of transitions that dictate actions within a list control:
Add - what happens when adding a new row (list item) to a list.
Delete - what happens when deleting an existing row (list item) to a list.
Edit - what happens when editing an existing row (list item) within a list.
Selection - what happens when selecting an existing row (list item) within a list.
Understanding Basic Customized List Transitions
Technically, a user can connect any transition/transaction to any of the options for a list control. However, this wouldn't make sense to do, because there should be a specific transition/transaction for each type of list transition.
As shown in the image below, when trying to set a specific Add Transition for a list, the user is presented with options for all transitions/transactions contained within the workflow of this form. It is important to only create (and then select) the transition/transaction that makes sense in the context of each list transition.
Add Transition Configuration
Suppose there is a list with three fields, configured as follows:
Field Name | Field Label | Field Type |
|---|---|---|
my_list | My List | list |
my_list_item | My List Item | group (list item) |
name | Name | string |
age | Age | integer |
birthdate | Birthdate | date |
Now that the list is made, an Add Transition can be configured so that users can see a customized screen to add an item to the list. The Add Transition will be run when the user clicks the blue "+ Add Row" button.
Without setting an Add Transition, when a user clicks the "+ Add Row" button, another row (list item) will simply be added to the bottom of the list. By connecting a Add Transition, the user will see whatever has been configured in the transition/transaction.
For example, suppose the Add Transition is set up to capture a name, age, and birthdate, and post that to a new record in a list. In order to do this, the dialog box of a "Add Item" transaction needs to be set up to contain a group that has the same fields as the list item (Name, Age, Birthday).
A new transaction called Add Item was created for this example.
This is extremely important because the form update that needs to be processed to append the record to the list, is an array-to-array. In simpler terms, the array (group in the transition dialog) will be appended to the form array (My List). For more information on array-to-array updates, visit the Form Updates article.
When the Add Item transaction has been finished, connect it to the Add Transition control property on the form. Leave the first radio button selected, since most of the time, after running an Add Transition, another additional row does not need to be created.
Now, when navigating to Preview, the list will be empty, but after clicking the "+ Add Row" will be visible and enabled. Select that button to see the dialog box that was configured earlier to capture the information. Fill out the fields, and then hit "OK" to add that group (list item) to the list.
Delete Transition Configuration
The Delete Transition will run when the user selects the trashcan on the list item. It is important to note that "Delete Enabled" must be true (or at least conditionally true) for the Delete Transition to run. The Delete transition is run when the user clicks the trashcan icon on the list item. The only case when this could be different is for if some reason, there was another workflow button on the list item that would perform the deletion, but this is highly unlikely since the trashcan button is default and already performs this action.
Normally, when manually deleting a list item, this is the dialog box that appears by default:
Suppose that the user would need to to see and confirm the information in the to-be-deleted list item before the Delete Transition runs. In this scenario, the form would display all the information in the list item before the deletion is complete.
A new transaction called Delete Item was created for this example.
Similar to the process for the Add Transition, there needs to be some custom configuration for the dialog box for the Delete Item transaction.
First, a new integer field needs to be added into the form. This field will serve as the selection field for the entire list. The selection field becomes populated with an integer value of the position of the user-selected list item. This is critical because when the Delete Transition runs, it will need to show the user the information of the fields at the exact position that they are trying to delete from, so that information needs to be referenced at the selected list item's position. For more information on this topic, please visit the position-based calculations article.
Now that the selection field is set up, navigate to the Delete Item transaction, and open the dialog editor. If the user needs to see the information that will be deleted, then there needs to be a field in the dialog that match the field type on the form. The controls in the dialog box were added as follows:
Control Name | Control Label | Control Type |
|---|---|---|
to_be_deleted | List Item to be Deleted | section |
name | Name | text |
age | Age | integer |
birthdate | Birthdate | date |
Now that the dialog fields are in place, there needs to be calculations set up to pull the values into the dialog box from the form. These calculations needs to be set for the initial calculation so that when the Delete Transition runs, the user can see the values of the fields. This is where the selection field comes into play. When referencing the field from the form, there needs to be a position calculation that references the selection index field (my_list_index).
Select the field in the dialog box to apply the calculation to
Navigate to the control properties
Select "calculation" for the initial property
Change the calculation type from 'constant' to 'field'
Change the context in the field selection window from Transition to Form
Navigate to the list and select the position button (red icon with three lines) and change 'first' to calculation, and then select the selection field from the form (my_list_index)
With the list index selected (position button should be blue), navigate into the list item and select the desired field
Repeat for all other fields in dialog box
One of the crucial differences between the Add Transition and the Delete Transition is that there does not need to be a form update applied because the Delete Transition is already going to be run on a selected list item (unless something else needs to happen on the form). So after the above changes are made, navigate to Preview, add a few list items and try deleting one of them.
Now it is clear that by running the Delete Transition on the list, the selected list item's information was pulled into the dialog for the Delete Item transaction, and then the entire list item was deleted from the list.
Edit Transition Configuration
It is important to note that configuring an Edit Transition is probably the least common transition that is edited by form designers. The main reason for this is because users can edit directly in-line without a transition connected to the list. HOWEVER, if the edit in the list needs to update a data table, this becomes more common.
Similar to the Delete Transition, the Edit Transition occurs when the user selects the edit button on a list item. This requires the list item to have the "Edit Enabled" and "Edit Button Shown" as true. However, editing a specific list item can be controlled by an additional workflow action button, but this Edit Transition is built into the list control.
A new transaction called Edit Item was created for this example.
The process of configuring this Edit Transition is essentially of part of the the process of creating an Add Transition (form update) and Delete Transition (field population in the dialog of the transition).
Suppose in the Edit Item transaction, there are the following form controls:
Control Name | Control Label | Control Type | Initial Value Mapping |
|---|---|---|---|
to_be_edited | List Item to be Edited | section | n/a |
name | Name | text | Mapped to the "name" field at the selected index of the list (my_list_index) |
age | Age | integer | Mapped to the "age" field at the selected index of the list (my_list_index) |
birthdate | Birthdate | date | Mapped to the "birthdate" field at the selected index of the list (my_list_index) |
Assuming these fields are set up correctly, the list item then needs to be updated via a form update. Each field in the list item needs to have a form update or else this won't work. For this scenario, the list index needs to be referenced from the field that is being set. This is so the form understands which specific list item will be updated.
Now by navigating to Preview, filling out a few list items, and running the edit transition, the fields will become updated.
It is clear that the Edit Transition worked properly, and the Age for the record that was selected was updated to the information being entered in the Edit Item transaction dialog.
Selection Transition Configuration
Suppose that a user wants to open a form when they select an item within a list. A Selection Transition can be applied to the list that will run when the user selects an item in the list.
A new transaction called List Selection was created for this example.
On the transaction, there will be a create form set:
Navigate to the Inbox to test this out. Create a new form and add a few list items. Then select one. The dialog box will appear (if this is marked as shown, which it was by default in this example - obviously the dialog box would be updated to be more informative in a real form scenario).
Then the new form should appear in the Inbox. If there is a Create dialog for the other form that is being created, that will be shown as well.
Using List Transitions for Data Table Requests
Similarly to changing things on the form, if the addition, deletion, editing, or selection of a list item needs to update a data table then this can also be performed by the List Transition(s). Since List Transitions are simply just normal transitions/transactions that are connected to different parts of the list, integration actions that modify data tables can be applied here.
Please visit our article on Data Table Requests for information on configuring data table integration actions.