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.

November 2013

www.microsoft.com/dynamics/ax

2 WORKFLOW APPROVAL VIA EMAIL

Table of Contents

Overview ..................................................................................................... 3

Setup and system configuration .................................................................. 3

Configuring workflow to allow approval from email .................................... 4

Appendix A: Creating a new Windows Azure Service Bus namespace ....... 18

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 ..........................22 Prerequisites .................................................................................................................... 23 Installation ...................................................................................................................... 23

Appendix C: Configuring Service Bus namespace details in workflow

parameters ............................................................................................... 26

Appendix D: Considerations ...................................................................... 27

3

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.

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. Apply the hotfix, located here.

3. Enable the inbound port and system account, as explained in Appendix B: Configuring 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 C: Configuring Service Bus namespace details in workflow parameters.

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.

4 WORKFLOW APPROVAL VIA EMAIL

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.

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.

5

WORKFLOW APPROVAL VIA EMAIL

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, 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.

6 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.

7

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.

8 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**

9

WORKFLOW APPROVAL VIA EMAIL

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

10 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.

11

WORKFLOW APPROVAL VIA EMAIL

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

13. Close the Properties dialog box.

12 WORKFLOW APPROVAL VIA EMAIL

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

13

WORKFLOW APPROVAL VIA EMAIL

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

14 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.

15

WORKFLOW APPROVAL VIA EMAIL

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

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.

16 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.

17

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.

18 WORKFLOW APPROVAL VIA EMAIL

Appendix A: Creating a new Windows Azure Service Bus namespace

After you have set up a Windows Azure account, open Windows Azure Management Portal at https://windows.azure.com/default.aspx.

For more information about the Windows Azure Service Bus, see http://msdn.microsoft.com/en-us/library/windowsazure/ee732537.aspx.

1. Go to your Windows Azure dashboard.

2. In the left navigation pane, click Service Bus.

3. On the Action Pane, click Create to create a new Service Bus namespace.

19

WORKFLOW APPROVAL VIA EMAIL

4. In the Namespace name field, enter a name for your namespace, such as contosomobile, and select your region, as shown in the following illustration.

This namespace is used to reference the Service Bus and the Access Control Service that is tied to the Service Bus.

5. Click OK to create the namespace.

6. Select the Service Bus namespace, and then, on the Action Pane, click Access key to view the default issuer and default key.

20 WORKFLOW APPROVAL VIA EMAIL

7. In the Access key form, click the Copy button to copy the 256-bit default key.

The default issuer and the 256-bit secret default key are used when you configure the Microsoft Dynamics AX Connector for Mobile Applications service that is deployed on the server. For more information, see the Setting up the Microsoft Dynamics AX Connector for Mobile Applications service

section.

This Microsoft Dynamics AX Connector for Mobile Applications deploys a listening endpoint that services the message coming from the Microsoft Dynamics AX mobile phone application. This endpoint address is structured around the Windows Azure namespace that you created.

21

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.

22 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 machine’s 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.

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=false&sid=512hmactzru0t0fs0dcgyvgm&stext=Mobile applications for Dynamics AX.

Use the following procedure to install and configure the Microsoft Dynamics AX Connector for Mobile Applications.

23

WORKFLOW APPROVAL VIA EMAIL

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.

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.

24 WORKFLOW APPROVAL VIA EMAIL

Parameter Configuration

Endpoint URI of

EmailApprovalService

The following text is preconfigured in this field:

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

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.

The following illustration shows the form that is used to configure the parameters for the Microsoft

Dynamics AX Connector for Mobile Applications.

11. Enter values for each parameter, and then click Save.

25

WORKFLOW APPROVAL VIA EMAIL

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.

26 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.

27

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.

28 WORKFLOW APPROVAL VIA EMAIL

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.

© 2013 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.

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