Dynamic Options RPC

Mostly used with select parameter or a search button.

Syntax of RPC output

In order to correctly show a response from your remote procedure, the output section of response must contain label and value.

The label is what a user sees when selecting items from the select dropdown, and value is what will be sent to the endpoint once the module is executed.

The limit is required if the API endpoint returns a large number of items (> 500). Read more about it here.

The default is optional and when true, the first item from the RPC response is pre-selected.

Response - RPC

"response": {
        "limit": 500,
        "iterate": "{{body.users}}",
        "output": {
            "label": "{{item.name}}",
            "value": "{{item.id}}",
            "default": true
        }
    }

Module communication

"response": {
        "iterate": "{{body.users}}",
        "output": "{{item}}"
    }

Select parameter

Select parameter with RPC options

Select parameter with RPC options can be used, when the API doesn't support search.

Also, a developer is able to customize labels and values by combining multiple properties together.

Examples: "label": "{{item.name}}" or

"label": "{{item.firstname + ' ' + item.lastname}}"

Both are accepted.

Mappable parameters

[
    {
        "name": "status",
        "type": "select",
        "options": "rpc://NameOfMyRemoteProcedure",
        "label": "Status"
    }
]

RPC

{
	"url": "/status",
	"method": "GET",
	"response": {
		"iterate": "{{body.data}}",
		"output": {
			"label": "{{item.optionName}}",
			"value": "{{item.optionID}}"
		}
	}
}

User view

User view - mapping mode

Notice when the mode is switched to mapping, labels aren't accessible. Values are used instead.

Filtering options in RPC

If your RPC returns unwanted items, you can filter them out by using the iterate directive together with the container and condition objects.

This approach is only recommended when the filtering of unwanted items is not supported on the API side.

RPC

...
"response": {
      
        "iterate":{
               "container": "{{body.data}}",
               "condition": "{{item.type = 'contact'}}"

	},
        "output": {
		"label": "{{item.name}}",
		"value": "{{item.id}}"
	}
...

Notice the iterate directive which involves the container and the condition objects. The container defines, what should be iterated. While the condition defines the criteria each item must satisfy to be included in the list.

Select parameter with nested RPCs

If your parameters are dependent on each other. The most common example would be dynamically selecting a file. To do it user would select an Account -> Folder -> File. Meaning RPC would require a value of the previous RPC.

Luckily, it is possible to nest RPCs under each other on Make. Here is an abstract example of how it would look inside a module's mappable parameters and RPC's communication.

Mappable parameters

Don't forget to put all your options to store property inside options. Without it nested will not work.

[
    {
        "name": "parameter_1",
        "type": "select",
        "label": "Parameter 1",
        "required": true,
        "mappable": false,
        "options": {
            "store": "rpc://exampleRpc1", //proper usage of options in this case
            "nested": [
                {
                    "name": "parameter_2",
                    "type": "select",
                    "label": "Parameter 2",
                    "required": true,
                    "mappable": false,
                    "options": {
                        "store": "rpc://exampleRpc2", //don't forget to store your options
                        "nested": [
                            "name": "parameter_3",
                            "type": "select",
                            "label": "Parameter 3",
                            "required": true,
                            "mappable": false,
                            "options": "rpc://exampleRpc3" 
                            //you are not using "nested" after it 
                            //-> there's no need to "store" options
                        ]
                    }
                }
            ]
        }
    }
]

RPC 1 Code

{
    "url": "/example1",
    "type": "GET",
    "response": {
        "output": {
            "value": "{{item.value}}",
            "label": "{{item.label}}"
        },
        "iterate": "{{body.examples}}"
    }
}

RPC 2

{
    "url": "/example2",
    "type": "GET",
    "qs": {
        "needed_parameter": "{{parameters.parameter_1}}"
    },
    "response": {
        "output": {
            "value": "{{item.value}}",
            "label": "{{item.label}}"
        },
        "iterate": "{{body.examples}}"
    }
}

Notice, that {{parameters.parameter_1}} is inherited from the 1st RPC and passed as query to the 2nd RPC call.

RPC 3

{
    "url": "/example3",
    "type": "GET",
    "qs": {
        "needed_parameter": "{{parameters.parameter_2}}"
    },
    "response": {
        "output": {
            "value": "{{item.value}}",
            "label": "{{item.label}}"
        },
        "iterate": "{{body.examples}}"
    }
}

Notice, that {{parameters.parameter_2}} is inherited from the 2nd RPC and passed as query to the 3rd RPC call.

User view

But you're not restricted to using inherited parameters in qs only. In the example below, the nested RPCs obtain a value from the parent's RPC and it is passed to the nested RPC in URL.

Structure is Workspace > Space > Folder.

Mappable Parameters

[
    {
        "name": "workspace_id",
        "label": "Workspace",
        "type": "select",
        "required": true,
        "mappable": false,
        "options": {
            "store": "rpc://getWorkspaces",
            "nested": [
                {
                    "name": "space_id",
                    "type": "select",
                    "label": "Space",
                    "mappable": false,
                    "required": true,
                    "options": {
                        "store": "rpc://getSpaces",
                        "nested": [
                            {
                                "name": "folder_id",
                                "label": "Folder",
                                "type": "select",
                                "options": "rpc://getfolders",
                                "required": true
                            }
                        ]
                    }
                }
            ]
        }
    }
]

RPC 1

{
    "url": "/workspace",
    "method": "GET",
    "response": {
        "iterate": "{{body.workspaces}}",
        "output": {
            "label": "{{item.name}}",
            "value": "{{item.id}}"
        }
    }
}

RPC 2

{
    "url": "/workspace/{{parameters.workspace_id}}/space",
    "method": "GET",
    "response": {
        "iterate": "{{body.spaces}}",
        "output": {
            "label": "{{item.name}}",
            "value": "{{item.id}}"
        }
    }
}

Notice the {{parameters.team_id}} parameter, which is inherited from the 1st RPC.

RPC 3

{
    "url": "workspace/{{parameters.workspace_id}}/space/{{parameters.space_id}}/folder",
    "method": "GET",
    "response": {
         "output": {
            "label": "{{item.name}}",
            "value": "{{item.id}}"
        }
    }
}

Notice the {{parameters.team_id}} and {{parameters.space_id}} parameters, which are inherited from the 1st and 2nd RPC.

User view

Select files or folders

Search button

When the API endpoint supports searching or has a search endpoint, you can implement a search button with confidence.

The difference between a search button and a search parameter:

• in search parameter, when a value is selected, user always sees a label;

• in search button, after a choice in the pop-up window, the field will store only value.

Search button for a query

Mappable Parameters

 {
        "name": "authorID",
        "type": "text",
        "rpc": {
            "label": "Search Author",
            "url": "rpc://getUser",
            "parameters": [
                {
                    "name": "email",
                    "label": "Author Email",
                    "help": "Enter author's email on whose behalf the comment should be created. E.g. yours.",
                    "type": "text"
                }
            ]
        },
        "label": "Author ID",
        "required": true
    }
]

