Remote Approval

About Remote Approval

The Remote Approval feature lets users perform request approvals via email, as an alternative to launching the actual form within the WorkflowGen User Portal.

Remote Approval is an optional route for a regular form approval action in a WorkflowGen process. It is embedded inside the form approval action that asynchronously triggers a notification to the user using the WorkflowGen notification engine.

Users can still reply via the normal form approval procedure. The system will take the approval result from either approach based on a first-come-first-served basis and complete the action accordingly. No separate action is required in the workflow design process.

As of WorkflowGen 7.21.0, Remote Approval supports delegations, where delegatees can perform approvals by email.

Remote Approval settings are set on the Remote Approval tab in the Configuration Panel (see Remote Approval).

Remote Approval action configuration

Remote Approval requires parameters to control which information to provide to the remote approver, and how. These parameters also control how to return the approval results as well as other approver information back to the WorkflowGen system.

Using parameters in a Remote Approval action

Remote Approval requires additional parameters to be added to an EFORMASPX action. These parameters are to define the questions for remote approver and map the approver’s response to the action.

To successfully complete a web form action with Remote Approval, the action must have a valid FORM_DATA IN parameter. In the case of a first action (when the form data is not available), FORM_DATA should have a template XML file with the following format:

<?xml version="1.0" standalone="yes"?>
<NewDataSet>
    <Table1>
        <CURRENT_REQUEST></CURRENT_REQUEST>
    </Table1>
</NewDataSet>

Only approval answers and the approver’s information need to be returned via Remote Approval parameters. Other regular action parameters that pass values in or out of the web form remain unchanged.

In order to send out a notification email to approver, a custom notification must be defined. Under the notification tab of an approval action, add an additional notification with To do as the event, an action assignee as recipient, and a custom email template with the information about the remote approval. This custom notification is the same as a regular custom notification for any WorkflowGen action.

Default parameters

Optional parameters

Remote Approval questions

Remote Approval supports three different types of approval questions: multiple choice, questions with numeric answers, and questions with free-form text answers.

Usually, Remote Approval is used to provide approval questions with two possible answers (for example, Yes or No). To do this, three main parameters are used:

  • Qx_KEYWORDS_n holds a list of possible keywords (comma-separated) for choice n

  • Qx_RESULT_n holds the normalized answer for choice n

  • Qx_RETURN_FIELDNAME specifies the web form field name that holds the final normalized answer for question x.

Since there can be more than one question in an action, x in these parameters represents the question number, and n at the end represents the choice of answer. You can define as many keywords and results as you need.

Defining a question with two choices

In this example, there are two Y/N questions in a Remote Approval action:

Question 1

Q1_KEYWORDS_1=yes,y,ok
Q1_RESULT_1=yes

Q1_KEYWORDS_2=no,n,refused  
Q1_RESULT_2=no

Question 2

Q2_KEYWORDS_1=approved,approve,ok  
Q2_RESULT_1=approve

Q2_KEYWORDS_2=refuse,refused,reject,rejected  
Q2_RESULT_2=reject

If the approver replies ok to question 1 and bad to question 2, the final normalized answers for questions 1 and 2 will be yes and reject, respectively.

Defining a question with more than two choices

If you need to define more than two choices, you must add a new keywords/result combination. For example:

Q1_KEYWORDS_1=yes,y,ok  
Q1_RESULT_1=yes

Q1_KEYWORDS_2=no,n,refused  
Q1_RESULT_2=no

Q1_KEYWORDS_3=modify,moreinfo  
Q1_RESULT_3=moreinfo

You can define as many keyword/result combinations as you need.

Defining other types of questions

Remote Approval also supports numeric and free-form type questions.

A numeric type question requires the following keywords/result combinations:

  • Qx_KEYWORDS_1=[0-9]: [0-9] is a keyword reserved for numeric type questions; you only need to use Qx_KEYWORDS_1

  • Qx_RETURN_FIELDNAME: The web form field name that holds the retrieved answer)

A free-form text type question does not require a keyword, only Qx_RETURN_FIELDNAME (the web form field name that holds the retrieved answer).

