Administration Guide

One-Click Action Links

On this page

A one-click action link is a link in an e-mail notification that runs a workflow action on a record when it is opened. The product supplies no ready-made action-link component: you build the link from three parts.

  • A SQL-type macro per link that builds the link.
  • An HTML-type macro that wraps those links for the message body, placed in the e-mail notification.
  • A task action that receives the link and runs.

The two macros are edited in the Settings App or in the Admin Center. The notification and the receiving action are created in the Settings App, the only application whose pages create e-mail notifications. The link itself runs in the REST API. For macro types and placeholders, see Macros Reference. For the approval and survey links of the Default Workflow, see Links in the supplied configuration.

Before you begin

  • One-click links work only when the API uses token authentication.
  • The link starts with the API's base address. The API Link system macro holds that address, and the link falls back to it when no address is given. In the Settings App it is set at Workflow and Business Logic > Advanced > System Macros, in the API Link: box, which requires the administrative right System Macros. See Macros Reference.
  • In the Settings App, Workflow and Business Logic > Macros requires the administrative right Macros. A class's own Macros and Workflow nodes require that class's own administrative right, the one that allows managing the class's business logic. See Permissions Reference.

In the Settings App

  1. Open Workflow and Business Logic > Macros, or the Macros node of a class under Workflow and Business Logic > module > object class.
  2. Click New. The New Macro window opens.
  3. Enter Name:. The read-only Placeholder: box shows the macro's placeholder, %[USR <name>]%, as you type.
  4. Set Type: to SQL Script and Output: to Plain Text. The list shows the macro as SQL script.
  5. Enter the content: a script that selects the result of dbo.GenerateActionURLParams, called with the seven arguments listed below. The placeholders in the script are replaced before it runs, so an argument can be an object field such as %[DBF ID]% or a parameter the notification declares, %[PAR <name>]%. The macro yields the first column of the first row of the last result set the script returns.
  6. Click OK.

The function dbo.GenerateActionURLParams takes these seven arguments, in this order:

  1. The API's base address, for example the %[SYS API Link]% system macro. An empty value falls back to the configured API Link.
  2. The id of the task action that receives the link.
  3. The id of the person the action runs as.
  4. The id of the record the action runs on, for example %[DBF ID]%.
  5. The expiration date of the link.
  6. The values to pass to the action, as name=value pairs joined with &. An empty or null value passes nothing.
  7. The success message shown on the result page. An empty or null value gives no message.

The function returns the API address followed by ExecuteAction?params= and an encrypted string that carries the other six values.

For the checks the macro window makes, such as a unique name, see Macros Reference.

  1. In the same macro list, click New.
  2. Enter Name:, set Type: to Text and Output: to HTML. The list shows the macro as Text (HTML).
  3. Choose All objects, or Object class: and the notification's class. The notification editor offers only the macros that belong to no class, to the notification's class, or to its general class.
  4. The content is an HTML editor that opens in Design mode. Switch it to HTML Code with its first toolbar button, and add one <a href> element per link, each pointing to the placeholder of one SQL macro, %[USR <name>]%. One HTML macro can hold several links.
  5. Click OK.
  1. Open the class's e-mail notifications at Workflow and Business Logic > module > object class > Workflow > Components > E-mail Notifications, or the global ones at Workflow and Business Logic > Global Components > E-mail Notifications.
  2. Create or open the notification.
  3. Give it an HTML body: choose HTML text, or choose HTML template and put the links in a section whose value is HTML.
  4. For an HTML text body, click Insert Placeholder... and, under User Macros in Select Placeholder, choose the HTML macro. A plain-text body offers no HTML macro. For a section, enter the HTML macro's placeholder, %[USR <name>]%, in the section's value.
  5. Save the notification.

The notification editor does not check that the link is well formed.

A notification is sent by an E-mail Notification step in the program of a workflow item or of a function. The step's Select offers the notifications of the step's own workflow object and those of Global Workflow. For the rest of the notification, its parameters, and the step, see Author E-mail Notifications.

Build the receiving action