RPC

{
    "url": "/users/retrieve",
    "method": "GET",
    "qs": {
        "email": "{{parameters.email}}"
    },
    "response": {
        "output": {
            "label": "{{body.name}}",
            "value": "{{body.id}}"
        }
    }
}

RPC executes a call to an endpoint, which returns author's ID for a given e-mail.

Occurence in a module

Notice, that instead of going through a list of available author IDs, user is prompted to enter author's e-mail.

Then RPC for retrieving of author's ID by e-mail is used.

Search button with nested RPCs

Mappable Parameters

[
    {
        "label": "Comment ID",
        "name": "id",
        "type": "text",
        "required": true,
        "rpc": {
            "label": "Search Comments",
            "url": "rpc://getComments",
            "parameters": [
                {
                    "name": "id",
                    "label": "Board ID",
                    "type": "select",
                    "mode": "edit",
                    "options": {
                        "store": "rpc://listBoards"
                    },
                    "nested": [
                        {
                            "name": "postId",
                            "label": "Post ID",
                            "type": "select",
                            "options": {
                                "store": "rpc://listPostsbyBoard"
                            },
                            "required": true
                        }
                    ]
                }
            ]
        }
    }
]

Occurence in a module

Advanced search button

Sometimes, it is worth implementing an advanced search (if API does have such endpoints available), which allows a user to enter as many conditions as possible, in order to find the particular record to work with.

User view

Mappable Parameters