Replying to a Remote Approval request

There are two Remote Approval answer modes: normal and quick.

In normal approval mode, a Remote Approval email can ask more than one question, and will expect replies in a structured format.

In quick approval mode, the email recipient can respond to the first question without any formatting needed. As well, they can include a comment by adding it to the second line under the response to the first question. This mode accepts only one question; as such, questions other than Q1_RETURN that have been specified as action parameters will be ignored. Quick approval mode is enabled on the Remote Approval tab in the Configuration Panel (see Remote Approval).

📌 Example in normal approval mode

An approval email contains the following:

What is your choice?  
Question 1: Y or N  
Question 2: Y or N

To answer these questions, you would need to reply to the email using the following syntax:

Q1: [Y]  
Q2: [N]  
COMMENT: [Request approved.]

Each answer is prefixed with Qx: where x is the question number. As well, answers are enclosed in brackets to indicate the beginning and end of the answer. Similarly, COMMENT has the same structure, except it is prefixed with the reserved word COMMENT:.

📌 Example in Quick approval mode

Only a keyword for question 1 is needed, with an optional comment. The first line below is the answer to question 1, and the second line is the comment:

Y  
Request approved.

Validating approval emails

A custom to-do email notification must be defined to be sent to action assignees for a Remote Approval action. This is similar to the default to-do notification of a regular EFORMASPX action. This custom email relies on the WorkflowGen notification system to distribute the approval email to one or multiple approvers.

To prevent spam or other unrelated incoming emails from arriving in the Remote Approval collector email account, and to assure the approver’s identity, a valid reply to a Remote Approval request must follow the following four conditions:

  1. The email subject line cannot be empty.

  2. The reply email should have the same email header key (Thread-Index) as registered for the associated request action in the WorkflowGen database.

  3. The remote approver's email address must match the one used by WorkflowGen in order to ensure the reply address belongs to a valid WorkflowGen user.

  4. The remote approver must be one of the action assignees for the particular request action.

Invalid emails will automatically be deleted from the collector email account.

In some unusual cases, certain email server types or configurations might automatically remove the default header key (Thread-Index) from incoming emails. To prevent this:

  1. Enable Subject line validation on the Remote Approval tab in the Configuration Panel.

  2. Add the WorkflowGen request and action IDs in the email subject in the following format: WorkflowGen request ID prefixed by # (number sign) WorkflowGen action ID prefixed by - (hyphen)

The following is an example of an email subject line containing the WorkflowGen request and action IDs:

Authorization for expenditure required #1374-4

Here, Authorization for expenditure required is the email subject, 1374 is the request ID (prefixed by a number sign), and 4 is the action ID (prefixed by a hyphen).

The email subject is defined on the first line of the custom email template with the prefix SUBJECT:. The WorkflowGen request and action IDs can be appended to the subject line using the <WF_PROCESS_INST_ID> and <WF_ACTIVITY_INST_ID> WorkflowGen macros, respectively.

Remote Approval will validate the email reply by verifying the request and action IDs obtained from the email subject. Validation conditions 2 and 3 (see above) are still applicable during the validation process.

It is highly recommended to keep the Subject line validation option disabled for greater security.

Approval email with incorrect answer or missing comment

In case of an email approval reply with an incorrect answer or missing a required comment, Remote Approval will send the email back to the approval sender and ask for a revision.

📌 Example 1: Notification email for approval reply with incorrect keyword

Your decision is in an incorrect format. Please reply to this email with one of the valid keywords or a numeric type value.

Q1: [n,NO or y,YES]

----Your reply was----

Q1: [maybe]

📌 Example 2: Notification email for approval reply with keyword that requires a mandatory comment

Your decision requires a mandatory COMMENT. Please reply to this email again with the valid keywords and a comment.

Q1: [n,NO or y,YES]  
COMMENT: [your comment]

----Your message----

Q1: [n]

This email will provide the possible keywords to remind the approval of which can be used for the answer. As well, the approver must reply to all of the questions again following the syntax (in normal approval mode), even if there was only one incorrect or missing answer.

