Microsoft Dynamics AX

Workflow
approval via
email
This document highlights the functionality in
Microsoft Dynamics AX 2012 that enables the
configuration of workflows that let users take
approval actions directly from email
messages.

White paper

November 2013

Updated: September 2018

Send feedback.

Learn more about Microsoft Dynamics.

 Contents
What’s new 3

Set up the new functionality 3

Overview 5

Setup and system configuration 5

Configure a workflow to enable approvals from email messages 6

Appendix A: Create a new Service Bus namespace 15

Appendix B: Configure shared access policies 16

Appendix C: Configure Active Directory Federation Services 17

Appendix D: Configure the on-premises server with Microsoft Dynamics AX 2012 and the Microsoft Dynamics AX
Connector for Mobile Applications service 17

Appendix E: Configure Service Bus namespace details in the workflow parameters 22

Appendix F: Apply the 2018 update to migrate from ACS to SAS 22

Appendix G: Considerations 23

Updates since initial publication 23

Workflow approval via email 2

 Workflow approval via email
This document highlights the functionality in Microsoft Dynamics AX 2012 that enables the configuration of
workflows that let users can take approval action directly from email messages.

What’s new
The Approval via email feature has been updated with the following functionality:

● Add comments when you approve or reject a workflow by using the new Approve and Reject links.

● Add attachments to a workflow item to provide additional details.

To use these new features, you must install the following hotfix: KB 2954087. If you’re using cumulative update 8 for
Microsoft Dynamics AX 2012 R3, you don’t have to apply the hotfix, because it’s included in that release.

You must also have the updated version of the Microsoft Dynamics AX Connector for Mobile Applications (the
connector).

Set up the new functionality

1 To use the new Approve and Reject links, replace the existing link strings in the work item instructions with the
following strings. (For an example of work item instructions that use the existing link strings, see step 9 in the
Configuring workflow to allow approval from email section of this document.)

Old link strings:

● Approve: %Workflow.Link to approve%

● Reject: %Workflow.Link to reject%

New link strings:

● Approve: %Workflow.Link to approve with comment%

● Reject: %Workflow.Link to reject with comment%

Workflow approval via email 3

 2 The Settings for workflow form has a new setting that enables attachments to be added. Select the Add
attachments check box, and then close the form.

3 Click System administration > Setup > Windows Store.

4 In the Windows Application Store setup form, select the type of workflow to add a report to. In the following
illustration, a Timesheet document level workflow (TSTimesheetApproval) is selected. When you select
TSTimesheetSignOff on the Report association tab, the Timesheet workflow associates the timesheet sign-off
report with that workflow type.

5 After the report is associated, close the form.

Workflow approval via email 4

 6 Click System administration > Periodic > Email attachments, and create an E-mail attachments batch job. This
step is required only if you’re attaching reports to the email approval. If you aren’t using attachments, you can
continue to use an E-mail processing batch job.

Overview
The Microsoft Dynamics AX workflow infrastructure lets users configure workflows in application modules, with a
specific focus on tasks and approvals. As one of the workflow features, email messages can be configured and sent
that contain links to documents that require action. For example, an employee enters a timesheet, and then submits
it to his or her manager for approval. The manager receives an email message that requests approval. The email
message contains a link to the timesheet that the user entered. One of the most frequently requested capabilities for
this functionality has been for the manager or approver to be able to approve or reject from the email message itself.

In AX 2012, this functionality can now be enabled by applying a hotfix download and then installing the connector.

Note: This hotfix isn’t required if you’re using cumulative update 6 for Microsoft Dynamics AX 2012 R2 or a later
version.

This document explains the setup that is required to enable the feature. It also provides an example that shows how
to define a workflow that uses the new functionality.

Setup and system configuration

This feature builds on the existing workflow capability to send email workflow instructions to approvers who have
been assigned by a workflow. You enable the Approve via email feature by providing Approve and Reject links in
the email message that is sent to approvers. The Approve and Reject links in the message are action URLs that
trigger an approve or reject workflow action when the approver that the message was sent to clicks the
corresponding link.

The action URLs are designed to work in any email client, regardless of whether the email client is on the corporate
network (for example, on a desktop computer in the office) or off the corporate network (for example, on a mobile
phone or tablet). Therefore, the action URL is based on the capabilities of Microsoft Azure Service Bus. The Service
Bus relays the action from the client to the connector. The connector receives the action and then makes a call to
Microsoft Dynamics AX to record the action in the workflow. At that point, the action is completed in the workflow,
just as if the user were using the Microsoft Dynamics AX client or Enterprise Portal for Microsoft Dynamics AX.

