How to set up one-click workflows via the API

Updated in 2024.2

Learn how to set up one-click workflows where users trigger workflow actions by clicking a hyperlink in an email or on a web page, and their input is then submitted via the API. This article explains how to enable and configure the ready-to-use one-click workflows for satisfaction surveys and approval requests, including how to replace the Alloy Software logo on the response page, and walks you through creating a custom one-click workflow by detailing every step of how the mechanism works behind the scenes.

Ready-to-use graphical one-click workflows

By default, Alloy Navigator includes these ready-to-use one-click workflows for two common scenarios:

• Satisfaction surveys

  1. Automatically send users an email with several clickable emoji-style faces representing five different satisfaction levels, from Great to Bad
  2. Users select their response with a single click, no forms to fill out, no sign-in required
  3. Their feedback is submitted instantly via the API

• Approval requests

  1. Deliver approval requests via email with two clickable emoji-style buttons for Approve and Reject
  2. Recipients respond directly from the email without opening any additional pages
  3. Their decision is sent via the API and immediately recorded in the system

These workflows are referred to as graphical one-click workflows because they use visual elements (emoji-style buttons and faces) to capture input.

By default, both graphical one-click workflows are disabled. In that case, the system sends standard email notifications with instructions to open the application and respond there. To activate the graphical workflows, enable them as described below. Once enabled, graphical notifications will replace the standard emails.

NOTE: When you enable graphical one-click workflows, you may also want to customize the web pages shown to users after they submit their response from an email. At the very least, replace the Alloy Software logo with your company logo. For details, see Customizing the Success and Error web pages below.

To enable ready-to-use graphical workflows:

1. Open the Admin Center or start the Settings App, and navigate to Workflow and Business Logic > Workflow Configuration.

2. Under Workflow Configuration, enable the corresponding workflow parameter:

   • One-click satisfaction surveys

     Go to Satisfaction Surveys and select the Enable Graphical Survey Submission checkbox. This turns on sending survey emails where users can respond using emoji-style faces directly in the message. You can also review and adjust other survey-related parameters in this section.

   • Approval requests

     Navigate to Misc Automation > Approvals > General and select the Enable Graphical Approval Submission checkbox. This enables approvers to approve or reject requests by clicking emoji-style buttons directly in email notifications. Additional approval settings can also be fine-tuned here.

Customizing the Success and Error web pages

On-prem only

When users submit feedback or approvals via a graphical one-click workflow, the API displays a web page confirming the result. These are the Success and Error pages, used to show a success message, such as "Thank you for your feedback" or an error like "The link has expired."

You can customize these pages to match your branding. At a minimum, we recommend replacing the default Alloy Software logo with your company logo. You may want to also adjust the HTML layout or styling to better fit your needs.

FOR CLOUD CUSTOMERS: Please note that configuring web page templates is only available for on-premises deployments. Contact our Support Team for assistance with this task.

The HTML templates for the Success and Error web pages are located in a special folder under the API installation directory:

[PhysicalPathToAPIfiles]\HtmlTemplates\

By default, this path is C:\Program Files\Alloy Software\Alloy Navigator\WebApps\API\Alloy Navigator Site\api\HtmlTemplates\

NOTE: To view the physical path to the API files on the computer hosting the API, start the Web Configuration tool on the web server and navigate to API in the sidebar. The path will be displayed in the main pane on the right hand side, among other configuration information

This folder contains:

• ExecuteActionSuccessTemplate.html: Success page template

• ExecuteActionErrorTemplate.html: Error page template

• \images\logo.jpg: Logo image shown on both pages

The actual result message shown to users is inserted dynamically; you can configure the text of this message in your workflow settings if needed.

IMPORTANT: It is recommended to back up the default templates before making any changes.

Setting up custom one-click workflows

This section explains how to configure custom one-click workflows and how the mechanism works behind the scenes. You'll learn how the links are generated, how user input is passed through the API, and how the result is processed.

One-click workflow mechanism at a glance

To set up a custom one-click workflow, complete these steps:

1. Make sure that the Alloy Navigator API module is set up. See API module and API URL.

2. In the Settings App, create at least two workflow items:

   1. A workflow Action for collecting the user input. See Collecting user input.

   2. A workflow Action for processing the collected input. See Processing user input.

3. Optional: Customize the web page that tells your customers that their feedback has been received. See How to set up one-click workflows via the API.

API module and API URL

One-click workflows send user input through the API, so it’s essential to have the API properly installed and configured in your environment. The API module must be set up with Access Token user authentication enabled.

• Cloud customers: The API module is pre-installed and ready to use

• On-premises customers: You need to install and configure the API module. For instructions, see Installation Guide: Installing and Configuring the API Module

To find your API URL, open the web-based Admin Center and navigate to Apps and Portals > API > General. The URL field shows your API endpoint, which typically looks like this:

https://mycompany.com/alloynavigator/api

This URL is available via the system macro %[SYS API Link]% and can be used in your workflows.

Collecting user input

To collect user input, you need a workflow Action. For example, you can create an Action that generates Email Notifications prompting the user to click one of the available embedded options, and captures the user input as parameter values. The Action will also get the ID of the person receiving the email and the ID of the target object.

