A Button is a clickable element that can be placed in various parts of the Mapsly user interface to execute actions. In various parts of the user interface a Button is displayed as:
a link: in a record's map popup;
a button: in the Trip mode's waypoint panel and record view popup;
a menu item:
in the main menu,
in the route waypoint's context menu,
in the Table view row's context menu,
in the Table view's group actions menu.
Concept
Button placement in user interface
A Button can made always visible in the main menu (for example, to re-reschedule regular visits), or can be associated with one or multiple records and appear only for record of those objects in:
Map popup,
record view popup,
route activity (route waypoint context menu, trip mode's waypoint panel,
map right-click
table view row's context menu,
table view's group actions menu,
main menu.
A Button may be made available for multiple records as well
You can use a Button to perform an action on one particular record, for which the button is pressed - in this case actions executed by the button may access the record's fields using the record merge tag.
Optionally, you can make the Button available in the Table view's for a multiple records at once - in this case records will be available in actions' context under the records array object, even if there's only one record in the array.
Note #1. Regardless of whether your Button is made available for multiple records or only for one record, when a button is executed, the execution context will alway contains both the record and records variables, so in both cases you may use actions that work with the records array ("bulkified" actions).
When a Button is clicked for multiple records, the record variable in the execution context will contain a randomly selected record from the array.
A Button can bring up a Form
A Button's condition/actions blocks can contain call(s) to one or multiple Forms actions.
IMPORTANT NOTE. Only first Form actions that is executed will bring up the form, and all subsequent Form actions in the current Session will be ignored. So while you have call calls to multiple Form actions in your Button, which invoke the same or different forms depending on the implemented business logic, only one Form can be shown to the user in response to one click to a button.
Adding a new button
To add a Button, go to Setup -> Buttons:
And click the + button. Then fill in the Button's configuration settings:
Name: the Button's name that will appear in the list of buttons for the Mapsly admin. It will not be visible to end users.
API name (optional): the Button's name for referencing in other automation elements.
Button label: the button's name that will appear on the button, link and in the menu item for this the Button (visible to end users).
Objects (optional): one or multiple objects for which to display the Button. Associating a Button with an object makes it possible to display it in the following locations:
in a record's map popup, record view popup, route waypoint's context menu and Trip mode's waypoint panel for the record;
in the Table view's group actions menu, when this object is selected.
Add button to: select locations in the user interface where to display the Button.
IMPORTANT NOTE: when a button is clicked from the main menu or from the map right-click menu, there will be no records in the automation execution context, so these two locations should not be used for buttons that work with records for which they are clicked.
Visible for: this setting takes affect only if Add button to contains Table view: group actions and indicates whether to make the button available when multiple records are selected:
if One record is selected, the button will be disabled when multiple records are selected;
if One or multiple records is selected, the user will be able to invoke the button for multiple records at once.
NOTE. By default, the maximum number of records for which a Button may be clicked is 1,000. This limit can be raised by your request - please contact Mapsly support to request it.
Icon: an icon that will be shown along with the button's label in:
the route waypoint's context menu,
in the Trip mode's waypoint panel,
in the record view popup.
Sort order defines where to show the Button in relation to other custom Buttons and standard buttons and menu items:
any value under 100 will put the button before the standard buttons and menu items except route waypoint where Navigate always comes first;
any value of 100 or above will put the button after the standard buttons and menu items.
Make user's location available for actions: if this box is checked, when the user presses the Button, Mapsly will attempt to determine the user's current location and - if successful - it will be available in the Context under the
currentMapslyUser.locationkey (described in detail here).
Actions lists of condition/actions blocks to be executed when the Button is clicked.
Permitted user profiles lists user profiles for which the Button will be shown.
Create custom API endpoints in Mapsly
Mapsly allows you to expose custom API endpoints in Mapsly so that your external IT system and call it programmatically to execute custom business logic in Mapsly and receive the response, for example, to retrieve the list of territories to which a location on the map belongs.
To create a custom API endpoint, create a Button as described above, and check the Expose as API endpoint checkbox.
When you check this box, Mapsly will check if an API key has already been generated for the Mapsly System source, which will required to call this endpoint. If the API key has not yet been generated, Mapsly will generate it for you:
The following parameters will become available for configuration:
Call mode:
Choose Sync if you want the endpoint to execute and return the response synchronously.
Note. The max time Mapsly will keep the connection open will be limited by the max session execution time, which is 10 minutes by default.
Choose Async if you want Mapsly to queue the execution and immediately return HTTP response code 200 with the body
{"result":"ok"}, and once the execution has been completed, call your callback URL to pass the result. In this mode, enter your callback URL:
Authentication: choose between the 2 auth available authentication options:
API key: when called, this endpoint will verify the API key before executing the Button's condition/actions blocks. Choose this option if you plan to call this endpoint from your server and not from a public web resource. In this case, Mapsly will append the Mapsly System source's API key to the endpoint's URL.
IMPORTANT NOTE. Do NOT use API key-based authentication if this Mapsly API endpoint will be called from a public-facing web resource. Doing so would compromise your API key, enabling anyone to access and overwrite your Maps y data.
URL signature: when called, this endpoint will only verify the URL signature present in the URL as a parameter. Use this option if the endpoint will be called from a public web resource to ensure that the URL parameters have not been altered.
When you choose this option, Mapsly will automatically append your endpoint's URL with a default URL signature generated for your endpoint's URL without any other URL parameters. If you'd like to pass some URL parameters to this endpoint, you will need to re-sign your URL using SignUrl) function for every unique set of URL parameters.
Accessing the Request
You may access the request data in the Button's condition/actions using the request object of the execution context, which contains 4 keys: url, method, parameters, and body (when present). Parameters contain an array of url_param:value pairs.
Example of the request object:
Returning Response
In the Sync mode, the endpoint returns data in the following format upon completion of the execution session:
{"code": your_code, "data": your_response}
In the Async mode, upon completion of the execution session, Mapsly will call the callback URL and pass {"code": your_code, "data": your_response} in the request body.
Note. Mapsly will keep the connection open until the execution session terminates.
Response code
To return a specific HTTP code in the Sync mode, set the code variable in the execution context. When this variable is missing, the endpoint will return code 200.
Response body
To return the response body, set the response variable in the execution context.