Workflow approval via email 5

 For more information about how Service Bus and the connector are used, see the following configuration document:
Configure the Microsoft Dynamics AX environment for Companion Apps.

To enable the feature, you must follow these steps.

1 Set up a Service Bus namespace, as explained in Appendix A: Create a new Service Bus namespace. If the
connector has already been installed so that it can be used with mobile applications, this step isn’t required.
2 If you’re using a version of AX 2012 R2 that is earlier than cumulative update 6, apply the hotfix that is provided
with the KB article, “Approver cannot approve or reject workflow workitems from email notifications directly in
Microsoft Dynamics AX 2012 R2.”

You can find this KB article on PartnerSource by searching for kb2827196.

The hotfix isn’t required if you’re using cumulative update 6 or a later version.

3 Enable the inbound port and system account, as explained in Appendix D: Configure the on-premises server with
Microsoft Dynamics AX 2012 and the Microsoft Dynamics AX Connector for Mobile Applications service.
4 Provide the Service Bus namespace in the appropriate workflow parameter field, as explained in Appendix E:
Configure Service Bus namespace details in the workflow parameters.
5 Install the connector, which is available at https://mbs.microsoft.com/customersource/northamerica/AX/news-
events/news/MSDYN_MobileAppsAX, as explained in the Set up the Microsoft Dynamics AX Connector for Mobile
Applications service section. If the connector has already been installed so that it can be used with mobile
applications, this step isn’t required.
6 Make sure that the workflow is set up to send workflow instructions via email. For more information about email
functionality and workflows, see the following TechNet articles: Configure email functionality in Microsoft
Dynamics AX and Configure email settings for the workflow system.

Important: Step 6 is required for Microsoft Dynamics AX to send email notifications. If step 6 isn’t completed,
email won’t be sent.

Configure a workflow to enable approvals from email

messages
The following steps assume that the user who defines the workflow configuration has Administrator rights. This
example walks you through the process of defining the workflow for an expense report. However, the Approval via
email feature can be used for any workflow type.

1 Sign in to your legal entity, and then click Travel and expense > Setup > Travel and expense workflows.
2 On the Travel and expense workflows list page, on the Action Pane, click New.

Workflow approval via email 6

 3 In the Create workflow form, select Expense report, and then click Create workflow.

4 In the Expense report workflow configuration form, add a conditional decision to the workflow.
a Select the Conditional decision control, and then, on the Action Pane, click Properties.
b Enter a name and condition. In this example, the workflow will let approvers approve or reject expense reports
from email messages if the total amount is less than or equal to 1,000.00 U.S. dollars (USD).
c When you’ve finished, close the Properties form.

Workflow approval via email 7

 5 Add an Approve expense report element to the workspace. Connect it to the True condition of the Conditional
decision control that you added in the last step. In this scenario, the organization wants approvers to be able to
approve or reject expense reports from email messages if the total amount of the expense report is less than
1,000.00 USD.

6 Select the element that you just added, and then, on the Action Pane, click Properties. Enter a name, and then
close the Properties form. No changes are required on the Automatic actions, Notifications, and Advanced
settings tabs.

Workflow approval via email 8

 7 On the Action Pane, click Level down, or double-click the workflow element.

8 In the left pane, select the Step element, and then, on the Action Pane, click Properties.
9 In the Properties form, enter the instruction information.

Based on the condition that you defined earlier, if the total amount of the expense report is less than
1,000.00 USD, the approver will receive the instructions that you define in this step. In this scenario, the
organization wants approvers to be able to accept or reject expense reports from email messages.

The following instruction text is a recommendation. Substitute specific content that is approved by your
organization.

Work item subject:

Please approve this expense report: %Expense report.ExpNumber% from %Expense report.CreatingWorker%

Work item instructions:

Please review and approve or reject the following expense report. You can use the approve or reject links in the
email or follow the more details link to approve it on the expense management website.

Expense report: %Expense report.ExpNumber%

Employee: %Expense report.CreatingWorker%

Purpose: %Expense report.Txt2%

Amount: %Expense report.Total expense report amount% %Expense report.Currency%

Workflow approval via email 9

 Approve: %Workflow.Link to approve%

Reject: %Workflow.Link to reject%

For more details see: %Workflow.Link to web%

Please note there will not be a confirmation upon selecting approve or reject.

**Do not forward**

The following illustration shows an example of the Properties form, where work item approval information and
instructions have been added.

10 In the left pane, click Assignment, and assign users to the workflow step.

Workflow approval via email 10

 11 On the Completion policy tab, select whether approval from one approver, multiple approvers, or all approvers
is required.

12 In the left pane, click Condition, and specify when the approval is required.

13 Close the Properties form.

14 Add another Approve expense report element, and link it to the False condition of the Conditional decision
control that you added earlier.

Workflow approval via email 11

 15 Select the element that you just added, and then, on the Action Pane, click Properties. Enter a name, and then
close the Properties form.

16 On the Action Pane, click Level down, or double-click the workflow element.

17 In the left pane, select the Step element, and then, on the Action Pane, click Properties.

Workflow approval via email 12

 18 In the Properties form, enter the instruction information.

Based on the condition that you defined earlier, if the total amount of the expense report is more than
1,000.00 USD, the approver will receive the instructions that you define in this step. Because of the expense report
total, the organization has decided that approvers should review the expense reports before they take action.
Approvers are directed to the portal where they can review the expense reports and then take action.

The following instruction text is a recommendation. Substitute specific content that is approved by your
organization.

Work item subject:

Please review and approve this expense report: %Expense report.ExpNumber% from %Expense
report.CreatingWorker%

Work item instructions:

Please review the following expense report. Use the link to the portal which will provide you specifics for this expense
report. You can accept or reject the expense report from the portal.

Expense report: %Expense report.ExpNumber%

Employee: %Expense report.CreatingWorker%

Purpose: %Expense report.Txt2%

Amount: %Expense report.Total expense report amount% %Expense report.Currency%

For more details and to approve: %Workflow.Link to web%

**Do not forward**

19 In the left pane, click Assignment, and then, on the Assignment type tab, select User.

Workflow approval via email 13

 20 On the User tab, assign users to the workflow step.

21 On the Completion policy tab, select whether approval from one approver, multiple approvals, or all approvers is
required.

22 In the left pane, click Condition, and specify when the approval step is required.
23 Close the Properties form.

Workflow approval via email 14

 24 Link the two Approve expense report elements to the End element.

25 Click Save and close to close the form and activate the workflow.

Appendix A: Create a new Service Bus namespace

The connector deploys a listening endpoint that services the message that comes from the Microsoft Dynamics AX
companion apps and email approval links. This endpoint address is structured around the Azure namespace that you
create.

To create a new Service Bus namespace, follow these steps.

1 Start Azure PowerShell. For more information, see Overview of Azure PowerShell.
2 At the command prompt, enter the following command to connect Azure PowerShell to your Azure subscription.

Login-AzureRmAccount

3 Enter the following commands to learn the subscriptions that are available and then select one of them.

Get-AzureRmSubscription
Select-AzureRmSubscription -SubscriptionId <"subscriptionId">

Workflow approval via email 15

 4 Enter the following command to create a new Service Bus namespace that has the appropriate Azure region.

New-AzureRmServiceBusNamespace -ResourceGroupName <-resourceGroupName-> -NamespaceName <-

serviceBusName-> -Location <-WestUS->

The Service Bus namespace that you create here will be entered as the Azure Service namespace value in the
connector parameters.

Property Description

-namespaceName Enter the name of the service namespace.

-serviceBusName Enter the name of the Service Bus

-location Enter your region.

If there were no errors, the following information is shown.

Name: [Name]
Region: [Region]
DefaultKey: 2pRUX4K5EhE5XKvDsaS+816/Neezztkgur/CKsib40w=
Status: Active
CreatedAt: 8/26/2014 7:24:31 PM
ServiceBusEndpoint: https://name.servicebus.windows.net/
ConnectionString: Endpoint=sb://SBName.servicebus.windows.net/;SharedSecretIssuer=own
er;SharedSecretValue=2pRUX4K5EhE5XKvDsaS+816/Nrqzztkgur/CKsib40w=

For more information about configuring Microsoft Dynamics AX rapid start connector, see Configure the
Microsoft Dynamics AX environment for Companion Apps..

Appendix B: Configure shared access policies

1 Sign into the Azure portal, and click the Service Bus menu.
2 Find and select the Service Bus that you created in Appendix A: Create a new Service Bus namespace.
3 Under Settings, select Shared access policies. Then click Add.
4 In the Add SAS policy blade, enter a new policy name, such as SendListen, and select the Send and Listen check
boxes. Then click Create.

The SAS policy name that you create here will be entered as the Azure service identity name value in the
connector parameters.

5 Select the new shared access policy (SendListen), and copy the primary key that should be used as the Azure
service identity password value in the connector parameters.

Workflow approval via email 16

 Appendix C: Configure Active Directory Federation Services
Complete the setup of Active Directory Federation Services (AD FS) as described in the Configure the Microsoft
Dynamics AX environment for Companion Apps white paper.

1 Skip the steps to create a new Service Bus namespace, because you completed those steps in Appendix A: Create
a new Service Bus namespace.
2 Complete the steps to configure AD FS for authentication.
3 Complete the steps to update the relying party federation metadata.

Appendix D: Configure the on-premises server with

Microsoft Dynamics AX 2012 and the Microsoft
Dynamics AX Connector for Mobile Applications service
Set up Microsoft Dynamics AX
This section applies to AX 2012 R2 and AX 2012 R3.

Set up inbound ports

1 In Microsoft Dynamics AX, click System Administration > Services and Application integration framework >
Inbound ports.
2 In the Inbound ports form, click New, and enter a name and description for the new inbound port.

Workflow approval via email 17

 3 On the Service contract customizations FastTab, click Service operations. The WSDL URI is automatically
entered.

4 In the Select service operations form, in the Remaining service operations list on the right, select
SysWorkflowApprovalService.applyUrlAction. Then click the left arrow button (<) to add the operation to the
Selected service operations list on the left.

Workflow approval via email 18

 5 Close the Select service operations form, and then, in the Inbound ports form, click Activate.

Create and configure a user account

1 Create a new service account user in Microsoft Dynamics AX. Before you deploy the connector, make sure that
this service account user is present in the computer’s Administrator group. This user will run the connector
service.
2 Make sure that the new service account user has a record in Microsoft Dynamics AX, and that it has System
administrator privileges.

Set up the Microsoft Dynamics AX Connector for Mobile

Applications service
The installer can be found at the following link.

https://mbs.microsoft.com/customersource/northamerica/AX/news-events/news/MSDYN_MobileAppsAX.

Version 8.2.384 (August 2018) is required for any installations after August 2018 that use shared access signatures
(SAS) instead of the Azure Access Control service (ACS).

Use the following procedure to install and configure the connector.

Prerequisites
● Make sure that the service account user that you created in the Create and configure a user account section is an
administrator or part of the Administrator group on the computer where the connector is running.
● Only one instance of the connector can be deployed to run on a computer.

Installation
1 Click Start > All Programs > Microsoft Dynamics AX Connector for Mobile Applications, and start the
Microsoft Dynamics AX Connector for Mobile Applications Setup Wizard.
2 Select the I accept the terms in the License Agreement check box, and then click Next.
3 On the Destination Folder page, accept the default folder location for the connector, or click Change to select
another location. Then click Next.
4 On the Service account page, in the Account name and Password fields, enter the name and password for the
user account that you previously created, and then click Next.
5 Click Install.
6 Click Finish.
7 Click Start > Administrative Tools > Service to open the Services list.

Workflow approval via email 19

 8 Click Start to start the Microsoft Dynamics AX Connector for Mobile Applications service. The service will run
under the context of the service user account.

9 On the Start menu, click the Microsoft Dynamics AX Connector for Mobile Applications shortcut. The
graphical user interface (GUI) for configuring the connector parameters appears.

10 Use the information in the following table to configure the connector parameters.

Parameter Configuration

Azure service Enter the service namespace that you set up in Appendix A: Create a new Service Bus
namespace namespace, and then click Save.

Azure service identity Enter the service identity name that you set up in Appendix A: Create a new Service
name Bus namespace.

Workflow approval via email 20

 Parameter Configuration

Azure service identity Enter the 256-bit symmetric key for the service identity that was generated in
password Appendix A: Create a new Service Bus namespace.

Endpoint URI of The following text is preconfigured in this field:

EmailApprovalsServices
net.tcp://<AOS_MACHINE_NAME>:8201/DynamicsAx/Services/EmailApprovalsServices

Replace <AOS_MACHINE_NAME> with the name of the computer that hosts

Microsoft Dynamics AX Application Object Server (AOS). Replace the default AOS port
number, 8201, if a different port is used.

Important: Don’t use the WSDL port, 8101, as the endpoint URI of
EmailApprovalsServices. Port 8101 is used as the default inbound port for an
instance of AOS.

Note: There might be additional fields that aren’t required for ADFS workflow approvals. Leave those fields set to
their default values.

11 When you’ve finished entering values for the parameters, click Save.
12 After the connector parameters are saved, click Start in the GUI. You can see that the status has changed to
Started. You can also see that the Microsoft Dynamics AX Connector for Mobile Applications service is now
running, and that it’s listening on the Service Bus.

Workflow approval via email 21

 Appendix E: Configure Service Bus namespace details in the
workflow parameters
After you’ve set up and started the connector, you must provide the Service Bus details in the workflow parameters.

1 Click System Administration > Setup > Workflow > Workflow parameters.
2 In the Settings for workflow form, in the Base URL to approve/reject workflow field, enter the Service Bus
details in the following format:

https://namespace.servicebus.windows.net/Email

Replace namespace with the namespace details that you set up in Appendix A: Create a new Service Bus
namespace.

Appendix F: Apply the 2018 update to migrate from ACS to

SAS
If you’re an existing customer, just four steps are required to migrate to the new solution.

1 Follow the steps in Appendix A: Create a new Service Bus namespace to create a new SAS Service Bus.
2 Follow the steps in Appendix B: Configure shared access policies, so that you can provide the key as the Azure
service identity password in the connector parameters.
3 Install the latest connector (8.2.384.0), and update the Azure service namespace, Azure service identity name, and
identity password from the previous steps.

Note: The latest connector is not backwards compatible with ACS. Once the latest update is applied it will no
longer work with ACS. The previous ACS solution is set to be deprecated on Nov 7, 2018.

4 In AX 2012, In the Settings for workflow form, update the Base URL to approve/reject workflow field with the
details of the new Service Bus.

Workflow approval via email 22

 Appendix G: Considerations
When you choose to enable this feature, consider the following points:

● The action URL that is included in the email message isn’t authenticated to the intended user. Any user who has
access to the message can click the action link. For example, if a user forwards the message to another user, the
new recipient of the message can complete the approve or reject action. We recommend that the email message
include a reminder not to forward it. As a mitigation, each action URL can be used only one time. Therefore, if a
message is inadvertently forwarded, only one action can be completed.
● The call to the Service Bus via the action URL isn’t authenticated. However, the action URL includes a secret
globally unique identifier (GUID). This secret GUID is of considerable length and is required to take the approve or
reject action. The connector also applies throttling if it detects repeated failed attempts. The Application
Integration Framework (AIF) service requires that a valid GUID (such as the GUID that is embedded in the action
URL) be presented. This requirement helps protect the AIF service. If the GUID isn’t valid, no action is taken.

Updates since initial publication

The following table lists the changes that have been made to this document since it was originally published in
November 2013.

Date Description

September 2014 ● Corrected inconsistent use of parameter names in the instructions for installing the
connector. All instances have been changed to EmailApprovalsServices.
● Added content to indicate that the hotfix that is available from KB 2827196 isn’t
required for cumulative update 6 for AX 2012 R2 or later versions.
● Added a note to indicate that the WSDL port, 8101, should not be used as the
endpoint URI of EmailApprovalsServices, because it’s used as the default inbound
port for an instance of AOS.

September 2018 ● Added support for SAS based service bus for workflow approval via email feature.

Workflow approval via email 23

Send feedback. © 2018 Microsoft Corporation. All rights
reserved.
Microsoft Dynamics is a line of integrated, adaptable business
management solutions that enables you and your people to make This document is provided “as-is.”
business decisions with greater confidence. Microsoft Dynamics works Information and views expressed in this
like and with familiar Microsoft software, automating and streamlining document, including URL and other
financial, customer relationship, and supply chain processes in a way Internet Web site references, may
that helps you drive business success. change without notice. You bear the risk
of using it.
United States and Canada toll-free: (888) 477-7989
Some examples are for illustration only
Worldwide: (1) (701) 281-6500
and are fictitious. No real association is
dynamics.microsoft.com intended or inferred.

This document does not provide you

with any legal rights to any intellectual
property in any Microsoft product. You
may copy and use this document for
your internal, reference purposes.