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.

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

Parameter	Type	Direction	Description
FORM_DATA (required)	FILE	IN/OUT	IN/OUT parameter that holds the WorkflowGen request form data file. This is a default parameter for EFORMASPX actions.
FORM_ARCHIVE	FILE	OUT	Remote Approval requires passing the FORM_ARCHIVE process data as a WorkflowGen parameter in order to capture all the field updates that occur during Remote Approval. The parameter direction must be OUT in order to return the updated archive content back to WorkflowGen. Notes: No update will be made to the archived web form if FORM_ARCHIVE is not defined in the Remote Approval action. FORM_ARCHIVE is needed for EFORMASPX actions only.
Qx_KEYWORDS_n	TEXT	IN	See the Email customization section for details on this parameter.
Qx_RESULT_n	TEXT	IN	See the Email customization section for details on this parameter.
Qx_RETURN_FIELDNAME	TEXT	IN	The normalized result from Qx_RESULT_n will be passed to the field name specified in this parameter. Note: No other parameter should be defined in a Remote Approval that has the suffix _RETURN_FIELDNAME.

Optional parameters

Parameter	Type	Direction	Description
KEYWORDS_BRACKETS	TEXT	IN	To answer a Remote Approval question in regular approval mode, you must follow a pre-defined syntax: Q1: [answer] The square brackets ([ and ]) are the default value if this parameter is not used. You can customize it by assigning different characters to enclose the answer. For example, you can set KEYWORDS_BRACKETS to ## for an answer format: Q1: #answer# Note: This consists of two characters only, for the opening and closing characters.
USER_NAME_FORMAT	TEXT	IN	The full name of the approver who replies will be retrieved from the WorkflowGen database. The approver’s full name will be returned to the field control in the web form if USER_NAME_FIELDNAME is defined. By default, the user’s full name will be in Firstname Lastname format. You can customize the format by using the control characters L and F, for last name and first name, respectively. For example: John Doe → F L Doe, John → L, F John (Doe) → F (L)
USER_NAME_FIELDNAME	TEXT	IN	Regular web forms can use WorkflowGen macros to obtain the assignee’s full name. In Remote Approval, the approver is defined based on the receipt of the approval reply, a specific parameter is required to return the actual approver’s name back to WorkflowGen. Create this parameter to specify the field control ID that receives the returned approver name. Only TextBox type field control IDs are supported.
USER_FIRSTNAME_FIELDNAME	TEXT	IN	Create this parameter by assigning the field control ID in your form to display the approver’s first name in the WorkflowGen user profile on the form archive page.
USER_LASTNAME_FIELDNAME	TEXT	IN	Create this parameter by assigning the field control ID in your form to display the approver’s last name in the WorkflowGen user profile on the form archive page.
USER_TITLE_FIELDNAME	TEXT	IN	Create this parameter by assigning the field control ID in your form to display the approver’s job title in the WorkflowGen user profile on the form archive page. Only TextBox, RadioButtonList, and DropDownList type field control IDs are supported.
COMMENT_FIELDNAME	TEXT	IN	Create this parameter by assigning the field control ID in your form to display the approver’s comment on the form archive page. Only TextBox type field control IDs are supported. Note: You can specify the control ID by entering the text string or by passing a process data only if the process data contains the ID of the control. If no control ID is found, or the control ID is invalid, no name will be displayed and this parameter will be ignored.
COMMENT_REQUIRED_RESULTS	TEXT	IN	Create this parameter by specifying which approver results will require a mandatory comment. Approver results refer to Qx_RESULT_n parameters. You can enter a comma-separated text string for this parameter to specify more than one result requiring a comment. Example: Q1_RESULT_2,Q2_RESULT_2,Q3_RESULT_1 Here, the second answers of questions 1 and 2 (Q1 and Q2) and the first answer of question 3 (Q3) will require comments. Notes: Mandatory comments require the COMMENT parameter in the action. All required results share the same COMMENT parameter. The approver will receive an email for re-approval if a mandatory comment is missing.
QUICKAPPROVALMODE	TEXT	IN	Quick mode can be enabled or disabled globally for all Remote Approval actions in the Configuration Panel as a default setting. Defining the QUICKAPPROVALMODE parameter for an individual Remote Approval action in a process will override the global default setting. Note: The only text string allowed for this parameter is Y or N.

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

In WorkflowGen version 5.3 or later, 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 folder has the structure year → month → log files.

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.

Error message	Description
Socket Error: No such host is known.	The application was not able to connect to the incoming email server. Check the collector email address settings.
Server Respond: ERR access denied.	There is an error in the username used for the incoming email server. Check the spellings of the incoming email address and password.
Socket Error: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond [server address]:[port number].	The email server is not responding and timed out. Possible reasons:
System Error: The token supplied to the function is invalid.	Possible incorrect email server security. Check the incoming mail server security.
Server Respond: ERR maildrop already locked.	The response email is being locked by the email server.
wfgResponse Error: Remote reply for action (Req #xxxx) cannot be accepted. Action may have already been expired/opened/completed by webform.	The application cannot complete the action, possibly due to an error connecting to WorkflowGen, or the action may have already expired or been closed or completed within the WorkflowGen User Portal.
Cannot clean up temp file ([FILENAME]) yet. It may be still in use.	The application has tried to clean up temporary files in the tmp folder, but the files might still be in use; in this case, the application will skip the removal of this file.
The response for Request #xxxx is in an incorrect format ([YOUR ANSWER]). An email has been sent.	The response is improperly formatted, no keyword has been detected in the email contents, or the keyword is invalid. Check also if Quick mode is enabled.
Email subject does not indicate it is a Remote Approval reply; email has been removed from mailbox.	An email received by the email server does not contain the required prefix RE: that indicates it is a reply to a remote approval request. This email will be automatically removed from the server.
Error parsing request information or reading email header/content before processing reply.	An email received by the email server does not contain all the necessary information such as thread index or the request/action IDs in the subject line that are needed to identify the associated WorkflowGen request action. Check the email server settings if the thread index was discarded, or you can add the request to action IDs in the email notification subject.
The response for Request #XXXX is missing a mandatory comment for answer ([YOUR ANSWER]). An email has been sent.	The response provided requires a mandatory comment. The approver must add COMMENT: [YYYYYY] (or YYYYY if Quick mode is enabled) in the email reply. The email will be automatically removed from the server.
Client found response content type of ‘text/html; charset=utf-8’, but expected ‘text/xml’	The WorkflowGen API web service is not returning a proper XML data. Make sure the \ws folder is enabled as an IIS application.
Applicative error + detail (level 4)	This refers to the exception detail to determine the source of the error. Check the following settings that can cause the application to throw an applicative error: