List types
Lists are needed when a specific identifier needs to be sent in an API request instead of its name. For the convenience of filling you can create a list, fill it with elements and select it in the action field setting. Each list item consists of:
Unique key - a value that will be used in all API requests
Name - the text that will be displayed to the user when a list item is selected in the field.
The list can be static, dynamic or nested. In the first case, all elements are created manually and never change. It is used to indicate the type of the created entity with numbers (e.g, 1 – person, 2 - organization).
The second type makes an API request at the time of creating a connection to Albato or updating it. This list gets the elements based on the response to the request. Each user will have a unique list with its own elements. It is used to indicate the status of the created entity or ID of the responsible user.
The third type (nested list) receives nested elements from the parent list dynamic list. Example: when each element of the list has its own array; let’s say that we receive an array of sales funnels, along with it we receive an array of statuses for each funnel. At the same time, we can select a parent for a dynamic list to send cyclic requests by ID received from the parent.
The number of lists can be unlimited, as one list can be used in an unlimited number of fields.
Creating the list, you specify the name in different languages and select the type.
The name of a static list is internal, dynamic list’s name is displayed in the app connecting settings.
After creating a list, changes are unavailable.
Static list consists of fields set, and each field is a list item. Setting includes fields and ID (unique key) adding
In this example, the item will be displayed to the user as person, and all API requests will use the value individual when this list item is selected.
After creation, items can also be sorted in a separate tab.
This type already uses the Requests widget, with behavior settings of the outgoing API request for list and parsing response.
After setting an outgoing request (Request tab), set up the response parser in the Response tab.
In this tab, you specify the path to the dataset (mapping to the variable containing the dataset of objects with elements) and map only two fields “Unique key” and “Element name”.
For example, if the JSON looks like:
then the mapping is indicated on the above screenshot.
Also, in the field where the element name is mapped, you can map several keys from the answer at once, in order to display several dynamic values together with static in the name of the element.
For example, if the JSON looks like this:
And in addition to the status name, it is necessary to indicate the name of the funnel to which it belongs, the mapping is written as follows
Thus, the list item will have two dynamic parameters in its name.
At the moment, dynamic lists are supported only in a flat form, the answer can be parsed from only one array of objects.
Creating a dynamic list, you can set up the Errors tab. In this case, errors will be checked at the time of creating/updating the connection with the app. You can apply this function when you need to handle a particular type of error in Authorization.
After creating any type of list, you can select it in the settings of the Action fields:
Select the list in the Action field. Action step settings in the bundle will look like:
The user can easily select the element he needs. The correct value will go to the API request. The same happens with a dynamic list.
It is also possible to get nested entities from the lists by selecting a parent list. We can select a parent list for Dynamic and Nested lists.
This list is in no way different from a common dynamic list. But it has an opportunity, to put the Unique key parameter in the Request .
This key will be exactly what is specified in the parent list field in the Response tab
This key will be substituted in the request, and the request itself will be executed as many times as the number of elements in the parent list (each request with a different key).
Choosing this type of list, “Parent list” is a required field. Nested list cannot be without a “parent”.
This list has only one tab - Response , and it does not make any additional HTTP requests.
In this list, it is important to indicate the path to the data array. The path is specified exactly to that array that is located in the element which has been received from the parent list. For example, our first list in response receives JSON of the following form:
The main list receives the teams array, and the Nested list receives the members array and its elements.
We need to get a list of funnel statuses, but each funnel has its own set of statuses. we do the following: first, we get an array of funnels by API. Then with another API request we get an array of statuses for each funnel, specifying the funnel ID in each request. Thus, we first create a regular dynamic list that receives funnels and stores them. Then we create another dynamic list for statuses specifying the list with funnels as a parent list. Thus, we will first make a request for funnels, save them, and then we will loop through status requests for each funnel. We can send as many requests as we receive funnels, substituting a unique ID in each request.
Similar example: we also need to get a list of statuses, but it is enough to make one API request. The response immediately comes with an array of objects (with funnels), and each object (funnel) has its own array of statuses inside. First, a dynamic list is created that receives only funnels, then a Nested list is created, and the list receiving funnels (dynamic) is selected as the parent. This list does not make additional requests, but it specifies the path to the array with statuses. Thus, we will make one request, get all funnels and save them, then we will pull out an array of statuses from each funnel and save these statuses in a separate list.
There are only examples, but they are applicable in many cases. In lay terms, we either make additional requests with the parent ID and get nested entities in a loop, or we try to pull out and save an additional array for each element in the list. Let’s suppose “Sites” is the main list, then “site forms” will be the nested, or the parent list is “Spaces” and the nested list receives sheets from each “Space” in which tasks can be created.
At the same time, the nesting level can be infinite and we remember the entire connection.
Using the ClickUp as an example, we need to create a task:
To create a task, we need to specify a certain list_id. We need to make a request to get this list_id, but we also need to specify the space_id there.
We are trying to get these Spaces, but again we need to specify the team_id in the request:
Finally, only teams can be received without specifying any ID.
At the same time, when receive teams, we get an array of users for each team:
In the App Integrator, we create the first dynamic list - Teams , then we create a “Nested list” where select Team as a parent list and specify a path to the members array, thus we get members of each team. Next, we create a dynamic list of Spaces with parent the same parent list - Teams, thus we get a set of Spaces for each team. Finally, we create another dynamic list - Lists, with a parent list - Spaces and we will get the list IDs of each “Space”. This list can already be used in the required field and the end-user of the “Actions” will be able to select the “List” he needs in which to create a task. Total level of nesting: Teams IDs => Spaces IDs => Lists IDs and we additionally received an array of users from the first list.
You can also select several parent lists in one list. In case we need to get some entity, we specify the ID in the request from the parent list we need. In example with the same ClickUp it looks like this: list_id can be received both from a specific space and from some Folder by specifying the folder ID.
And getting folder IDs again comes from Space
In this case, we a dynamic list as well - Folders were we specify parent - Spaces again. But for the Lists list, we select both Spaces and Folders as a parent, and we will get the lists IDs from both entities above.
Nesting can be controlled step by step, so that before setting up the “Action” or “Trigger”, the user will select a specific Team, Space, Folder step by step. If the desired list is not in the folder but in the space, then there will be the “Not selected” option. Every time the choice will be narrowed exactly by the level of nesting.
After creating any type of list, it can be selected in the settings of the action fields:
It will be easier for the user to select the element he needs, and the correct value will go to the API request. The same happens with the dynamic list.
Unique key - a value that will be used in all API requests
Name - the text that will be displayed to the user when a list item is selected in the field.
The list can be static, dynamic or nested. In the first case, all elements are created manually and never change. It is used to indicate the type of the created entity with numbers (e.g, 1 – person, 2 - organization).
The second type makes an API request at the time of creating a connection to Albato or updating it. This list gets the elements based on the response to the request. Each user will have a unique list with its own elements. It is used to indicate the status of the created entity or ID of the responsible user.
The third type (nested list) receives nested elements from the parent list dynamic list. Example: when each element of the list has its own array; let’s say that we receive an array of sales funnels, along with it we receive an array of statuses for each funnel. At the same time, we can select a parent for a dynamic list to send cyclic requests by ID received from the parent.
The number of lists can be unlimited, as one list can be used in an unlimited number of fields.
Creating the list, you specify the name in different languages and select the type.
The name of a static list is internal, dynamic list’s name is displayed in the app connecting settings.
After creating a list, changes are unavailable.
Static list
Static list consists of fields set, and each field is a list item. Setting includes fields and ID (unique key) adding
In this example, the item will be displayed to the user as person, and all API requests will use the value individual when this list item is selected.
After creation, items can also be sorted in a separate tab.
Dynamic list
This type already uses the Requests widget, with behavior settings of the outgoing API request for list and parsing response.
After setting an outgoing request (Request tab), set up the response parser in the Response tab.
In this tab, you specify the path to the dataset (mapping to the variable containing the dataset of objects with elements) and map only two fields “Unique key” and “Element name”.
For example, if the JSON looks like:
then the mapping is indicated on the above screenshot.
Also, in the field where the element name is mapped, you can map several keys from the answer at once, in order to display several dynamic values together with static in the name of the element.
For example, if the JSON looks like this:
And in addition to the status name, it is necessary to indicate the name of the funnel to which it belongs, the mapping is written as follows
Funnel - {{item.pipelineName}}, Status - {{item.name}}Thus, the list item will have two dynamic parameters in its name.
At the moment, dynamic lists are supported only in a flat form, the answer can be parsed from only one array of objects.
Additional information
Creating a dynamic list, you can set up the Errors tab. In this case, errors will be checked at the time of creating/updating the connection with the app. You can apply this function when you need to handle a particular type of error in Authorization.
Using in Action
After creating any type of list, you can select it in the settings of the Action fields:
Select the list in the Action field. Action step settings in the bundle will look like:
The user can easily select the element he needs. The correct value will go to the API request. The same happens with a dynamic list.
Nested Lists
It is also possible to get nested entities from the lists by selecting a parent list. We can select a parent list for Dynamic and Nested lists.
How to set up a dynamic list with a parent list
This list is in no way different from a common dynamic list. But it has an opportunity, to put the Unique key parameter in the Request .
This key will be exactly what is specified in the parent list field in the Response tab
This key will be substituted in the request, and the request itself will be executed as many times as the number of elements in the parent list (each request with a different key).
How to set up nested list
Choosing this type of list, “Parent list” is a required field. Nested list cannot be without a “parent”.
This list has only one tab - Response , and it does not make any additional HTTP requests.
In this list, it is important to indicate the path to the data array. The path is specified exactly to that array that is located in the element which has been received from the parent list. For example, our first list in response receives JSON of the following form:
The main list receives the teams array, and the Nested list receives the members array and its elements.
Use cases
We need to get a list of funnel statuses, but each funnel has its own set of statuses. we do the following: first, we get an array of funnels by API. Then with another API request we get an array of statuses for each funnel, specifying the funnel ID in each request. Thus, we first create a regular dynamic list that receives funnels and stores them. Then we create another dynamic list for statuses specifying the list with funnels as a parent list. Thus, we will first make a request for funnels, save them, and then we will loop through status requests for each funnel. We can send as many requests as we receive funnels, substituting a unique ID in each request.
Similar example: we also need to get a list of statuses, but it is enough to make one API request. The response immediately comes with an array of objects (with funnels), and each object (funnel) has its own array of statuses inside. First, a dynamic list is created that receives only funnels, then a Nested list is created, and the list receiving funnels (dynamic) is selected as the parent. This list does not make additional requests, but it specifies the path to the array with statuses. Thus, we will make one request, get all funnels and save them, then we will pull out an array of statuses from each funnel and save these statuses in a separate list.
There are only examples, but they are applicable in many cases. In lay terms, we either make additional requests with the parent ID and get nested entities in a loop, or we try to pull out and save an additional array for each element in the list. Let’s suppose “Sites” is the main list, then “site forms” will be the nested, or the parent list is “Spaces” and the nested list receives sheets from each “Space” in which tasks can be created.
At the same time, the nesting level can be infinite and we remember the entire connection.
Using the ClickUp as an example, we need to create a task:
To create a task, we need to specify a certain list_id. We need to make a request to get this list_id, but we also need to specify the space_id there.
We are trying to get these Spaces, but again we need to specify the team_id in the request:
Finally, only teams can be received without specifying any ID.
At the same time, when receive teams, we get an array of users for each team:
In the App Integrator, we create the first dynamic list - Teams , then we create a “Nested list” where select Team as a parent list and specify a path to the members array, thus we get members of each team. Next, we create a dynamic list of Spaces with parent the same parent list - Teams, thus we get a set of Spaces for each team. Finally, we create another dynamic list - Lists, with a parent list - Spaces and we will get the list IDs of each “Space”. This list can already be used in the required field and the end-user of the “Actions” will be able to select the “List” he needs in which to create a task. Total level of nesting: Teams IDs => Spaces IDs => Lists IDs and we additionally received an array of users from the first list.
You can also select several parent lists in one list. In case we need to get some entity, we specify the ID in the request from the parent list we need. In example with the same ClickUp it looks like this: list_id can be received both from a specific space and from some Folder by specifying the folder ID.
And getting folder IDs again comes from Space
In this case, we a dynamic list as well - Folders were we specify parent - Spaces again. But for the Lists list, we select both Spaces and Folders as a parent, and we will get the lists IDs from both entities above.
Nesting can be controlled step by step, so that before setting up the “Action” or “Trigger”, the user will select a specific Team, Space, Folder step by step. If the desired list is not in the folder but in the space, then there will be the “Not selected” option. Every time the choice will be narrowed exactly by the level of nesting.
How to use in actions
After creating any type of list, it can be selected in the settings of the action fields:
It will be easier for the user to select the element he needs, and the correct value will go to the API request. The same happens with the dynamic list.
Updated on: 07/12/2022
Thank you!