How-to

How to set up one-click workflow via the API

Introduced in 8.6

Updated in 8.7

This article shows you how to set up a workflow where your customers can trigger workflow Actions with a single click on a hyperlink contained in an email or on a web page. The customer's input is transferred via the API.

For example:

  • Embed satisfaction survey questions with response options into an email template to invite your internal users or customers to rate their experience with the support.

  • Send out approval requests with one-click links to enable stakeholders to cast their votes directly from email messages without having to open additional links or pages.

One-click workflow at a glance

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

  1. Configure the Alloy Navigator API module. 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 Customizing the web page.

API module and API URL

The Alloy Navigator API module must be installed and configured for the Access Token user authentication.

INFO: For instructions, see Installation Guide: Installing and Configuring the API Module.

To have the API URL ready, complete the Workflow Integration page of the Web Configuration tool for the API module. This will assign a value to the system macro %[SYS API Link]%, so you can use it later in workflow. The API URL may look like this:

https://mycompany.com/alloynavigator/api

INFO: For instructions, see Installation Guide: Customizing the API Link Macro.

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 to use action's virtual fields

For details, see Processing user input.

'2287'

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:

    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.

Customizing the web page

As your customers submit their feedback, the API shows them a special web page with a success message. This is the message that @SuccessMessage defines (see Generation of API links). If an error occurs, this web page would show a corresponding error message (for example, "The link has expired").

You can customize any of these web pages. At least, replace the Alloy Software logo with your company logo.

The HTML templates are located in a special folder under the API installation directory:

[PhysicalPathToAPIfiles]\\HtmlTemplates\

TIP: To view the physical path to API files, 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

The folder contains two templates:

  • ExecuteActionErrorTemplate.html - the success web page;
  • ExecuteActionSuccessTemplate.html - the failure web page.

The company logo that those web pages display is located in the images sub-folder.

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