Create the receiving action among the class's actions, at Workflow and Business Logic > module > object class > Workflow > Actions. It is an ordinary task action.

  • Every name=value pair of the link becomes a field value, except the values the link carries for itself: personId, objectId, actionId, expirationDate, and successMessage. The name is matched against the fields of the action's form, by field name, caption, or label, including form-only (virtual) fields, and then against the fields of the record and of its activity by caption. A name that matches no field fails the run with "field is unknown". A value for a field with a lookup may be given as a name, which the API resolves; a value that resolves to nothing fails the run with "object does not exist in database". A value for a Boolean field counts as true when it is 1, true, or yes, and as false otherwise.
  • Form fields that the link does not send get their default values. A field that is mandatory on the form, or that the database does not allow to be empty, fails the run when it ends up empty, and the failure names the field's caption.
  • A condition on the action that compares %[SYS Initiator.Type]% (or %[SYS Initiator]%) with API tells a run through the API from any other run. Every run made through the API has the initiator API. When a condition compares the initiator's Type, its value list offers API.

The REST API rereads workflow changes at most every minute, so an edited action can still run in its old form for up to one minute.

In the Admin Center

The Macros tile in the Workflow section lists the same user macros, grouped by object class. In a macro's drawer:

  • For the macro that builds a link, set Type to SQL script and Output to Plain text, and enter the script in Text Content.
  • For the macro that holds the links, set Type to Text and Output to HTML, and enter the <a href> elements in Text Content. Under This macro available for:, choose All objects, or Object class: and the notification's class. The Settings App's notification editor offers only the macros that belong to no class, to the notification's class, or to its general class.
  • The read-only Placeholder shows %[USR <name>]%, the placeholder that the HTML macro and the notification use.

For the rest of the drawer, see Macros Reference.

The link points to the REST API. Opening it runs the action named in the link on the record named in the link, with the person named in the link as the acting person.

Instead of a JSON response, the API returns an HTML result page:

  • The success page, with the link's success message if it has one. This page is shown in every case that the error page below does not cover. A workflow abort in the action raises no error, so an aborted run still shows the success page.
  • The error page, with "The link has expired." after the link's expiration date, "Invalid Link" when the link lacks the record, the action, or the person, or the error message when the action is refused or running it raises an error. The action is refused before it runs when it is not available, when the record does not exist, when the action's condition does not admit the run, or when a name the link passes matches no field or a mandatory field is empty.

A link always runs a task action on an existing record; it cannot run a create action. A link that names a create action shows the error page with "Cannot process the request. Requested action id is of unexpected type." Where the two result pages are stored on the API server is described in Create Records and Run Actions.

A new 2026.1 database created with the Default Workflow contains one-click links for approval requests and for satisfaction surveys, each built from the three parts described on this page. A database upgraded from an earlier version need not contain them, and an administrator may have changed them. See Default Workflow Configuration.

Links SQL macros that build them Receiving action
Survey ratings on incidents The five SQL macros whose names begin with Incident Survey Rating Link and end with (API) API Survey Vote, on incidents
Survey ratings on service requests The five SQL macros whose names begin with Service Request Survey Rating Link and end with (API) API Survey Vote, on service requests
Approve and reject Approval Request Link for Approval (API) and Approval Request Link for Rejection (API) API Approval, on approval requests
  • Each SQL macro builds its link with the API Link system macro as the address, %[DBF ID]% as the record, the notification's person parameter as the person, the notification's parameter %[PAR ExpirationDate]% as the expiration date, and "Thank you for your feedback" as the success message.
  • The five survey macros of a class pass the ratings 1 to 5, one per macro, under Vote. The two approval macros pass "approved" and "rejected" under Response.
  • The HTML macro Incident Survey Rating Links (API) holds the incident rating links. The HTML body of the notification E-mail Requester with Initial Survey Request (Graphical) embeds it, and the incident function Send Survey sends that notification.
  • Each receiving action is an ordinary task action whose form has one form-only, mandatory field: Vote on the two survey forms, and Response, with the values "approved" and "rejected", on the approval form. The link passes its value under that field's caption.
  • Each receiving action has a condition that compares the initiator with API. The two API Survey Vote actions also check that the person has not voted yet.

The workflow parameter Enable Graphical Approval Submission decides whether the approval e-mails of the supplied configuration carry one-click links. It is set to off in the supplied configuration, where two functions of approval requests test it: Create Manager Approval and Notify (Related Object) and Email Approver. The parameter's description says the feature requires the API to be installed and working; see also Before you begin. The survey rating links have a switch of their own, described in Customer Satisfaction Survey.

  1. In the Admin Center, go to Workflow and Business Logic > Workflow Configuration.
  2. In the category tree, open Misc Automation > Approvals > General. The page shows one control per parameter.
  3. Turn on Enable Graphical Approval Submission. Save and Cancel appear once a field has changed.
  4. Click Save.

Leaving the page with unsaved changes asks "You should save you changes before leaving this page. Do you want to leave this page?"