NOTE: The Person record must exist and be active. A matching Alloy Navigator account is not required.

Generation of API links

To transfer the user input to Alloy Navigator, it must be converted to a specific URL for the API module. The conversion is performed by a special database function: dbo.GenerateActionURLParams.

The function requires the following information:

dbo.GenerateActionURLParams (@ApiURL, @ActionID, @PersonID, @ObjectID, @ExpirationDate, @ActionParams, @SuccessMessage)

Attribute	Description	Example	Data type
@ApiURL	The URL of Alloy Navigator API's endpoint. It is convenient to use the "API Link" system macro. For details, see API module and API URL.	%[SYS API Link]%	nvarchar(max)
@ActionID	The ID of the Action to feed the user input to. To get the user input sent via the API, we recommend using action's virtual fields. For details, see Processing user input.	'2833'	nvarchar(max)
@PersonID	The ID (globally unique identifier, GUID) of the Person record for the person who receives the notification and clicks the link. The Person record must exist and be active. Note that a matching Alloy Navigator account is not required.	%[VIR Person.ID]%	nvarchar(max)
@ObjectID	The ID (globally unique identifier, GUID) of the object to be updated with the action identified by @ActionID.	%[DBF ID]%	nvarchar(max)
@ExpirationDate	The date after which the link expires. NOTE: Clicking an expired link will produce the "Link has expired" error message.	DATEADD(DAY,3,GETDATE())	datetime
@ActionParams	A string composed of a series of field-value pairs separated with the ampersand character (&). The string includes fields required by the Action @ActionID. For details, see Processing user input.	An action with a single parameter (a single virtual field): N'Vote=1' An action with multiple parameters (multiple virtual fields): N'Vote=1&notes=Your Note' An action with no parameters (no virtual fields): null	nvarchar(max)
@SuccessMessage	The message to show to the user after the action completes successfully.	An action with a message: N'Thank you for your feedback!' A "silent" action: null	nvarchar(max)

NOTE: The URL parameters that users will see in the address bar of their web browser will be encrypted.

Example: Collect customer feedback

For example, you can set up a one-click customer satisfaction survey for Self Service Portal customers:

1. Once an Incident is resolved, the requester receives a notification. The email message contains options to rate the experience with the support.
2. The customer clicks on the desired option embedded in the message.
3. A numeric score appears in the Rating field of the corresponding Ticket.

See how a sample Incident Step Action can collect user feedback:

1. The Action gets the Person ID of the email recipient.

   

   In this example, the Action simply asks the user to select a person from the drop-down list on the Action Form.

2. The Action triggers sending Email Notifications.

   

   This Action uses the Email Notification operation to generate email messages.

3. The Email Notification asks the user to click one of the available options.

   

   This Email Notification generates messages with this HTML content:

   <p>Please take a moment to share your feedback with us!</p>
   <p>Rate your experience with ticket %[PAR Ticket]% from 1 to 5.</p>
   <p>&nbsp;<a href="%[PAR VoteUrl_1]%">1</a>&nbsp;
   <a href="%[PAR VoteUrl_2]%">2</a>&nbsp;
   <a href="%[PAR VoteUrl_3]%">3</a>&nbsp;
   <a href="%[PAR VoteUrl_4]%">4</a>&nbsp;
   <a href="%[PAR VoteUrl_5]%">5</a>&nbsp;</p>

   Note that clicking a link in the message body opens a URL containing the user feedback. That URL is generated by a SQL expression, as explained below.

4. The Email Notification captures the user input as parameter values.

   

   This Email Notification have parameters where the email address and the user's vote will be captured.

5. The Action processes the supplied parameters.

   

   This Action assigns values to the Email Notification parameters. Go to the next step to view how each of the available user's votes is converted to a specific URL for the API module.

6. The SQL expression converts the user input to a specific URL.

   

   To generate a specific API link, the dbo.GenerateActionURLParams function is used.

   For example, this SQL expression converts the highest rating parameter %[PAR VoteUrl_5]% to the URL for the API module:

   select dbo.GenerateActionURLParams (%[SYS API Link]%, '2287', %[VIR Person.ID]%, %[DBF ID]%, DATEADD(DAY,3,GETDATE()), N'Vote=5', N'Thank you for your feedback')

   INFO: For details, see Generation of API links.

Now everything is ready to capture user input. Let's configure how to process it.

Processing user input

To process the collected user input, you need another workflow Action. That Action will be called via the API when the user clicks the desired option. We recommend to use virtual fields to get the user input sent via the API.

Example: Calculate Incident rating

Let's see how an Incident Step Action processes the user feedback collected by the "Request for Vote" Action from our example above.

1. The Action gets the user input in the form of parameters sent via the API.

   

   The virtual field on the Action Form gets the user's vote, transferred via the API.

2. The Action checks the condition.

   

   The workflow engine checks whether all these conditions are met:

   • The action is initiated via the API;
   • The current user is the Incident requester;

   • The Incident requester has not already voted.

3. The Action processes the parameter value and calculates a numeric rating score for the Incident.

   

   • This sample Action adds the voting details to the Incident's Notes tab,

     

   • adds a new log record to the Activity Log,

     

   • declares a variable to convert ratings to the percentage,

     

   • and finally, calculates the Incident rating based on the user's vote.