Depending on the approver’s WorkflowGen user profile default language preference, either an English or a French message will appear on the revision notification email. If the user has a preferred language other than English or French, English will be used by default.

📌 Example of a French notification email

Votre réponse est incorrecte, veuillez répondre avec un des mots-clés suivants :

Q1: [n,NON ou o,OUI]

----Votre réponse était----

Q1: [possible]

Email customization

A custom email notification must be defined in order to distribute Remote Approval emails to approvers.

How to build the email template

The creation of custom notifications follows the same rules as any other WorkflowGen custom notification; all WorkflowGen macros are supported (see the Custom notification templates section for more information)

Attachments

File process data can be attached to a Remote Approval email so that the approver can have direct access to any file type data. A special macro can be used to add a file process data to the email:

<WF_PROCESS_INST_RELDATA_FILE.XXXXX>

Add this tag to the email body, and the file from the XXXXX process data will be appended to the email as an attachment. It will not be rendered as text in the body of the email. If multiple attachments are required, add this tag multiple times with the relevant process data name.

How to set up the overdue notification

In case an overdue notification must be sent, add an additional notification by specifying the event as "Overdue" and use the same Remote Approval email template.

For additional notifications, only "To-do" and "Overdue" events will incorporate the email thread-index for email validation (see Validating approval emails for more information).

Remote Approval web form design

Considerations

Remote Approval attempts to process an approval reply as if an approver has actually launched an approval action and submitted the web form. The form data and action parameter values are updated accordingly. This means that when the next action is launched, WorkflowGen already obtains the form data from Remote Approval and is able to display the result on the web form.

However, in order to reflect the approval result in the form archive, the approval field control must be visible by the time the action before the Remote Approval action is submitted. Remote Approval updates the form archive generated by the previous action by searching for the matching field control and assigning the value via JavaScript. It does not perform any re-rendering of the web form. For example, if a process has two actions, and the approval field in the first action is hidden by default in the web form, the form archive generated by the first action will not contain the approval field control.

Remote Approval will not be able to populate the approval result on the archive form even though WorkflowGen is still able to retrieve the latest form data and action parameter values.

Remote Approval fields only support the CheckBoxList, RadioButtonList, ListBox, and DropdownListBox controls. Remote Approval comment fields only support the TextBox and TextArea controls.

When considering the incorporation of Remote Approval in an action, we suggest the following:

  • Set the relevant approval field as always visible but read-only in the previous action.

  • Set the approval field as visible only after SubmitToWorkflow() is called in the previous action, in order to add the approval field to the archive page only.

  • Use CSS to hide the approval field in the previous action.

Error logging

Log file

Remote Approval will automatically generate basic event log information in the Windows Event Viewer as well as detailed log files within the WorkflowGen \App_Data folder. By default, the log is located in the WorkflowGen web folder DRIVE:\wwwroot\wfgen\App_Data\LogFiles\RemoteApproval\.

If WorkflowGen has been configured to use a different ApplicationDataPath (defined in the web.config file), the log files will be within the path specified in the config file. For example, if ApplicationDataPath is set to \SERVER_B\App_Data\, then the Remote Approval log files will be created in \SERVER_B\App_Data\LogFiles\RemoteApproval\.

The log file name will be the date, in the format YYYY-MM-DD.log.

The log file will contain a summary of activity, including details of technical issues, and information on the WorkflowGen actions closed via the Remote Approval application. There are five levels of details:

  • Level 0: None (no log file will be created)

  • Level 1: Execution summary message only

  • Level 2: Exception error message only

  • Level 3: Execution summary messages and exception error messages

  • Level 4: Execution summary messages and full detail exception messages (including event viewer information logs)

Level 3 is recommended, because its file size and details are well balanced.

The log file level is set on the Remote Approval tab in the Configuration Panel (see Remote Approval).

The number and size of these log files may grow according to the selected log level and the number of WorkflowGen actions handled by the application. It is recommended that you back up and clean up archived log files periodically.

Error messages

The following table provides brief explanations of some possible error messages found in the Remote Approval log.

Last updated