Embed Size (px)
Citation preview
Solution Design Document
Dynamics AX Email Approvals
Page 2 of 47
Preface
It is my pleasure to share this document and the knowledge contained within with our community. The
purpose of this Solution Design Document is to set forth an industry best practices approach for utilizing a
single document to capture a comprehensive strategy for requirements, analysis, design, and implementation
in support of implementing Email based notifications and approvals for Dynamics AX 2012 R3. Should you
have any questions or feedback about the content of this document, feel free to contact me.
Ranny Grubb
Chief Technologist
Pillow Rock Group, LLC
Page 3 of 47
Table of Contents
1. PROJECT OVERVIEW ..................................................................................................................................... 4
2. VISION AND SCOPE ......................................................................................................................................... 4
2.1 VISION STATEMENT ........................................................................................................................................ 4 2.2 PROJECT SCOPE .............................................................................................................................................. 5
3. REQUIREMENTS .............................................................................................................................................. 6
3.1 ACTORS/USERS ............................................................................................................................................... 6 3.2 USE CASE SUMMARY ..................................................................................................................................... 6 3.3 NON-FUNCTIONAL REQUIREMENTS ................................................................................................................ 8
4. SOLUTION ARCHITECTURE ....................................................................................................................... 10
4.1 SOLUTION OVERVIEW .................................................................................................................................. 10 4.2 APPLICATION DESIGN AND CONFIGURATION ................................................................................................ 12
4.2.1 User Option Configuration .................................................................................................................. 12 4.2.2 Email Processing Configuration .......................................................................................................... 14 4.2.3 Email Templates .................................................................................................................................. 16 4.2.4 Workflow configuration ....................................................................................................................... 19
5.1 INTEGRATION ARCHITECTURE AND DESIGN ................................................................................................. 23 5.1.1 Configure the Microsoft Azure Service Bus ......................................................................................... 24 5.1.2 Setup Inbound Port for Email Approval Service.................................................................................. 27 5.1.3 Install and Configure Dynamics AX Connector for Mobile Applications ............................................ 30 5.1.4 Configure Service Bus Namespace URL in Workflow Parameters ...................................................... 37
6.1 INFRASTRUCTURE DESIGN AND CONFIGURATION ......................................................................................... 39 7.1 SECURITY DESIGN AND CONFIGURATION ..................................................................................................... 41
7.1.1 Authentication ...................................................................................................................................... 41 7.1.2 Authorization ....................................................................................................................................... 42 7.1.3 Risks and Exposures ............................................................................................................................ 42
5. SOLUTION IMPACT ASSESSMENT ............................................................................................................ 43
6. COST DETAILS ................................................................................................................................................ 44
7. CONSTRAINTS, RISKS, AND ISSUES ......................................................................................................... 44
8. DEPLOYMENT AND IMPLEMENTATION PLAN .................................................................................... 44
9. REFERENCE..................................................................................................................................................... 46
10. CHANGE LOG .............................................................................................................................................. 47
Page 4 of 47
1. PROJECT OVERVIEW
In the current Dynamics implementation, there are multiple workflows with approval paths
including requisition, vendor invoice, vendor invoice journal, general journal, and budget register
entries. Approvers currently get a notification within the Dynamics client that one of the documents
is awaiting their approval. For many of these approvers, the only reason they ever log into AX is to
complete these approvals. In many cases, they are unaware there are documents awaiting their
approval. The submitter may ask them to approve face to face, via phone call or via email.
This project will focus on implementing approval by email. When a document is moving through
a workflow and requires approval, the approver will be notified via email that a document is
awaiting their approval. They will then have the option to APPROVE, REJECT or click on a link to be
taken to the Work List in the AX Role Center where they can then access the document.
2. VISION AND SCOPE
2.1 VISION STATEMENT
A user will submit a purchase requisition, direct vendor invoice, vendor invoice journal, general
journal, or budget register entry for approval. The approver will receive an email similar to the
following. The email will provide details about the transactions as well as any notes from the
submitter. The approver will then be able to click on a link to “Approve” or “Reject” the document.
Page 5 of 47
They will then be taken to a web page where they may enter necessary comments before
approving or rejecting the document.
This will prevent the approver from having to login to AX and will allow them complete the
approval from their computer, tablet, or other mobile device resulting in more efficient and timely
approvals.
2.2 PROJECT SCOPE
This solution will support email-based approvals for the following entities:
This solution will support email-based approvals for the following types of documents in Dynamics:
Purchase Requisition
Direct Vendor Invoice
Vendor Invoice Journal
General Journal
Budget Register Entry
Page 6 of 47
3. REQUIREMENTS
This section of the document is intended to capture the requirements for support of email-based
approvals in Dynamics. These requirements will identify the users(actors) involved in the approval
process, specific use cases these users are involved in through the approval process, and any non-
functional requirements such as technical or security requirements which must be considered when
implementing this functionality.
3.1 ACTORS/USERS
The following users are presented as roles so that the individual’s filling the role can change over
time. These users are the players in the use cases in the following sections.
ACTOR/USER DESCRIPTION
1. Submitter The submitter is the user who will be creating and submitting a document
for approval. This may involve preparation and submission of a purchase
requisition, direct vendor invoice, vendor invoice journal, general journal, or
budget register entry.
2. Approver The approver is the user responsible for approving a transaction. Once a
document is submitted into workflow for approval, the approver will get a
popup notification in Dynamics notifying them they have a document ready
for approval.
3. Dynamics(AX) Microsoft Dynamics AX application.
4. SMTP
Gateway
SMTP Mail Relay
5. Azure Microsoft Azure is a cloud computing service created by Microsoft for
building, testing, deploying, and managing applications and services
through a global network of Microsoft-managed data centers.
3.2 USE CASE SUMMARY
A use case is a list of actions or event steps typically defining the interactions between an actor and
a system to achieve a goal. The actor can be a human or other external system.
ID USE CASE DESCRIPTION
UC1 Purchase Requisition Notification Once a purchase requisition is submitted for
approval by the Submitter, AX should notify
the Approver via email they have a requisition
awaiting their approval. This email should
have detailed information about the
transaction including:
Description of the transaction
Description of each line on the transaction
Financial dimensions for each line on the
transaction
Status of budget check
Comments from Submitter
Page 7 of 47
ID USE CASE DESCRIPTION
UC2 Direct Invoice Notification Once a direct vendor invoice submitted for
approval by the Submitter, AX should notify
the Approver via email they have an invoice
awaiting their approval. This email should
have detailed information about the
transaction including:
Description of the transaction
Description of each line on the transaction
Financial dimensions for each line on the
transaction
Status of budget check
Comments from Submitter
UC3 Vendor Invoice Journal Notification Once a vendor invoice journal is submitted for
approval by the Submitter, AX should notify
the Approver via email they have an invoice
journal awaiting their approval. This email
should have detailed information about the
transaction including:
Description of the transaction
Description of each line on the transaction
Financial dimensions for each line on the
transaction
Status of budget check
Comments from Submitter
UC4 General Journal Notification Once a general journal is submitted for
approval by the Submitter, AX should notify
the Approver via email they have a general
journal awaiting their approval. This email
should have detailed information about the
transaction including:
Description of the transaction
Description of each line on the transaction
Financial dimensions for each line on the
transaction
Status of budget check
Comments from Submitter
UC5 Budget Register Entry Notification Once a budget register entry is submitted for
approval by the Submitter, AX should notify
the Approver via email they have a budget
register entry awaiting their approval. This
email should have detailed information about
the transaction including:
Description of the budget register entry
Page 8 of 47
ID USE CASE DESCRIPTION
Comments from Submitter
UC6 Email Relay and Distribution AX should forward email notifications to the
SMTP Gateway for distribution. For internal
addresses, the gateway will forward the
message to Groupwise. For external
addresses such as or users, the
gateway should forward the message to the
appropriate Internet mail relay for delivery.
UC7 Approver Approves Transaction The Approver will receive an email notification
from AX that a document is ready for their
approval. Once they review the information in
the email, the Approver should have the
ability to click on a link to approve the
transaction.
UC7.1 The Approver should receive
acknowledgement that the transaction has
been approved.
UC8 Approver Rejects Transaction The Approver will receive an email notification
from AX that a document is ready for their
approval. Once they review the information in
the email, the Approver should have the
ability to click on a link to reject the
transaction.
UC8.1 The Approver should have the ability
to provide comments as part of the rejection
process.
UC8.2 The Approver should receive
acknowledgement that the transaction has
been rejected.
UC9 AX Notifies Submitter Transaction is
Rejected
If a transaction is rejected by the Approver,
the Submitter should be notified the
transaction has been rejected.
3.3 NON-FUNCTIONAL REQUIREMENTS
This section of the solution design contains a summary of the non-functional requirements. Non-
functional requirements are requirements that are not directly tied to a functional use case. This
may involve technical requirements, security requirements, process requirements, or other types of
requirements.
ID REQUIREMENT DESCRIPTION
NF1 Support for Mobile Devices Approvers should be able to use a mobile
device such as an iPad or iPhone to receive a
Page 9 of 47
ID REQUIREMENT DESCRIPTION
notification and complete the subsequent
approval or rejection of the transaction.
NF2 Support for Selectable Notifications Some users may wish to handle all approvals
from within Dynamics. The system should
support the ability to choose to have an
Approver receive or not receive notifications
via email.
Page 10 of 47
4. SOLUTION ARCHITECTURE
This section of the solution design defines the solution architecture which will be utilized to
accomplish the project and realize the requirements which were identified in the previous section.
The solution architecture will vary across types of projects and can have unique components related
to a specific project. Typically, the solution design should cover the following design components.
Solution Overview
Application Design and Configuration
Interface and Integration Design and Configuration
Infrastructure Design and Configuration
Security Design and Configuration
These are the foundational components which typically make up a solution. Depending on the type
of project, one or more of these components may not be applicable. In addition, for some solutions,
there may be other design components that should be included.
4.1 SOLUTION OVERVIEW
Microsoft Dynamics AX 2012 R3 “Workflow Approval via Email” is a feature that will be utilized to
achieve the results for this solution.
This feature builds on the existing workflow capability to send email workflow instructions to
approvers who have been assigned by workflow. This feature is enabled by providing Approve and
Page 11 of 47
Reject links in the email message that is sent to approvers. The Approve and Reject links in the
message are action URLs that trigger the 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 internal network (for example, on a desktop computer) or outside off the network (for example,
on a mobile phone or tablet or at or ). 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.
Page 12 of 47
4.2 APPLICATION DESIGN AND CONFIGURATION
For the email notification and approval to work, there are a number of configuration items which
need to be completed in Dynamics. The following sections outline the necessary configuration to
support email notification and approval.
User Option Configuration
E-mail Processing Configuration
E-mail Templates
Workflow Configuration
4.2.1 USER OPTION CONFIGURATION
A user’s ability to receive a workflow email notification is dependent upon a setting in the user’s
profile. This must be set for each user that needs to receive notifications via email.
After opening the user profile, click on Options to show the following configuration. On the General
tab, you must ensure a valid E-mail address is configured.
Page 13 of 47
Next, click on the Notifications tab and ensure the “Send notifications in email” is checked under
Workflow notifications.
This must be completed for each user that needs to receive workflow notifications through email.
Page 14 of 47
4.2.2 EMAIL PROCESSING CONFIGURATION
In order for AX to process email, it is necessary to implement the Email Distribution Batch Job. This
batch job runs at the selected interval and will process the sending of email messages that are in
the queue. There are a few configuration steps which need to occur.
First, you must configure AX’s general capability to send email. If you have an existing internal
SMTP server/relay, it will be as simple as going to System Administration>Setup\System\Email
Parameters and supplying the appropriate information for the SMTP server as shown below.
If there is no existing SMTP server, then you can implement the Microsoft SMTP Server which is
part of Internet Information Services(IIS) on Windows Server.
After setting these parameters, the next step is to configure the email batch processing job. This
can be completed by going to System Administration>Periodic\E-mail processing. You will see
several options as follows.
Click on Batch to configure the batch job which will process email messages as follows. Make
sure you click on Recurrence to configure the job to run frequently.
Page 15 of 47
Once this job is configured, you should then be able to go to System
Administration>Inquiries>Batch Jobs>Batch jobs and see the job in the batch queue as follows.
If you want to be able to monitor the status of email messages, you can simply click on System
Administration>Periodic\E-mail processing and then click on E-mail sending status.
Page 16 of 47
The following window will appear where you can see the status of email waiting to be sent as well
as a log of email messages which have been successfully sent. From this window, you can also
click and view the actual message content that was sent as well.
4.2.3 EMAIL TEMPLATES
An email template functions as the structure within which additional information is embedded and
sent. The email template is used to specify basic information such as Sender Name, Sender E-mail
Address, and Priority of the message. In addition, you can also include basic text you want to
appear in every email as well as embedding content specific messages which are specific to the
workflow which is in progress. Once an email template is created, that email template is then
associated to the workflow. The workflow will then use that email template to send alerts and
notifications. You could have a single email template which is used for all workflows but I have
found that having one template per workflow makes more sense because there is some information
that is unique to the respective workflow.
To create the E-Mail Templates, go to Organization Administration>Setup and click on E-Mail
templates. From there, you can click on File>New to create a new template.
Page 17 of 47
From there, you will supply the highlighted information as shown below.
Once the basic information is completed, you will then be able to further customize the template
in the lower pane of the window where you can specific a Subject for the email and choose
whether the email template will be in HTML or XSLT format. You can then click on the E-Mail
Message button to further customize the body of the email.
Page 18 of 47
The message can be formatted, and can include %variables% that are replaced by data when the
workflow notification email is transmitted. A full list of the placeholders can be found on Technet
at: https://technet.microsoft.com/en-us/library/aa834423.aspx, Below are the basic variables
which can be utilized.
You can also include these placeholders in the ‘Subject’ line of the E-mail template as shown
above.
Page 19 of 47
4.2.4 WORKFLOW CONFIGURATION
In general, to enable notifications on workflows, you will simple need to associate a template you
created to the workflow and then enable notifications on specific types of events within the
workflow. These actions coupled with enabling notifications via email on the given user’s profile,
will allow the user to receive notifications from the workflow.
To associate an email template to the workflow, simply click on Basic Settings and then select the
email template from the list of templates as shown below.
Notifications may occur throughout different steps in the workflow. To configure notifications for
a specific step, you simply need to click on the step to assign focus to the step and then configure
notifications as shown below.
Page 20 of 47
When configuring Notifications, you must configure the Notification Text and the Recipient which
is who you want to receive the notification. When configuring the Notification Text, you have the
ability to click on the Insert Placeholder button to insert variables which represent information
about the specific transaction into the notification.
With an Approval, there will be at least one step in the approval. It is on this step that you can
interrogate the workflow to provide details about the transaction in the notification email that goes
to the approver requesting their approval. Each step will have two sections within Basic Settings;
Work item subject and Work item instructions. Anything that is specified in Work item subject
will be injected into the Email Notification Template through the %subject% variable. Anything that
is specified in the Work item instructions section will be injected into the Email Notification
Template through the %message% variable. The examples below show the configuration of the
workflow and the result which will appear in the notification email.
Work item subject
%Ledger journal table.JournalName% %Ledger journal table.JournalNum% Awaiting Approval
Page 21 of 47
Work item instructions
Please approve %Ledger journal table.JournalName% %Ledger journal table.JournalNum%
submitted by %Workflow.Workflow originator%. Below are the details of this transaction.
Budget check results: %Ledger journal table.Budget check results%
Journal Line Description: %Ledger journal table.Journal lines.Txt%
Main Account: %Ledger journal table.Journal lines.OffsetLedgerDimension.MainAccount%
OL1: %Ledger journal table.Journal lines.OffsetLedgerDimension.OL1%
Department: %Ledger journal table.Journal lines.OffsetLedgerDimension.Department%
Division: %Ledger journal table.Journal lines.OffsetLedgerDimension.Division%
Fund: %Ledger journal table.Journal lines.OffsetLedgerDimension.Fund%
Function: %Ledger journal table.Journal lines.OffsetLedgerDimension.Function%
Subdivision: %Ledger journal table.Journal lines.OffsetLedgerDimension.Subdivision%
Program: %Ledger journal table.Journal lines.OffsetLedgerDimension.Program%
Project: %Ledger journal table.Journal lines.OffsetLedgerDimension.Project%
Note from Submitter: %Workflow.Last note%
%Workflow.Link to approve with comment%
%Workflow.Link to reject with comment%
Page 22 of 47
If you wish to allow the Approver to approve the transactions using a link in the notification email,
you must also add two special variables which are:
%Workflow.Link to approve with comment%
%Workflow.Link to reject with comment%
These items result in the Approve and Reject links appearing in the notification email. These links
utilize the
Notice that none of these options for sending notifications refer to the crucial step of letting you
know that a purchase requisition has been assigned to you for approval. That notification occurs
automatically.
Page 23 of 47
5.1 INTEGRATION ARCHITECTURE AND DESIGN
The previous section reflects the configuration of the application within Dynamics in order to have
a workflow transmit an email notification out of Dynamics. This section of the document sets forth
the design which picks up the email notification from Dynamics, transmits it to the approver, and
then provides the integration necessary to allow the approver to either approve or reject the
transaction from their email.
As shown in the figure above, the APPROVER will receive an email similar to the email below which
has an APPROVE or REJECT link in the email. These will be clickable links. The following shows an
example of the URL for each link.
Page 24 of 47
APPROVE
https:// axwfapproval.servicebus.windows.net/Email/applyURLActionWithComment?action=A
pprove&workflowDocumentId={85DA0519-9898-4B4F-8844-
4FADA1D2E498}&userId=b82accba2 a932760e e93c1c6174b1b1cd0558cd
045d3&url=https%3a%2f%2f axwfapproval.servicebus.windows.net%2fEmail%2fapplyURLActi
on&actionLabel=Approve&commentLabel=Comment&cancelLabel=Cancel&RTL=false
REJECT
https:// axwfapproval.servicebus.windows.net/Email/applyURLActionWithComment?action=Re
ject&workflowDocumentId={85DA0519-9898-4B4F-8844-
4FADA1D2E498}&userId=b82 a932760ed32 93c1c6174b1b1cd0558cd
045d3&url=https%3a%2f%2f axwfapproval.servicebus.windows.net%2fEmail%2fapplyURLActi
on&actionLabel=Reject&commentLabel=Comment&cancelLabel=Cancel&RTL=false
Both of these URLs point to https:// axwfapproval.servicebus.windows.net. This is a Microsoft
Azure Service Bus. The Microsoft Azure Service Bus is a web service which is designed to provide a
mechanism to integrate applications utilizing a messaging architecture. For a comprehensive
description of the Azure Service Bus, please see https://docs.microsoft.com/en-us/azure/service-
bus-messaging/service-bus-fundamentals-hybrid-solutions. Azure will then communicate back to
the Dynamics application running in the internal network via an Inbound Port configured using the
Services and Application Integration Framework. This communication is brokered by the Dynamics
AX Connector for Mobile Applications which is a software/service running on an internal server.
Please see https://www.microsoft.com/en-us/download/details.aspx?id=36776 for additional
details on this application. The following sections outline the steps which are necessary to configure
this integration framework.
5.1.1 CONFIGURE THE MICROSOFT AZURE SERVICE BUS
This section outlines the steps necessary to setup an Azure account and to configure the Azure
Service Bus namespace.
1. Register for Azure Account and Subscription
If you already have an active Azure account and subscription, this stepped can be skipped.
You can sign up for a free Azure account with a 90-day subscription but eventually you will
need to convert to a paid model.
2. Submit Support Request to Microsoft to Have Subscription Whitelisted
The Dynamics AX Connector for Mobile Applications requires an Azure Service Bus
Namespace and a companion Access Control Service(ACS) Namespace. Azure currently
supports ACS as an authentication mechanism for service bus applications. Microsoft will
eventually transition away from this architecture supporting Access and Identity
Management toward the use of Azure Active Directory. This will require a change to the
Connector. There is no documented timeframe as to when this will be occurring.
Additional details on this change can be found at:
Page 25 of 47
https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-acs-
migration
Long story short, you will need to contact Microsoft to have them whitelist your Azure
subscription which will then allow you to create the required Service Bus Namespace and
companion ACS namespace.
3. Install Azure PowerShell Cmdlets
Creation of the Service Bus and ACS namespaces must be done through PowerShell. In
order to access/manage Azure through PowerShell, you will need to install the Azure
PowerShell Cmdlets from https://azure.microsoft.com/en-us/downloads/.
4. Connect to Azure Account
In Windows PowerShell, run the Add-AzureAccount command, and provide the user name
and password for the Azure account created in Step 1.
5. Create Azure Namespace and Companion ACS Namespace
PS C:\> New-AzureSBNamespace -name AXWFApproval -location 'East US' -
CreateACSNamespace $true -NamespaceType Messaging
Upon successful completion, you will see a screen similar to the following:
6. Login to Azure Portal and Verify Existence of Service Bus Namespace
After creating the namespace, you can login through the Azure Portal at
https://portal.azure.com or https://portal.azure.us for the Government Portal and view the
new namespace. You should see something similar to the following:
Page 26 of 47
You can then click on the Service Bus and then click on Properties to verify provisioning
was successful.
Page 27 of 47
7. Login to ACS Management Portal to Verify Creation of ACS Service
When the namespaces were created in Step 5, the link to the ACS endpoint was shown as
follows:
You can login to this site to verify the ACS endpoint. You should see a screen similar to the
following.
5.1.2 SETUP INBOUND PORT FOR EMAIL APPROVAL SERVICE
This step will be completed on the on-premise Dynamics AX environment. The result of this step
will be AIF Inbound Port that will listen for incoming communication from the Dynamics AX
Connector for Mobile Applications which is configured in the following step.
1. In Microsoft Dynamics AX, click on System Administration > Services and Application
integration framework > Inbound ports.
Page 28 of 47
2. Click New, and enter a name and description.
3. Under Service contract customizations, click Service operations. The WSDL URI is
populated.
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.
Page 29 of 47
You should see a green checkmark beside the service. You will also see the WSDL URI
which will be utilized later in the configuration of the Dynamics AX Connector for Mobile
Appliations.
Page 30 of 47
5.1.3 INSTALL AND CONFIGURE DYNAMICS AX CONNECTOR FOR MOBILE APPLICATIONS
This step will focus on installing the Connector which runs on an on-premise server. It can run on
any server including but not limited to one of the Dynamics AOS’s. This application will run as a
Windows Service and will connect to the Azure Service Bus created in a previous step. It will
initiate and maintain a connection to the Azure Service Bus. When the Azure Service Bus receives
a message when an Approver clicks on a link in the email, Azure will then forward the
authenticated message into the Connector. The Connector will then communicate with Dynamics
through the AIF port configured in the previous step.
1. Download the Connector
The Connector can be downloaded from Customer Source at:
https://mbs.microsoft.com/customersource/northamerica/AX/news-
events/news/MSDYN_MobileAppsAX
2. Provision Service Account in Dynamics
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. This account can be a local machine account or a domain
account.
Make sure that this new service account user has a record in Microsoft Dynamics AX
and has been given System administrator privileges.
3. Install Connector
Double click on AXConnectorForMobileApplications.msi to start the installation. The
following window will appear. Click on Next to continue.
Page 31 of 47
Accept the license terms and click on Next to continue.
Accept the default for the destination folder and click on Next to continue.
Enter the service account information as follows.
Page 32 of 47
Click on Install to complete the installation.
After the installation is complete, it will be necessary to start the Connector service. Go to
Start > Administrative Tools > Service to open the Windows Services list. 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.
4. Configure Connector
Once the installation is complete you the Connector service has been started, you should
have a new item under Apps for the Microsoft Dynamics AX Connector for Mobile
Applications as follows.
Page 33 of 47
Click on this item to open the Connector to complete the configuration. You will see a
window similar to the following.
To complete the configuration, you will click on the parameter in the list, enter the
appropriate value for the parameter and then click on Save. The following parameters are
the ones that are required to support email approvals.
Page 34 of 47
Azure service namespace – This is the name of the namespace which was configured in a
previous step. This can be found in the Azure portal as follows.
Azure service identity name – By default, this will be “owner” unless it has been modified.
You can find this information in the ACS Management Portal as set forth on Page 26. After
logging into the portal, you will see the following screen. Click on Service Identities.
There you will see the Service Identify for the service bus which will include the Name.
Page 35 of 47
Azure service identity password – This password provides the authentication for this
service. This password can be found by click on the Service Identify Name, “Owner” as
shown above. You will then see the following window.
The Symmetric Key and Password are essentially the same by default unless they are
changed. This will provide a 256-bit symmetric key that will be utilized to authenticate to
the service bus.
Page 36 of 47
Click on Password. The following window will appear. You can then click on the Show
Password button to display the password. You can then copy/paste this password into the
Azure service identify password value in the Connector.
Endpoint URI of EmailApprovalsService – This is the URI of the AIF Inbound Port which
was configured in Dynamics beginning on Page 26. 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. It is recommended that port 8201 be used instead so the URL
would be similar to the following:
net.tcp://DAXTST:8201/DynamicsAx/Services/RocoEmailApproval
Page 37 of 47
While not utilized for this specific configuration, the following parameters must not be
blank. I would recommend just putting an “x” in for their value. If these are blank, you will
get an error when you attempt to start the service.
Thumbprint of X509 certificate used to sign SAML token
ADFS URL
Support Email
After completing the configuration of each of these parameters, you should be ready to
start the Connector service. Click on Start to start the service. You should see a window
similar to the following showing a green “Started” along with the related URL’s for the
service below.
Make note of the https:// axwfapproval.servicebus.windows.net/Email/ URL. This will
be carried forward to the next step.
5.1.4 CONFIGURE SERVICE BUS NAMESPACE URL IN WORKFLOW PARAMETERS
This is the final step in the configuration. This step will configure the workflow parameters with the
URL from the previous step. The workflows will then pull this URL into the email templates for the
APPROVE and REJECT links as described on Page 23.
Page 38 of 47
To configure, go to System Administration > Setup > Workflow > Workflow parameters.
Paste the URL into the configuration as shown above and click on Close to complete the process.
Page 39 of 47
6.1 INFRASTRUCTURE DESIGN AND CONFIGURATION
This section of the Solution Design identifies the design and configuration of the infrastructure
components necessary to support the solution design as set forth below.
Component Description
Dynamics AX 2012 R3 This represents a functional Dynamics AX 2012 R3
platform. At a minimum, this will include one or more
AOS’s as well as the database. These services may be
running on one or more physical or virtual servers.
The AX-PROD environment consists of the following
virtual machines:
Dynamics Connector for Mobile
Applications
This is a Windows Service that will be installed and
configured to run on one of the existing AX
Page 40 of 47
Component Description
application servers. This application will be installed
on:
DAXTST – For Test Purposes
– For Production Operation. It makes sense
to install on this AOS since this AOS is responsible for
batch and workflow processing.
SMTP Mail Relay This role will be handled by an internal SMTP relay.
smtp.roanokecountyva.gov
This SMTP relay has been configured to accept and
relay messages from the following hosts:
Groupwise This represents the internal Groupwise Email system.
No additional configuration is necessary on this
system.
Azure This represents the Microsoft Azure environment. This
is a cloud-based service hosted by Microsoft.
Firewall The firewall shown in the above diagram represents
the security perimeter between the internal network
and the public Internet. No configuration changes are
required on the firewall to support this service.
Page 41 of 47
7.1 SECURITY DESIGN AND CONFIGURATION
This section of the Solution Design identifies design and configuration items that relate to the
security of this solution. While the implementation of this solution does not require any specific
changes to security or implementation of additional authentication or authorization mechanisms,
the solution does present a few minor exposures that must be addressed along with the
mechanisms that will be implemented to address these exposures.
7.1.1 AUTHENTICATION
As shown in the following diagram, the Dynamics Connector for Mobile Applications Windows
Service will communicate to the Azure Service Bus and establish a persistent connection.
This connection is authenticated via symmetric private keys. In order to establish this connection,
it uses three parameters which were entered when the Connector was configured as follows:
Azure service namespace Provide the “address” of the web service or Azure Service
Bus.
Azure service identify name The Connector uses this parameter as one of the two
components necessary to authenticate to the Azure
Page 42 of 47
Service Bus. The identity name essentially functions as a
“public key”.
Azure service identity password The Connector uses this parameter as the other
component of the credentials to authenticate to the Azure
Service Bus. The service identity password essentially
functions as the “private key”.
The initial communication from the Connector to Azure occurs over an HTTPS connection so the
information above is passed through an encrypted tunnel. Once the connection is authenticated,
the Connector then establishes a persistent connection between the Connector and Azure over two
random TCP ports. This can be seen by interrogating the connections to the server which the
Connector is running on. Below is an example.
TCP 192.168.XX.XX:52717 52.168.133.227:9351 ESTABLISHED
[Microsoft.Dynamics.Framework.RapidStart.Connector.exe]
TCP 192.168.XX.XX:52722 52.168.133.227:9351 ESTABLISHED
[Microsoft.Dynamics.Framework.RapidStart.Connector.exe]
This essentially creates a “tunnel” between the Connector and Azure for secure communication of
messages.
7.1.2 AUTHORIZATION
The user will receive an email with links to APPROVE or REJECT the transaction. When they click on
either of these links, their client will launch their default web browser initiating a connection to the
Azure Service Bus through an encrypted HTTS connection through the Internet. The call to the
Service Bus via the action URL from the email message is not authenticated. However, the action
URL does contain a considerably long secret GUID as shown below that is required for the APPROVE
or REJECT action.
https://r axwfapproval.servicebus.windows.net/Email/applyURLActionWithComment?action=A
pprove&workflowDocumentId={85DA0519-9898-4B4F-8844-
4FADA1D2E498}&userId=
&url=https%3a%2f%2f axwfapproval.servicebus.windows.net%2fEmail%2fapplyURLActi
on&actionLabel=Approve&commentLabel=Comment&cancelLabel=Cancel&RTL=false
The Connector also applies throttling if it detects repeated failed attempts. The Application
Integration Framework (AIF) service is protected by requiring that a value GUID (which is embedded
in the action URL) be presented. If the GUID is not valid, no action is taken.
7.1.3 RISKS AND EXPOSURES
While overall, the solution provides a secure architecture for the approval of transactions, there is
an exposure in that the action URL that is included in the email message is not authenticated to the
Page 43 of 47
intended user. The original email will be delivered to the intended user based upon the email
address that is on their Options in their user profile. However, 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. This risk is mitigated by the
fact that a user must authenticate to the email system in order to receive the email.
5. SOLUTION IMPACT ASSESSMENT
This section of the document is intended to define the impact of this project on the overall
technology footprint, Finance processes or procedures, or processes and procedures.
ITEM IMPACT SUMMARY
ROLES AND RESPONSIBILITIES LOW This solution will require no additional roles
or responsibilities nor any changes in
existing roles or responsibilities.
USER SUPPORT MEDIUM This solution will extend additional
functionality to the user by providing the
ability to complete approvals via email. As a
result, additional support issues may occur
and be required to be addressed as a result
of the implementation of this solution.
DISASTER RESILIENCE LOW This solution will take advance of the
existing DR capabilities which are already in
place and will not require any additional
capabilities.
INITIAL SOFTWARE COST LOW There is no additional software cost for this
solution.
RECURRING SOFTWARE COST LOW There is no recurring software cost for this
solution.
RECURRING SERVICE COST LOW Based on testing of this solution, this
solution will require an Azure subscription.
The solution will incure a minimal monthly
cost for the messages which flow through
the Azure service bus.
INFRASTRUCTURE COST LOW There is no additional infrastructure cost
related to this solution.
APPLICATION AND INFORMATION SECURITY LOW Please see Section 7.1 for a full explanation
of the overall security risks and mitigations.
PERMITER SECURITY ATTACK SURFACE LOW No additional inbound ports on the
perimeter firewall are required.
NETWORK BANDWIDTH AND PERFORMANCE LOW This solution will result in minimal impact to
network bandwidth usage.
CLIENT ACCESS LOW This solution will not impact client access.
INFORMATION RETENTION AND RECORDS
MANAGEMENT
LOW This solution will not impact information
retention and records management.
PROCESS LOW This solution will not require any process
changes.
Page 44 of 47
6. COST DETAILS
This section if the document defines any capital or recurring operations costs related to the
implementation of this solution.
7. CONSTRAINTS, RISKS, AND ISSUES
This section of the document is intended to capture any constraints, risks or issues that are
identified during the Analysis and Design Phase.
ITEM DESCRIPTION RISK
1. Use of Azure ACS Namespaces Support for the use of the Azure ACS
namespaces will be discontinued as of
November 2018. At the current time, the
Connector requires the use of an ACS
namespace. Microsoft will need to release
a version of the Connector that will support
another authentication method prior to this
date.
MEDIUM
2.
3.
4.
5.
8. DEPLOYMENT AND IMPLEMENTATION PLAN
This section of the document is intended to provide a deployment and implementation plan for
this project. This is not intended to be a comprehensive project plan. If this level of detail is
required, a separate project plan will be developed outside of this document.
TASK ECD ASSIGNED STATUS
APPLICATION CONFIGURATION
1. Configure Email and Notification Options for Users
2. Complete Email Processing Configuration in AX
3. Complete Configuration of Email Templates
4. Complete Workflow Configuration to Support Email
Notification and Approvals
INTEGRATION CONFIGURATION
5. Provision Production Azure Account and Subscription
6. Complete Azure Service Request to have Subscription
Whitelisted for Implementation of ACS Namespace
7. Complete Configuration of Azure Service Bus
8. Configure Inbound AIF Port to Support Email
Approval in AX
Page 45 of 47
TASK ECD ASSIGNED STATUS
9. Install and Configure Dynamics AX Connector for
Mobile Applications
10. Configure Service Bus Namespace URL in Workflow
Parameters
TESTING
11. Test ability to successfully send email notifications
from workflow to validate email processing
configuration
12. Test ability to successfully APPROVE or REJECT a
document utilizing link in Email
Page 46 of 47
9. REFERENCE
About setting up alert email templates [AX 2012]
https://technet.microsoft.com/en-us/library/aa834423.aspx
Overview of Azure Service Bus
https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-fundamentals-
hybrid-solutions
Microsoft Dynamics AX 2012 White Paper: Configure the Microsoft Dynamics AX environment for
companion apps
https://www.microsoft.com/en-us/download/details.aspx?id=36776
Microsoft Dynamics AX Connector for Mobile Applications Download
https://mbs.microsoft.com/customersource/northamerica/AX/news-
events/news/MSDYN_MobileAppsAX
Azure Portal
https://portal.azure.com
Azure Government Portal
https://portal.azure.us
Azure PowerShell Cmdlets
https://azure.microsoft.com/en-us/downloads/.
Page 47 of 47
10. CHANGE LOG
DATE CHANGE SECTION/
PAGE
CHANGED BY
