The Remote Approval feature lets a user 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 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.
Remote Approval requires additional parameters to be added to an EFORMASPX action. These parameters are to define the questions for remote approver and mapping of the approver’s response to the action.
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.
FORM_DATA (IN/OUT | FILE | required): This is an IN/OUT parameter that holds the WorkflowGen request form data file. This is a default parameter for EFORMASPX actions.
FORM_ARCHIVE (OUT | FILE | default): Remote Approval requires passing the FORM_ARCHIVE process data as 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.
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.
KEYWORDS_BRACKETS (IN | TEXT | optional): To answer a Remote Approval question in regular approval mode, you must follow a pre-defined syntax:
The square brackets (
]) 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
## for an answer format:
Note: This consists of two characters only, for the opening and closing characters.
Qx_KEYWORDS_n (IN | TEXT | default): See the Email customization section for details on this parameter.
Qx_RESULT_n (IN | TEXT | default): See the Email customization section for details on this parameter.
Qx_RETURN_FIELDNAME (IN | TEXT | default): 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
USER_NAME_FORMAT (IN | TEXT | optional): 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 the "Firstname Lastname" format. You can customize the format by using the control characters
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 (IN | TEXT | optional): 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 (IN | TEXT | optional): 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 (IN | TEXT | optional): 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 (IN | TEXT | optional): 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 (IN | TEXT | optional): 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 (IN | TEXT | optional): 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. For example:
Here, the second answers of questions 1 and 2 (
Q2) and the first answer of the third question (
Q3) will require comments.
Mandatory comments require the
COMMENT parameter in the action.
All required results share the same
The approver will receive an email for re-approval if a mandatory comment is missing.
QUICKAPPROVALMODE (IN | TEXT | optional): 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
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,
No). To do this, three main parameters are used:
Qx_KEYWORDS_n holds a list of possible keywords (comma-separated) for choice
Qx_RESULT_n: holds the normalized answer for choice
Qx_RETURN_FIELDNAME specifies the web form field name that holds the final normalized answer for question
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.
In this example, there are two Y/N questions in a Remote Approval action:
If the approver replies
ok to question 1 and
bad to question 2, the final normalized answers for questions 1 and 2 will be
If you need to define more than two choices, you must add a new keywords/result combination. For example:
You can define as many keyword/result combinations as you need.
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_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).
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).
An approval email contains the following:
What is your choice?Question 1: Y or NQuestion 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
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
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:
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:
The email subject line cannot be empty.
The reply email should have the same email header key (
Thread-Index) as registered for the associated request action in the WorkflowGen database.
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.
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.
Note: 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:
Enable Subject line validation on the Remote Approval tab in the Configuration Panel.
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
The following is an example of an email subject line containing the WorkflowGen request and action IDs:
Authorization for expenditure required #1374-4
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_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.
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.
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]
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.
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]
A custom email notification must be defined in order to distribute Remote Approval emails to approvers.
The creation of custom notifications follows the same rules as any other WorkflowGen custom notification; all WorkflowGen macros are supported (see the Custom notificaton templates section for more information)
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:
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.
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.
Note: 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 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.
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.
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
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
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).
Note: 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.
The following table provides brief explanations of some possible error messages found in the Remote Approval log.
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
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
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
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
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: