Microsoft Dynamics AX

Workflow approval via email

White Paper
This document highlights the functionality in Microsoft Dynamics
AX 2012 R2 that allows workflow to be configured so that a user
can take approval action directly from email messages.

Date: November 2013

Updated: September 2014
www.microsoft.com/dynamics/ax

Table of Contents

Whats New ................................................................................................. 3

Setting up the new functionality ................................................................. 3
Overview..................................................................................................... 5
Setup and system configuration .................................................................. 5
Configuring workflow to allow approval from email .................................... 6
Appendix A: Creating a new Windows Azure Service Bus namespace ....... 20
Appendix B: Configuring the on-premises server with Microsoft Dynamics
AX 2012 and the Microsoft Dynamics AX Connector for Mobile Applications
service ...................................................................................................... 21
Microsoft Dynamics AX 2012 and Microsoft Dynamics AX 2012 R2 .............................................21
Set up inbound ports ......................................................................................................... 21
Create and configure a user account in Microsoft Dynamics AX ............................................... 22
Setting up the Microsoft Dynamics AX Connector for Mobile Applications service ..........................23
Prerequisites .................................................................................................................... 23
Installation ...................................................................................................................... 23

Appendix C: Configuring Service Bus namespace details in workflow

parameters ............................................................................................... 26
Appendix D: Considerations ...................................................................... 27
Updates since initial publication ............................................................... 27

2
WORKFLOW APPROVAL VIA EMAIL

Whats New
The Approval via email feature has been updated with the following functionality:

Add comments when you approve or reject a workflow with links.

Add attachments to a workflow item to provide additional details.

To use these new features, youll need to install the following hotfix. If you are using Microsoft
Dynamics AX 2012 R3 CU8, you dont need to apply the hotfix because it is included in this release.
You will also need the updated mobile connector that can be found here.

Set up the new functionality

1. To use the new approve or reject links, replace the existing strings in the workflow (an
example can be found on page 11 of this document) with the following strings:

Old links

Approve: %Workflow.Link to approve%

Reject: %Workflow.Link to reject%

New links

Approve: %Workflow.Link to approve with comment%

Reject: %Workflow.Link to reject with comment%

The Workflow parameters form now has a new option for adding attachments.

3
WORKFLOW APPROVAL VIA EMAIL

2. Select the check box, and then close the form.

3. Open the Windows Application Store setup form by clicking System administration >
Setup > Windows Store.

4. Select the workflow type you would like to add a report to. In the screen shot above, you can
see that a Timesheet document level workflow is selected. By selecting
TSTimesheetSignOff on the Report association tab, the Timesheet workflow associated
the timesheet sign off report with that workflow type.
5. After the report is associated, close the form.

6. Click System administration > Periodic > Email attachments to create an email attachments
batch job. This is only required if you are attaching reports to the email approval. You can still use the
E-mail processing batch if you are not using attachments.

4
WORKFLOW APPROVAL VIA EMAIL

Overview
The Microsoft Dynamics AX workflow infrastructure empowers users to configure workflow 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 actions. For
example, an employee enters a timesheet, and then submits it to his or her manager for approval.
The manager receives an email message requesting approval. The email message contains a link to
the timesheet that the user entered. One of the most common requests related to this functionality
has been for the capability for the manager or approver to approve or reject from the email message
itself.
In Microsoft Dynamics AX 2012 R2, this functionality can now be enabled by applying a hotfix
download and then installing the Microsoft Dynamics AX Connector for Mobile Applications.
Note: This hotfix is not required if you are running cumulative update 6 for Microsoft Dynamics AX
2012 R2 or later versions.
This document explains the setup that is required to enable the feature and provides an example of
defining workflow with 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 workflow. The approve via email feature is enabled 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 to
whom the message is sent clicks the corresponding link.
The action URL is designed to work on any email client, and it works whether the email client is on the
corporate network (for example, on a desktop machine in the office) or off the corporate network (for
example, on a mobile phone or tablet). As such, the action URL is based on the capabilities of the
Microsoft Windows Azure Service Bus. The Service Bus relays the action from the client to the
Microsoft Dynamics AX Connector for Mobile Applications (the connector). The connector receives the
action and then makes a call to Microsoft Dynamics AX to record the action in workflow. At that point,
the action is completed in workflow, just as if the user were using the Microsoft Dynamics AX client or
Enterprise Portal for Microsoft Dynamics AX.
For a broader understanding of the use of the Windows Azure Service Bus and the Microsoft Dynamics
AX Connector for Mobile Applications, see the following configuration document:
https://mbs.microsoft.com/downloads/customer/AX/ConfigureAXConnectorforMobileApplications.pdf.
You must follow these steps to enable this feature:
1. Set up a Windows Azure Service Bus, as explained in Appendix A: Creating a new Windows Azure
Service Bus namespace. If the connector has already been installed for use with mobile
applications, this step is not necessary.
2. If you are using a version of Microsoft Dynamics AX 2012 R2 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 locate the KB article in PartnerSource by searching for kb2827196.
The hotfix is not required if you are using cumulative update 6 for Microsoft Dynamics AX 2012 R2
or a later version.
3. Enable the inbound port and system account, as explained in Appendix B: Configuring the onpremises 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 C: Configuring Service Bus namespace details in workflow parameters.
5
WORKFLOW APPROVAL VIA EMAIL

5. Install the connector, which is available at

https://mbs.microsoft.com/downloads/customer/AX/AXConnectorForMobileApplications.zip, as
explained in the Setting up the Microsoft Dynamics AX Connector for Mobile Applications service
section. If the connector has already been installed for use with mobile applications, this step is
not necessary.
6. Make sure that workflow is set up to send workflow instructions via email. For more information
about email functionality and workflow, see the TechNet articles, Configure email functionality in
Microsoft Dynamics AX and Configure email settings for the workflow system.
Completing step 6 is required for Microsoft Dynamics AX to send email notifications. If step 6 is
not completed, email will not be sent.

Configuring workflow to allow approval from email

The following steps assume that the user has Administrator rights when defining the workflow
configuration. This example walks you through the process of defining the workflow for an expense
report; however, the capability to allow approvals through email can be used for any workflow type.
1. Sign in to your legal entity, and then go to Travel and expense > Setup > Travel and
expense workflows.
2. On the Travel and expense workflows list page, on the Action Pane, click New.
A Create workflow dialog box is displayed.
3. Select Expense report, and then click Create workflow.

4. In the Expense report workflow configuration form, add a conditional decision to workflow.
Select the control, and then click Properties. Enter a name and condition. In this example,

6
WORKFLOW APPROVAL VIA EMAIL

workflow will allow approvers to approve or reject expense reports from email if the total amount
is less than or equal to 1,000.00 USD. After you have finished, close the Properties dialog box.

7
WORKFLOW APPROVAL VIA EMAIL

5. Add an Approve expense report element to the workspace. Connect it to the True condition of
the element 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 if the total expense report is less than
1,000.00 USD.

8
WORKFLOW APPROVAL VIA EMAIL

6. Select the Approve expense report element, and then select Properties. Enter a name. No
changes are needed on the Automatic actions, Notifications, or Advanced settings tab. Close
the Properties dialog box.
7. On the Action Pane, click Level down, or double-click the workflow element.

8. In the left pane, select the Step 1 component, and then, on the Action Pane, click Properties.

9
WORKFLOW APPROVAL VIA EMAIL

9. Enter the instruction information.

Based on the condition that you defined earlier, if the total 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.
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%
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**

10
WORKFLOW APPROVAL VIA EMAIL

The following illustration shows the Properties form, where you can add work item approval
information and instructions.

11
WORKFLOW APPROVAL VIA EMAIL

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

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

12
WORKFLOW APPROVAL VIA EMAIL

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

13. Close the Properties dialog box.

13
WORKFLOW APPROVAL VIA EMAIL

14. Add another Approve expense report element, and link it to the False condition.

14
WORKFLOW APPROVAL VIA EMAIL

15. Select the False approval step, and define the properties. Enter a name, and then close the
Properties dialog box.

15
WORKFLOW APPROVAL VIA EMAIL

16. Select the highlighted workflow element, and then, on the Action Pane, click Level down, or
double-click the workflow element to select the step within the workflow element.

17. On the Action Pane, click Properties.

18. In the Properties form, enter the instruction information.
Based on the condition that you defined earlier, if the total 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 these

16
WORKFLOW APPROVAL VIA EMAIL

expense reports before taking 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 on the Assignment Type tab, select User.

17
WORKFLOW APPROVAL VIA EMAIL

20. Click the User tab to assign users to Step 1.

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

22. In the left pane, click Condition to specify when the approval step is required.
23. Close the Properties dialog box.

18
WORKFLOW APPROVAL VIA EMAIL

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.

19
WORKFLOW APPROVAL VIA EMAIL

Appendix A: Creating a new Windows Azure Service Bus

namespace
Note: As of August 2014, you cannot use the Azure Management Portal to create a service bus
namespace. You must use Azure PowerShell to create the service bus service namespace.
The Microsoft Dynamics AX Connector for Mobile Applications deploys a listening endpoint that
services the message coming from the Microsoft Dynamics AX companion apps and email approval
links. This endpoint address is structured around the Windows Azure namespace that you will create.
To create a new service bus namespace, complete the following steps:
1. Open Azure PowerShell. Details can be found here.
2. In the PowerShell command prompt, enter the following command to connect Azure
PowerShell to your Azure subscription:
Add-AzureAccount

3. When prompted, enter your credentials for your Azure subscription.

4. In the PowerShell command prompt, enter the following command to add a new service bus
service namespace:
New-AzureSBNamespace name InsertNameHere location InsertRegionHere

Property

Description

-name

Enter the name of the service namespace.

-location

Enter your region. The list of region values

5. If you followed the steps correctly and there were no errors, the following information is
displayed.

Name:
Region:
DefaultKey:
Status:
CreatedAt:
AcsManagementEndpoint:
ServiceBusEndpoint:
ConnectionString:

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

Copy the DefaultKey, ServiceBusEndpoint, and ConnectionString for reference later. You will use the 256-bit secret
default key when you configure the Microsoft Dynamics AX Connector for Mobile Applications service that is
deployed on the server. For more details, see Configuring the on-premises server for Companion apps.

20
WORKFLOW APPROVAL VIA EMAIL

Appendix B: Configuring the on-premises server with

Microsoft Dynamics AX 2012 and the Microsoft Dynamics
AX Connector for Mobile Applications service
Microsoft Dynamics AX 2012 and Microsoft Dynamics AX 2012 R2
Set up inbound ports
1. In Microsoft Dynamics AX, click System Administration > Services and Application
integration framework > Inbound ports.
2. Click New, and enter a name and description.
3. Under Service contract customizations, click Service operations. The WSDL URI is populated.

21
WORKFLOW APPROVAL VIA EMAIL

4. In the list of operations on the right side of the Select service operations form, select the
SysWorkflowApprovalService.applyUrlAction service operation, and then click < to add it to
the list on the left side of the form.

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

Create and configure a user account in Microsoft Dynamics AX

1. Create a new service account user, and make sure that the service account user is present in the
machines Administrator group before you deploy the Microsoft Dynamics AX Connector for
Mobile Applications service on the machine. This user will run the connector service.
2. Make sure that this new service account user has a record in Microsoft Dynamics AX and has been
given System administrator privileges.

22
WORKFLOW APPROVAL VIA EMAIL

Setting up the Microsoft Dynamics AX Connector for Mobile

Applications service
The installer can be found at
https://mbs.microsoft.com/partnersource/newsevents/news/msdyn_mobileappsax.htm?printpage=fals
e&sid=512hmactzru0t0fs0dcgyvgm&stext=Mobile applications for Dynamics AX.
Use the following procedure to install and configure the Microsoft Dynamics AX Connector for Mobile
Applications.

Prerequisites

Make sure that the service account user that you created in the Create and configure a user
account in Microsoft Dynamics AX section is an administrator or part of the Administrator group
on the machine that the Microsoft Dynamics AX Connector for Mobile Applications is running on.

Only one instance of the Microsoft Dynamics AX Connector for Mobile Applications can be deployed
to run on a machine.

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 Windows Services list.
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 GUI for configuring the connector parameters opens.

23
WORKFLOW APPROVAL VIA EMAIL

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

Configuration

Azure service namespace

Enter the service namespace that you set up in the Creating a new
Windows Azure Service Bus namespace section, and then click Save.

Azure service identity name

Enter the service identity name that you set up in the Creating a new
Windows Azure Service Bus namespace section.

Azure service identity password

Enter the 256-bit symmetric key for the service identity that was
generated in the Creating a new Windows Azure Service Bus namespace
section.

Endpoint URI of
EmailApprovalsServices

The following text is preconfigured in this field:

net.tcp://<AOS_MACHINE_NAME>:8201/DynamicsAx/Services
/EmailApprovalsServices
Replace <AOS_MACHINE_NAME> with the name of the machine that
hosts Microsoft Dynamics AX Application Object Server (AOS).
Replace the default AOS port number, 8201, if a different port is used.
Important: Do not use the WSDL port, 8101, as the endpoint URI of
EmailApprovalsServices. This is used as the default inbound port for an
instance of AOS.

The following illustration shows the form that is used to configure the parameters for the Microsoft
Dynamics AX Connector for Mobile Applications.

24
WORKFLOW APPROVAL VIA EMAIL

11. Enter values for each parameter, and then click Save.
12. After the connector parameters are saved, click Start in the form. You can see that the status has
changed to Started, and that the Microsoft Dynamics AX Connector for Mobile Applications service
is now running and listening on the Service Bus.

25
WORKFLOW APPROVAL VIA EMAIL

Appendix C: Configuring Service Bus namespace details in

workflow parameters
After setting up and starting the Microsoft Dynamics AX Connector for Mobile Applications, provide the
Service Bus details in the workflow parameters form.
1. Go to System Administration > Setup > Workflow > Workflow parameters.

2. 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 the section, Appendix A:
Creating a new Windows Azure Service Bus namespace.

26
WORKFLOW APPROVAL VIA EMAIL

Appendix D: Considerations
In choosing to enable this feature, consider the following points:

The action URL that is included in the email message is not 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 recipient of the message could complete the approve or reject
action. We recommend that you include a reminder not to forward the email message in the
message. As a mitigation, each action URL can be used only one time, so that inadvertent
forwarding enables only a single action.

The call to the Service Bus via the action URL is not authenticated. However, the action URL does
contain a considerably long secret GUID that 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 is protected by the requirement that a value GUID (which is embedded in
the action URL) be presented. If the GUID is not valid, no action is taken.

Updates since initial publication

The following table lists changes made to this document after it was initially published.
Date

Changes

September 2014

Corrected inconsistent use of parameter names in the instructions

for installing the Microsoft Dynamics AX Connector for Mobile
Applications. All instances have been changed to
EmailApprovalsServices.

Added content to indicate that the hotfix available from KB 2827196

is not required for cumulative update 6 for Microsoft Dynamics 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 is
used as the default inbound port for an instance of AOS.

27
WORKFLOW APPROVAL VIA EMAIL

Microsoft Dynamics is a line of integrated, adaptable business management solutions that enables you and your
people to make business decisions with greater confidence. Microsoft Dynamics works like and with familiar
Microsoft software, automating and streamlining financial, customer relationship and supply chain processes in a
way that helps you drive business success.
U.S. and Canada Toll Free 1-888-477-7989
Worldwide +1-701-281-6500
www.microsoft.com/dynamics

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the
date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a
commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of
publication.
This white paper is for informational purposes only. Microsoft makes no warranties, express or implied, in this document.
Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of
this document may be reproduced, stored in, or introduced into a retrieval system, or transmitted in any form or by any means
(electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of
Microsoft Corporation.
Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject
matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this
document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.
2014 Microsoft Corporation. All rights reserved.

Microsoft, Microsoft Dynamics, and the Microsoft logo are either registered trademarks or trademarks of Microsoft Corporation in
the United States and/or other countries.

28
WORKFLOW APPROVAL VIA EMAIL