{
        "name": "ticket",
        "label": "Ticket ID",
        "type": "text",
        "required": true,
        "rpc": {
            "url": "rpc://listTickets",
            "label": "Search Tickets",
            "parameters": [
                {
                    "name": "filter",
                    "type": "select",
                    "label": "Predefined Filter",
                    "options": [
                        {
                            "label": "New and my open",
                            "value": "new_and_my_open"
                        },
                        {
                            "label": "Watching",
                            "value": "watching"
                        },
                        {
                            "label": "Spam",
                            "value": "spam"
                        },
                        {
                            "label": "Deleted",
                            "value": "deleted"
                        }
                    ]
                },
                {
                    "name": "requester_id",
                    "type": "text",
                    "label": "Requester(Agent) ID",
                    "rpc": {
                        "label": "Search Agents",
                        "url": "rpc://listAgents",
                        "parameters": [
                            {
                                "name": "term",
                                "label": "Term",
                                "type": "text",
                                "required": true,
                                "help": "◉ The search is case insensitive.\n◉ You cannot search with a substring. For example, an agent \"John Jonz\" can be looked up using \"john\", \"Joh\", \"Jonz\" and \"jon\". But it will not be returned when you search for \"hn\" or \"th\"."
                            }
                        ]
                    }
                },
                {
                    "name": "company_id",
                    "type": "text",
                    "label": "Company ID",
                    "rpc": {
                        "label": "Search Companies",
                        "parameters": [
                            {
                                "name": "term",
                                "label": "Keyword Name",
                                "type": "text",
                                "help": "◉ It is case insensitive.\n◉ You cannot search with a substring. For example, a company \"Acme Corporation\" can be looked up using \"acme\", \"Ac\", \"Corporation\" and \"Co\". But it will not be returned when you search for \"cme\" or \"orporation\"."
                            }
                        ],
                        "url": "rpc://listCompanies"
                    }
                },
                {
                    "name": "updated_since",
                    "type": "date",
                    "label": "Updated Since"
                }
            ]
        }
    },
    ...
    ]

RPC

{
    "url": "/tickets",
    "method": "GET",
    "qs": {
        "per_page": 100,
        "order_by": "updated_at",
        "order_type": "desc",
        "company_id": "{{ifempty(parameters.company_id, undefined)}}",
        "requester_id": "{{ifempty(parameters.requester_id, undefined)}}",
        "updated_since": "{{ifempty(parameters.updated_since, undefined)}}",
        "filter": "{{ifempty(parameters.filter, undefined)}}"
    },
    "response": {
        "output": {
            "label": "{{item.subject}}",
            "value": "{{item.id}}"
        },
        "iterate": "{{body}}",
        "limit": 500
    },
    "pagination": {
        "qs": {
            "page": "{{pagination.page}}"
        },
        "condition": "{{headers.link}}"
    }
}

Reusable options in a select

Sometimes, it is better to keep the list of available options outside of mappable parameters code. To keep the code readability or use the same piece of code multiple times (like a reusable component).

In this case, we can create a "fake" RPC, where we manually define the list of available options which will be returned in the RPC's output.

User view

Mappable parameters

[
	{
		"label": "Status",
		"name": "status",
		"type": "select",
		"options": "rpc://reusableOptions"
	}
]

RPC code

{
	"response": {
		"output": [
			{
				"label": "Option A",
				"value": "a"
			},
			{
				"label": "Option B",
				"value": "b"
			},
			{
				"label": "Option C",
				"value": "c"
			}
		]
	}
}

Send query to RPC

Sometimes, you can use one general RPC instead of multiple similar RPC with different qs parameters.

Example: You have one general search endpoint, which requires to specify the type of the search companies or contacts.

Instead of creating separate RPCs or hidden parameters inside each module, where the RPC is used. You can send all needed parameters as a query to the RPC.

Example: rpc://yourRPC**?type=contact&active=true**\

Module - mappable parameters

[
  {
        "label": "Option",
        "name": "option",
        "type": "select",
        "options": "rpc://yourRPC?type=contact&active=true"
  }
]

Both - type and active - are passed to the RPC as parameters.

RPC - Communication

{
    "url": "/search/{{parameters.type}}",
    "qs": {
        "active": "{{parameters.active}}"
    },
    "response": {
        "output": {
            "label": "{{item.name}}", 
            "value": "{{item.id}}"
        }    
    }
}

The values that we send to RPC as query, will be inherited and accessed in RPC by "{{parameters.active}}" and "{{parameters.type}}" .

Sending an array to RPC

You can send an array to an RPC.

Module - mappable parameters

[
    {
        "name": "options",
        "type": "select",
        "label": "Options",
	"options": "rpc://passArrayToRPC?buttonTypes=a&buttonTypes=b&buttonTypes=c",
        "required": true
    }
]

RPC - Parameters

[
	{
		"name": "buttonTypes",
		"type": "array",
		"label": "Button Types",
		"spec": {
			"type": "text"
		}
	}
]