Configure the Microsoft Dynamics AX Environment for Companion Apps

Microsoft Dynamics

®

AX 2012

Configure the Microsoft

Dynamics AX environment for companion apps

White Paper

January 2014

www.microsoft.com/dynamics/ax

Send suggestions and comments about this document to [email protected]. Please include the title with your

feedback.

http://www.microsoft.com/dynamics/ax

mailto:[email protected]

2 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS

Table of Contents

Introduction ................................................................................................ 4

Prerequisites ............................................................................................... 5

Create a new Windows Azure Service Bus namespace ................................ 6

Configure an Active Directory Federation Service for authentication .......... 9 Enable the endpoint .............................................................................................................. 9 Add/Configure the token signing certificate .............................................................................10

Ensure that the token signing certificate is linked to a trusted root in the Federation Service and is

issued by an enterprise certification authority....................................................................... 11 Obtain the thumbprint of the X.509 token signing certificate (digital signature) ........................ 11

Verify claim descriptions .......................................................................................................14 Add the trust relationship and claim rule .................................................................................15 Save the AD FS FederationMetadata.xml file ...........................................................................22

Configuring the Access Control Service ..................................................... 23 Add and configure the identity provider ..................................................................................24 Configure the relying party applications ..................................................................................26 Configure rule groups ...........................................................................................................27

Add a claim rule for the identity provider ............................................................................. 28

Update the relying party federation metadata .......................................... 30

Configuring the on-premises server for Companion apps .......................... 31 Install the required hotfixes for Microsoft Dynamics AX 2012 R2 ................................................31 Install Microsoft Dynamics AX Connector for Mobile Applications ................................................31

To install the Microsoft Dynamics AX Connector for Mobile Applications ................................... 32

Configuring the Windows 8 or mobile phone applications ......................... 38

Appendix 1: Configuring the Approvals app .............................................. 39 Viewing recent approval items ...............................................................................................39 Configuring the Approvals app ...............................................................................................39 Configuring the tiles .............................................................................................................41 Configuring the Overview tab ................................................................................................42 Adding reports .....................................................................................................................42 Using Microsoft Lync integration ............................................................................................43

Appendix 2: Windows Phone 8 .................................................................. 44

Appendix 3: Microsoft Dynamics Business Analyzer .................................. 45 Install and Configure Business Analyzer ..................................................................................46 Optional: Configure Management Reporter ..............................................................................47

Add a trust relationship and claim rule for Business Analyzer with Management Reporter .......... 47 Configure settings and update the database schema for Management Reporter ........................ 51 Install required Management Reporter hotfixes ..................................................................... 53

3

CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS


Introduction

This paper describes how to configure an environment that is running Microsoft Dynamics AX 2012, so that users can use the Microsoft Dynamics AX companion apps. For a list of the companion apps that are available, see http://go.microsoft.com/fwlink/?LinkId=335790.

In order for the companion apps to interact with Microsoft Dynamics AX 2012, you must configure the following components:

Active Directory Federation Services (AD FS) – AD FS works with an organization’s instance of Active Directory Domain Services to authenticate users of the mobile phone

application. Users are authenticated based on credentials that are sent by the mobile phone application. Upon successful authentication, AD FS returns a token to the mobile phone

application.

Companion app – The companion app allows a user to capture a transaction. It then authenticates the user and sends the message.

Windows Azure Active Directory Access Control (also known as Access Control

Service or ACS) – A Windows Azure Service Bus, which is an ACS managed namespace, enables the companion app to send a message to Microsoft Dynamics AX (which resides on-premises). ACS provides the authentication that is necessary to send a message via the Service Bus service.

Microsoft Dynamics AX Connector for Mobile Applications – The connector listens for messages sent via the Service Bus, authenticates the sender of the message, and then sends the message to the Microsoft Dynamics AX 2012 instance.

Microsoft Dynamics AX 2012 – The Microsoft Dynamics AX 2012 instance receives messages originally sent from the companion application. It stores the messages as

transactions that are available to the user (for example, the user will see expense transactions that are captured via the user’s mobile phone in the Dynamics AX system).

For information about configuring specific companion apps, refer to the appendix of this white paper.

http://go.microsoft.com/fwlink/?LinkId=335790

5


The following diagram shows these components and the flows among them.

Figure 1: Required Microsoft components and configurations for Microsoft Dynamics AX mobile apps

Prerequisites

Before you can configure the Microsoft Dynamics AX environment for companion apps, you must complete the following prerequisites:

Set up and configure the Active Directory server:

The Active Directory server and domain controller should have been set up during the installation and configuration of Microsoft Dynamics AX 2012.

Install Active Directory Federation Services. You can download the Active Directory Federation Services 2.0 RTW from http://www.microsoft.com/en-us/download/details.aspx?id=10909.

Configure Microsoft Dynamics AX 2012:

Configure users for Microsoft Dynamics AX 2012.

Configure Expense management.

Configure Time management.

Configure Human resources.

Configure a Windows Azure account. For more information, see

http://www.windowsazure.com.

http://www.microsoft.com/en-us/download/details.aspx?id=10909

http://www.windowsazure.com/


Create a new Windows Azure Service Bus namespace

After you have set up a Windows Azure account, open the 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.

Figure 2: Service Bus page on the Windows Azure dashboard

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

Figure 3: Create new Service Bus page

https://windows.azure.com/default.aspx

http://msdn.microsoft.com/en-us/library/windowsazure/ee732537.aspx

http://msdn.microsoft.com/en-us/library/windowsazure/ee732537.aspx

https://manage.windowsazure.com/#Workspace/All/dashboard

7


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

Figure 4: Add new namespace dialog box

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. Then click Connection Information on the Action Pane to view the default issuer and default key.

Figure 5: Default issues and default Access key


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

Figure 6: Access key dialog box

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

The next step is to set up the Active Directory server as the identity provider that the Service Bus and its Access Control Service require for Federated Authentication.

9


Configure an Active Directory Federation Service for authentication

After the federation server and AD FS 2.0 are installed, as specified in the Prerequisites section, use the AD FS 2.0 Management tool to configure the service.

For guidance about Active Directory federation servers, how to configure certificates, and how to install the AD FS 2.0 software by using the setup wizard and server management, see http://technet.microsoft.com/en-us/library/dd807089(v=ws.10).aspx.

Next, run the AD FS 2.0 Federation Server Configuration Wizard to configure a new federation server and a new Federation Service. For more guidance, see http://technet.microsoft.com/en-

us/library/adfs2-help-how-to-configure-a-new-federation-server(v=ws.10).aspx.

The configuration described here is for a Federation Service role for a stand-alone federation server.

1. Enable the endpoint for Windows Authentication.

2. Establish a trust relationship between the Federation Service and the relying party (the Access Control Service of the Windows Azure Service Bus—for example, contosomobile-sb).

3. Create rules to pass claims through the Federation Service.

4. Obtain the X.509 token signing certificate’s thumbprint that is required when you configure the Microsoft Dynamics AX Connector for Mobile Applications service.

Enable the endpoint

1. Click Start > Administrative Tools > AD FS 2.0 Management to open the AD FS 2.0

Management tool.

2. In the left navigation pane, expand the Service node, and then select Endpoints. In the list of endpoints in the Token Issuance section, find the endpoint that has the URL

/adfs/services/trust/13/usernamemixed. Select this endpoint, right-click, and enable the endpoint.

After you enable the service endpoint, the authentication server URL of this Federation Service will be in the form https://<FederationServiceName>/adfs/services/trust/13/usernamemixed.

Example: https://contosoadfs.com/adfs/services/trust/13/usernamemixed

3. Click Start > Administrative Tools > Service to open the Windows Services list. Restart the AD FS 2.0 Windows service.

http://technet.microsoft.com/en-us/library/dd807089(v=ws.10).aspx

http://technet.microsoft.com/en-us/library/adfs2-help-how-to-configure-a-new-federation-server(v=ws.10).aspx

http://technet.microsoft.com/en-us/library/adfs2-help-how-to-configure-a-new-federation-server(v=ws.10).aspx

http://technet.microsoft.com/en-us/library/ee913579(WS.10).aspx


4. In the Endpoints list, ensure that the three endpoints in the Metadata section are enabled, as shown in the following screen shot.

Figure 7: Windows Endpoints list

Add/Configure the token signing certificate

The Microsoft Dynamics AX Connector for Mobile Applications service requires the thumbprint of the X.509 token signing certificate used by the Federation Service.

Both the service communications and token signing certificates are configured when you run the AD

FS 2.0 setup wizard. For more about certificate requirements for federation servers, see http://technet.microsoft.com/en-us/library/dd807040(v=ws.10).aspx.

You can view the certificates by clicking Certificates under the Services node in the left navigation pane. You can also add new token certificates from this management tool by right-clicking the Certificates node.

http://technet.microsoft.com/en-us/library/dd807040(v=ws.10).aspx

11


Before you can add any new certificates, you may have to disable the automatic certificate rollover feature by using Windows PowerShell commands.

Figure 8: AD FS 2.0 Management Certificate Alert

Ensure that the token signing certificate is linked to a trusted root in the

Federation Service and is issued by an enterprise certification authority

For more information about token signing certificates, see http://technet.microsoft.com/en-

us/library/dd807039(v=WS.10).aspx.

Set the newly added token signing certificate as the primary certificate.

Obtain the thumbprint of the X.509 token signing certificate (digital signature)

1. Select the token signing certificate in the Certificates list. Right-click, and then select View Certificate.

Figure 9: Certificates list

http://technet.microsoft.com/en-us/library/dd807039(v=WS.10).aspx

http://technet.microsoft.com/en-us/library/dd807039(v=WS.10).aspx


2. On the Details tab of the Certificate form, copy the Thumbprint value, as shown in the following screen shot, and save it without the spaces between pairs of characters. This thumbprint value is used when you configure the connector parameters in the Microsoft Dynamics AX Connector for Mobile Applications service.

Figure 10: Certificate dialog box

3. Export this token signing certificate, and save it to a location.

This certificate must be installed in the Trusted Root Certification Authorities store on the server machine that hosts the Microsoft Dynamics AX Connector for Mobile Applications service.

Here are a few more points to keep in mind about these certificates:

Ensure that the Subject Name (CN) or Issued to property of the service communications certificate (SSL certificate) matches the Federation Service name.

To view or edit the Federation Service name, right-click Service in the left navigation pane, and then select Edit Federation Service Properties.

In our example, the service communications certificate has its Subject Name(CN)

property set to contosoadfs.com, which helps define the URL of the Federation Server endpoint—for example, https://contosoadfs.com/adfs/ls/.

13


You can validate that your service is set up correctly by opening the URL https://contosoadfs.com/adfs/fs/federationserverservice.asmx in a browser.

Figure 11: Federation Service Properties dialog box

For additional debugging and troubleshooting, go to the Events tab in the Federation Services Properties form, and turn on logging for error and other events. This can help you debug any

issues by looking at the logged events in Windows Event Viewer.


Verify claim descriptions

Ensure that the claim named Windows account name exists, and that the Published property is set to Yes. This is configured by default when AD FS 2.0 is installed.

Note: If you are using the Microsoft Dynamics Business Analyzer app along with Management Reporter, you must setup a new Relying Party Trust that is specific to Management Reporter but will utilize the same Azure Service Bus configuration. You also must make note of the URL for the UPN Claim Type as you’ll need this when you configure the MRServiceHost.settings.config file. For more information, see 8. Optional: Configure Management Reporter.

Figure 12: Claim descriptions list

15


Add the trust relationship and claim rule

Active Directory Domain Services is the claim provider trust for issuing claims about an authenticated user.

Figure 13: Claims Provider Trusts

The relying party is the Windows Azure Access Control Service associated with the Service Bus that was set up in the Creating a new Windows Azure Service Bus namespace section.

1. In the left navigation pane, expand Trust Relationships, right-click Relying Party Trusts, and then select Add Relying Party Trust.

This will open the Add Relying Party Trust Wizard that you need to follow to add your Windows Azure Service Bus namespace as a relying party to the AD FS configuration database.

2. Click Start.

Figure 14: Add Relying Party Trust Wizard Welcome page


3. On the Select Data Source page, select one of the options to add data about your relying party.

If you select the first option, Import data about the relying party published online or on a local network, enter the federation metadata address in the text box in the following format:

https://<AzureNamespace>-sb.accesscontrol.windows.net/FederationMetadata/2007-06/FederationMetadata.xml

In our example, this address is https://contosomobile-sb.accesscontrol.windows.net/FederationMetadata/2007-06/FederationMetadata.xml, as shown in the following screen shot.

Figure 15: Add Relying Party Trust Wizard Select Data Source page

To use the second option, Import data about the relying party from a file, because your AD FS server does not have Internet access, you need to do the following:

1. In a browser, open the address https://contosomobile-sb.accesscontrol.windows.net/FederationMetadata/2007-06/FederationMetadata.xml, for example, and save the FederationMetadata.xml file to a location.

2. Select the second option, Import data about the relying party from a file, click Browse, and load the saved FederationMetadata.xml file.

4. Click Next.

17


5. On the Specify Display Name page, enter a display name or leave the default value, and then click Next.

Figure 16: Add Relying Party Trust Wizard Specify Display Name page


6. On the Choose Issuance Authorization Rules page, ensure that the Permit all users to access this relying party option is selected, and then click Next.

Figure 17: Add Relying Party Trust Wizard Choose Insurance Authorization Rules page

19


7. On the Ready to Add Trust page, click Next, and then finish the setup by clicking Close. The Open the Edit Claim Rules dialog for this relying party trust when the wizard closes option is selected by default. When the wizard closes, the Edit Claim Rules form will open.

Figure 18: Edit Claim Rules page

8. Click Add Rule. You will be guided through the Add Transform Claim Rule Wizard.


9. On the Select Rule Template page, in the Claim rule template field, select Pass Through or Filter an Incoming Claim, as shown in the following screen shot, and then click Next.

Figure 19: Select Rule Template page

10. On the Configure Rule page, enter a name for the claim rule.

11. In the Incoming claim type field, select Windows account name.

21


12. Select the Pass through all claim values option, as shown in the following screen shot, and then click Next.

Figure 20: Configure Rule page

13. In the Edit Claim Rules form, you can see the newly created claim rule. Click Apply and then OK to save your changes.

Figure 21: Edit Claim Rules form


You can get back to the Edit Claim Rules form by right-clicking the relying party trust that you just added and then selecting Edit Claim Rules.

Save the AD FS FederationMetadata.xml file

1. On your federation server, open the following address in a browser: https://<FederationServiceName>/FederationMetadata/2007-06/FederationMetadata.xml

In our example, this address is https://contosoadfs.com/FederationMetadata/2007-06/FederationMetadata.xml.

2. Save the FederationMetadata.xml file to a location.

3. You will need to upload this federation metadata file (if the Federation Service does not have an Internet-facing IP address), or you can use this address directly when you add the WS-Federation Identity Provider while configuring the Windows Azure ACS as described in the Add and configure

the identity provider section.

This completes the required Active Directory Federation Service configuration.

23


Configuring the Access Control Service

The Service Bus uses the Access Control Service to implement Federated Authentication. A buddy namespace, contosomobile-sb, is created for the ACS when the Service Bus is created. Use the following steps to configure the ACS and its relying party–related parameters, the identity provider, and rule groups.

Select the namespace that you want to configure, and then click Access key on the Action

Pane. In the form that opens, click the Open ACS Management Portal link.

Figure 22: Access Key dialog box

The Access Control Service page will open.

Figure 23: Windows Azure Access Control Service page


Add and configure the identity provider

Use the following procedure to add the WS-Federation identity provider. The identity provider is the Federation Service that was configured in the Configuring an Active Directory Federation Service for authentication section.

Figure 24: Windows Azure Identify Provider page

1. Verify that the WS-Federation identity provider (e.g. Microsoft AD FS 2.0) option is selected, and then click Next.

2. On the Edit WS-Federation Identity Provider page, enter a display name for the identity provider, such as Contoso ADFS.

3. Under WS-Federation metadata, enter the federation metadata URL or the file that is available

from your configured AD FS server, as described in the Configuring an Active Directory Federation Service for authentication section.

25


Figure 25: Identity Provider Settings page

4. In the Used By section, under Relying party applications, ensure that the Service Bus check box is selected.

Figure 26: Used By section of the Identity Provider Settings page


Configure the relying party applications

Because the Service Bus uses this ACS for Federated Authentication, the Service Bus is added as a relying party application.

Figure 27: Windows Azure Relying Party Applications page

1. Click the ServiceBus link, and then, in the Relying Party Application Settings section, verify that the settings for the Realm and Token format fields are as shown as in the following screen shot.

Figure 28: Windows Azure Relying Party Application Settings page

2. In the Authentication Settings section, select the identity provider to use with the relying party. The identity provider was created in the previous section, Add and configure the identity provider.

27


3. Select the Default Rule Group for ServiceBus check box to use the default rule group, as described in the Configure rule groups section.

Figure 29: Windows Azure Authentication Settings page

Configure rule groups

1. In the left navigation pane, click Rule Groups.

2. Select the Default Rule Group for ServiceBus check box to configure the default rule group.

Figure 30: Windows Azure Rule Groups page

3. You will be able to view the predefined rules that have Access Control Service as the claim

issuer value. Click each rule to view the values. These rules have owner as the Input claim value, and Listen, Manage, or Send as the Output claim value.


4. Delete the rules that have Output claim values of Manage and Send.

Figure 31: Windows Azure Edit Rule Group page

Add a claim rule for the identity provider

1. After deleting the Manage and Send rules, click Add to add a new claim rule for the identity provider.

2. Select the identity provider that was configured in the Add and configure the identity provider section. In our example, this identity provider is Contoso ADFS.

3. Under Input claim type, select the Select type option, and then select the following URI: http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname

4. Under Input claim value, leave the fields as-is.

5. Under Output claim type, select the Enter type option, and then enter the value net.windows.servicebus.action.

6. Under Output claim value, select the Enter value option, and then enter Send.

29


7. Optionally, add a description.

Figure 32: Windows Azure Edit Claim Rule page

This completes the required Access Control Service configuration.


Update the relying party federation metadata

1. On the Federation Service server, open the AD FS 2.0 Management tool.

2. In the left navigation pane, expand Trust Relationships, and then select Relying Party Trusts.

3. Right-click the relying party that was added in the Add the trust relationship and claim rule section, and then select Update from Federation Metadata.

4. Click Update.

Figure 33: Relying Party Trusts page

31


Configuring the on-premises server for Companion apps

Install the required hotfixes for Microsoft Dynamics AX 2012 R2

To use of Windows 8 or phone applications, the following hotfixes are required:

If you are using the Windows 8 Expense app, the following hotfix, which must be installed

prior to installing the next hotfix) is required: KB2867017 http://go.microsoft.com/fwlink/?LinkID=322082

To enable the services that the Approvals, Expense, and Timesheet apps communicate with, you must install the following hotfix or have installed Cumulative Update 7 for Microsoft Dynamics AX 2012 R2: KB2877944 http://go.microsoft.com/fwlink/?LinkID=286321

To enable the services that the Business Analyzer app communicates with, you must install

the following hotfix: KB2892866 http://go.microsoft.com/fwlink/?LinkId=389273

Install Microsoft Dynamics AX Connector for Mobile Applications

Before you can install the Microsoft Dynamics AX Connector for Mobile Applications, you must ensure the following prerequisites are met:

The .Net Business Connector proxy account must be created.

o In a later step, the Dynamics AX Connector for Mobile Applications service should be deployed and run using this same account. For more information about how to create and set up the .Net Business Connector (BC) proxy account, see Specify the .NET Business Connector proxy account [AX 2012]

o If EP is deployed on the Server, it will be using the BC proxy account.

o Also it is very important that the .Net BC proxy user account is added as an

Administrator on the machine running the AX Connector service

o Also note the following guidance for the .Net BC proxy account

Must be a Windows domain account

Must be a dedicated account (used only by Business Connector)

Must have a password that does not expire

Must not have interactive logon rights

Must not be a Microsoft Dynamics AX user

o You can check which BC Proxy user account has been configured by going to AX> System Administration> System Service Accounts

For Microsoft Dynamics Business Analyzer, you must install Microsoft .NET Framework 4.5.

For Microsoft Dynamics Business Analyzer and if SQL Server Analysis Services is not

installed on the same machine as your Microsoft Dynamics AX AOS, you must install the ADOMDClient (v10) assembly on your AOS machine.

o X86: http://go.microsoft.com/fwlink/?LinkId=130651&clcid=0x409

o X64: http://go.microsoft.com/fwlink/?LinkId=130652&clcid=0x409

o IA64: http://go.microsoft.com/fwlink/?LinkId=130653&clcid=0x409

Note: You can only run one instance of the Microsoft Dynamics AX Connector for Mobile Applications on a machine.

http://go.microsoft.com/fwlink/?LinkID=322082&clcid=0x409

http://go.microsoft.com/fwlink/?LinkID=286321&clcid=0x409


http://technet.microsoft.com/en-us/library/aa496652.aspx

http://technet.microsoft.com/en-us/library/aa496652.aspx

http://go.microsoft.com/fwlink/?LinkId=130651&clcid=0x409




To install the Microsoft Dynamics AX Connector for Mobile Applications

1. Download and unzip the Microsoft Dynamics AX Connector for Mobile Applications Zip package.

https://mbs.microsoft.com/downloads/partner/AX/AXConnectorForMobileApplications.zip

2. Click Start > All Programs > Microsoft Dynamics AX Connector for Mobile Applications, and start the Microsoft Dynamics AX Connector for Mobile Applications Setup Wizard.

Figure 34: Microsoft Dynamics AX Connector for Mobile Applications Setup Wizard Welcome page

3. Select the I accept the terms in the License Agreement check box, and then click Next.

Figure 35: Microsoft Dynamics AX Connector for Mobile Applications Setup End-User License Agreement

https://mbs.microsoft.com/downloads/partner/AX/AXConnectorForMobileApplications.zip

33


4. On the Destination Folder page, accept the default folder location for the connector, or click Change to select another location. Then click Next.

Figure 36: Destination Folder page

5. On the Service account page, in the Account name and Password fields, enter the name and password for the BC Proxy user account that was previously created, and then click Next.

Figure 37: Service account page

6. Click Install.

7. Click Finish.

8. Click Start > Administrative Tools > Service to open the Windows Services list.


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

Figure 38: Services

35


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.

Thumbprint of X.509 certificate used to sign SAML token

Information about the thumbprint value can be found in the Add/Configure the token signing certificate section.

Endpoint URI of ExpenseServices (if using Expenses applications)

The following text is preconfigured in this field:

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

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.

Endpoint URI of TimesheetServices (if using Timesheets applications)


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



Endpoint URI of ApprovalsServices (if using the Approvals application)


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

Replace <AOS_MACHINE_NAME> with the name of the machine

that hosts AOS.


The Approvals app can be configured to support various types of approvals. For details, see Appendix 1: Configuring the Approvals app.

Endpoint URI of EmailApprovalsServices (if using Email approvals)


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

Replace <AOS_MACHINE_NAME> with the name of the machine that hosts AOS.


Endpoint URI of BusinessAnalyzerServiceGroup (if using Microsoft Dynamics Business Analyzer)

The following text is preconfigured in this field: net.tcp://<AOS_MACHINE_NAME>:8201DynamicsAx/Services/BusinessAnalyzerServiceGroup



ADFS URL An authentication server URL. This is the endpoint URL of the AD FS server that was set up in the Enable the endpoint section.

In our example, this URL is in the form https://contosoadfs.com/adfs/services/trust/13/usernamemixed

Support Email An email address the mobile user will see to contact in case of any issues. For example, [email protected]

https://contosoadfs.com/adfs/services/trust/13/usernamemixed


10. On the Start menu, click the Microsoft Dynamics AX Connector for Mobile Applications shortcut. The GUI for configuring the connector parameters will open.

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

12. Note that the Endpoint URI parameters for the following services are optional:

Expense

Timesheet

Approvals

Email Approvals

Business Analyzer

If you choose not to configure one of the services, leave that field blank, and then click Save. When the Microsoft Dynamics AX Connector for Mobile Applications service is started, you will notice that the URL for that service does not appear, and the phone applications will not display

the corresponding feature.

Note: Windows 8 applications will fail to connect to Microsoft Dynamics AX if the corresponding URI entry does not exist. For example, the Windows 8 Expenses app will fail to connect to Microsoft Dynamics AX if the Endpoint URI of ExpenseServices parameter is blank or not correct.

Figure 39: RapidStart Services parameters setting form

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

37


14. After the connector parameters are saved, click Start in the form. You can see that the status has changed to Started, and that the Mobile Application Connector service is now running and listening on the Service Bus.

Figure 40: RapidStart Services parameters setting form


Configuring the Windows 8 or mobile phone applications

When you notify users that the solution is available, they will have to provide their domain credentials and the service connection name to use any of the Microsoft Dynamics AX applications for Windows 8 or mobile phones.

When users open the application for the first time, they are directed to a sign in page with the following fields:

User name

Password

Service connection name. This is the name of the Service Bus namespace that was set up in the Creating a new Windows Azure Service Bus namespace section.

When the information is entered, the user presses sign in, the data is synced from the server, and

they can then begin using the application.

Note: The steps for configuring the Microsoft Dynamics Business Analyzer app are different. For steps

on how to configure Business Analyzer, see 9. Install and Configure Business Analyzer.

39


Appendix 1: Configuring the Approvals app

Viewing recent approval items

The Approvals app provides a way for users to view all the workflow approval items assigned to them, and to approve or reject them. After the workflow generates the approval, the approver will be able to

view the details, attachments, comments, and other information for that approval. For example, if an approver rejects a particular version of a timesheet, and that approval is later re-routed by workflow and assigned to a different employee, the timesheet document, including the subsequent changes, will still be visible to the original approver.

Configuring the Approvals app

The Approvals app provides a way for users to view all the workflow approval items assigned to them,

and to approve or reject them. To help users determine which action to take, basic information about the approval is shown on the tiles, and more detailed information is shown when one of the tiles is opened. Even more information about the approval item can be shown by using attachments. For approvals of timesheets and expenses, the app also includes extended context, such as the list of

expenses or time entries, receipts, and visual breakdowns of the impact of the expenditures on current project budgets. The following illustrations show each of these approaches.

Contextual information shown on tiles

Figure A1: Screen capture of the contextual information shown on tiles

Contextual information shown on the Overview tab

Figure A2: Screen capture of the contextual information shown on the Overview tab


Contextual information shown as an attachment

Figure A3: Screen capture of the contextual information shown as an attachment

Extended context for a timesheet (Time details, Time summary, and Project impact tabs)

Figure A4: Screen capture of a timesheet and other contextual information

41


Although the extended context for timesheets and expenses is built into the app and can’t be provided for other approval types, all the other contextual information, such as context on a tile, context on the Overview tab, and attachments, can be customized to meet the requirements of your organization by making configurations on the server. All customizations are performed in the following form, which is

accessible in the Microsoft Dynamics AX client under System Administration > Setup > Windows Store > Windows application store setup.

Figure A5: Screen capture Approvals page and Tile information tab

Configuring the tiles

Tiles can be rendered in two different formats, as specified by the Tile style field. When this field is

set to Value, unit, and description, three fields can be chosen and will be shown on the tile. This style communicates a quantity and unit, such as USD 233, on an expense report or timesheet, and then provide additional information, such as the summary Team Lunch. If your approval does not have a value overview, you can use the Title and description format, which has just two options.

Developers can extend the set of fields and values that is available for inclusion on tiles. The set of available fields is determined by the corresponding workflow template’s class. For example, the

following steps show how to add the quotation amount to the quotation approval, because this is likely

the value that you would want to show in the app:

1. In the Application Object Tree (AOT), click Workflows > Approvals > PSAQuotationApproval. Note the value of the Document property, which in this case is PSAProjQuotationDocument.

2. In the AOT, click Classes > PSAPRojQuotationDocument.

3. Add the following code to the class. This code will return the value of a display method that is already on the class and that contains the value that we want to show the user:

public AmountCur parmInvoiceAmount(

CompanyId _companyId,

tableId _tableId,


RecId _recId)

{

SalesQuotationTable t;

if(_tableId == tableNum(SalesQuotationTable))

{

t = SalesQuotationTable::findRec(_recId);

return t.invoiceAmount();

}

return 0;

}

4. Complete an Incremental CIL compilation.

5. Return to the Windows Store App configuration screen, and select Value as the new field to show

on the tile.

6. To customize the tile color, double-click the example tile, and then select the color from the color palette.

Configuring the Overview tab

The list of fields that shown on the Overview tab of a specific approval is determined by the fields that selected on the Overview fields tab of the Windows Store App configuration screen. By default, this list is populated with the fields that are typically shown in the Microsoft Dynamics AX client, which are determined by the field group specified on the workflow approval item in the AOT. To modify this list, click on the Overview tab and use the same process described earlier for customizing the information on the Tile information tab.

Adding reports

You can build reports to customize the information that an approver will receive in the Approval app, and then associate the reports with the workflow template. For example, a new report might show all the details of the quotation that is being approved. When an approval work item is generated, the report that displays the quotation information is rendered and included as an attachment in the email

message to the approver. The approver can then open and view the report. The following steps must be completed if you want to include a custom report:

1. Author a new report: The new report must use a query-based data source whose root is the same table as the workflow template’s document. Continuing the example with PSASalesQuotation from the previous sections, the new report must be based on a query whose root table is SalesQuotationTable. This enables the context of the quotation that is being approved to be passed to the report when it is executed.

2. Create a menu item: Create a new display menu item that references your new report. In order to associate the report with the workflow template, you must complete these steps:

1. Verify that the configuration key matches the configuration key of the workflow template.

2. Use the same prefix for the menu item and the report. The prefix refers to the first three letters of the element name in the AOT.

3. Pick the menu item: On the Report association tab of the Windows Store App configuration

screen, select the newly created menu item.

After you have completed these steps, the report will be rendered when an approver clicks view on the approval item in the attachments section of the application.

43


Using Microsoft Lync integration

If your organization uses Lync for communications and collaboration, the Approvals app can show pictures of submitters and indicate their availability. This will help the approver know whether they can contact a submitter by using Lync. If Lync is not available, pictures will be retrieved from Microsoft Dynamics AX, but no presence indicators will be included. Lync integration in the Approvals app utilizes the new UCWA protocol and therefore can be used only with on-premises deployments of Lync 2013 CU1. Additionally, the domain of your users will need to be added to the “Allowed List,” as described in this document: http://ucwa.lync.com/documentation/ITAdmin-Configuration.

http://ucwa.lync.com/documentation/ITAdmin-Configuration


Appendix 2: Windows Phone 8

The Dynamics AX app now supports populating the Service connection name field in the sign in page with a URI. This feature is only available on Windows Phone 8. This feature supports the following:

URL redirection. This is the primary recommendation for bootstrapping. For example, http://tinyurl.com/contosoSetup to ms-dynamics-

ax:setup?serviceConnectionName=namespace.

Emails that contain links that are to Gmail, Hotmail, or outlook.com email accounts, and then read from the same client.

Website links that you can navigate to by using your Windows Phone 8 device.

http://tinyurl.com/contosoSetup

45


Appendix 3: Microsoft Dynamics Business Analyzer

Microsoft Dynamics Business Analyzer provides a dashboard where you can view and interact with reports, charts, or KPIs for Microsoft Dynamics AX. Choose from a set of default charts and KPIs based on a specific role, or personalize the application with additional Management Reporter reports that are most important to you.

Before you can use the Windows 8 Business Analyzer app with AX 2012 R2, you must configure your

Microsoft Dynamics AX environment and the Business Analyzer app. The following diagram illustrates this process.

Configure the on-premises server for

companion appsOptional: Add a trust relationship and claim

rule for Business Analyzer with Management

Reporter

2a

Create a Windows Azure Service Bus

namespace

1

Configure an Active Directory Federation

service for authentication

2

Configure the Access Control Service

3

Update party federation metadata

4

5

Optional: Configure Management

Reporter

6

Install and configure Business Analyzer

7

The steps in the diagram correspond to sections of this document. The following list shows the order in

which you must complete these steps:

Step 1: Creating a new Windows Azure Service Bus namespace

Step 2: Configure an Active Directory Federation Service for authentication

Step 2a: Optional: Add a trust relationship and claim rule for Business Analyzer with Management Reporter

Step 3: Configuring the Access Control Service

Step 4: Update the relying party federation metadata

Step 5: Configuring the on-premises server for Companion apps

Step 6: Optional: Configure Management Reporter


Step 7: Install and Configure Business Analyzer

Install and Configure Business Analyzer

After you have configured your Microsoft Dynamics AX environment for use with Business Analyzer, complete the following steps to install and configure the app. You or your company’s app users will have to repeat this procedure for each tablet or PC that the app is installed on.

1. Install the app from the Windows Store on your Windows 8 device:

http://go.microsoft.com/fwlink/?LinkID=330401

2. Open Business Analyzer.

3. Swipe in from the right edge of the screen, and then tap Settings. (If you're using a mouse, point to the upper-right corner of the screen, move the mouse pointer

down, and then click Settings.)

4. Tap or click Configuration.

5. Turn the Sample Report Mode setting off.

6. Enter your user name and password.

7. Enter the service connection name. This is the name of the Service Bus namespace that was set

up in the Create a new Windows Azure Service Bus namespace section of this white paper

8. Tap Connect.

http://go.microsoft.com/fwlink/?LinkID=330401

47


Optional: Configure Management Reporter

To view Management Report content within the Business Analyzer app, you must complete the following prerequisites and procedures:

Prerequisites:

Install Management Reporter Cumulative Update 7. For more information, see http://go.microsoft.com/fwlink/?LinkId=389296.

Enter the correct Management Reporter server location for Microsoft Dynamics AX. Open the Configuration Console where the Management Reporter server components are installed and

click Publish server connection.

Install Windows Identity Foundation. For more information, see http://www.microsoft.com/en-us/download/details.aspx?id=17331.

Download the following Windows PowerShell script package:


Complete the following procedures in the following order:

1. Add a trust relationship and claim rule for Business Analyzer with Management Reporter

2. Configure Management Reporter settings and enable Management Reporter data retrieval for app users

3. Install required Management Reporter hotfixes

Add a trust relationship and claim rule for Business Analyzer with Management

Reporter

1. Open Trust Relationships > Relying Party Trusts.

2. In the Actions pane, click Add Relying Party Trust to display the Add Relying Party Trust Wizard.

Figure B1: Add Relying Party Trust

3. Click Start.

4. On the Select Data Source page, select the Enter data about the relying party manually option, and then click Next.

5. On the Specify Display Name page, enter a display name, and then click Next.

6. On the Choose Profile page, select the AD FS profile option, and then click Next.

7. On the Configure Certificate page, click Next.






8. On the Configure URL page, select the Enable support for the WS-Federation Passive protocol check box, enter your relying party WS-Federation Passive protocol URL, and then click Next. This URL should use the following format:

https://[AzureNamespace].servicebus.windows.net/reportingsecure/Report.svc/authentication/v2/

wsfederation

Figure B2: Configure URL page

49


9. On the Configure Identifiers page, add the Service Bus endpoint, and then click Next.

Figure B3: Configure Identifiers page

10. On the Ready to Add Trust page, click Next, and then finish the setup by clicking Close. The Open the Edit Claim Rules dialog for this relying party trust when the wizard closes option is selected by default. When the wizard closes, the Edit Claim Rules form will open.

11. Click Add Rule to display the Add Transform Claim Rule Wizard.


12. On the Select Rule Template page, in the Claim rule template field, select Send LDAP Attributes as Claims as shown in the following screen shot, and then click Next.

Figure B4: Select Rule Template page

13. On the Configure Rule page, enter a name for the claim rule.

51


14. In the Attribute store field, select Active Directory.

Figure B5: Configure Rule page

15. In the LDAP Aattributes to outgoing claim types grid, enter the following field values and then

click Finish:

LDAP Attribute: User-Principal-Name

Outgoing Claim Type: UPN

16. In the Edit Claim Rules form, you can see the newly created claim rule. Click Apply and then OK to save your changes.

You can get back to the Edit Claim Rules form by right-clicking the relying party trust that you just

added and then selecting Edit Claim Rules.

Configure settings and update the database schema for Management Reporter

Before you can use Business Analyzer with Management Reporter, you must configure the

MRServiceHost.settings.config file, and you must also add the required database schema to the Management Reporter database. Two Windows PowerShell scripts are available to help you complete these tasks. Download the Windows PowerShell script package from the following location:


The package is a .zip file that contains two Windows PowerShell scripts:

Configure-ManagementReporterActOnBehalfOf – Run this script to add the required database schema to the Management Reporter database and to insert the record for the user who has permission to act on behalf of another user.



ConfigureAzure-ManagementReporter – Run this script to configure the MRServiceHost.settings.config file. Running this script is optional. Instead, you can manually configure the MRServiceHost.settings.config file by using the following information.

(For more information about Windows PowerShell, see http://technet.microsoft.com/en-

us/library/dn425048.aspx.)

Configure the MRServiceHost.settings.config file manually

Before you can use Business Analyzer with Management Reporter, you must configure the MRServiceHost.settings.config file so that Management Reporter can authenticate with the Active Directory Federation Service (AD FS) and register itself with the proper Windows Azure Service Bus.

The MRServiceHost.settings.config file is installed during Management Reporter Server installation, and you can find it in the following location:

%Program Files%\Microsoft Dynamics ERP\Management Reporter\2.1\Server\Services

You can manually configure the MRServiceHost.settings.config file, or you can download and install a Windows PowerShell script that will configure the file for you.

1. Open the MRServiceHost.settings.config file for editing.

2. Locate the content between the <appSettings> and </appSettings> tags, and add the following rows of code:

<add key="AdfsRealm" value="https://contosomobile.servicebus.windows.net"/>

<add key="AdfsIssuer" value="https://contosoadfs.com/adfs/ls" />

<add key="AdfsThumbprint" value="faf8b8778a50e1d07357..." />

<add key="AdfsName" value="https://contosoadfs.com" />

<add key="ServiceBusDefaultIssuer" value="owner" />

<add key="ServiceBusDefaultKey" value="S83sFqJNg/1kgiSpqzZC+NHSJLRK0IEPuz7kR2gbnps=" />

<add key="ServiceBusAddress"

value="https://contosomobile.servicebus.windows.net/reportingsecure/Report.svc" />

<add key="AdfsAudienceURI" value="https://contosomobile.servicebus.windows.net" />

<add key="AdfsClaim" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn" />

<add key="EnableMROverAzure" value="true" />

Note: The MRServiceHost.settings.config file might already contain additional rows in the

appSettings section.

3. Replace the sample values in the rows that you added with the values that are specific to your Microsoft Dynamics AX environment, save your changes, and then restart the Management Reporter Process Service and Management Reporter Application Service. Use the following table to determine where the values are referenced in this white paper.

Variable Reference in this white

paper

Example value from this white

paper

AdfsRealm Add a trust relationship and claim rule for Business Analyzer with Management Reporter

https://contosomobile.servicebus.windows.net

AdfsIssuer Add/Configure the token signing certificate

https://contosoadfs.com/adfs/ls

AdfsThumbprint Add/Configure the token signing certificate

faf8b8778a50e1d07357…

AdfsName Configure an Active Directory Federation Service for authentication

https://contosoadfs.com

http://technet.microsoft.com/en-us/library/dn425048.aspx

http://technet.microsoft.com/en-us/library/dn425048.aspx

53


Variable Reference in this white paper

Example value from this white paper

AdfsAudienceURI Add a trust relationship and claim rule for Business Analyzer with Management Reporter

https://contosomobile.servicebus.windows.net

AdfsClaim Verify claim descriptions http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn

ServiceBusDefaultIssuer Create a new Windows Azure Service Bus namespace

owner

ServiceBusDefaultKey Create a new Windows Azure Service Bus namespace

S83sFqJNg/1kgiSpqzZC+NHSJLRK0IEPuz7kR2gbnps=

ServiceBusAddress Create a new Windows Azure

Service Bus namespace

https://contosomobile.servicebus.windows

.net/reportingsecure/Report.svc

EnableMROverAzure true

Note: The AdfsAudienceURI and AdfsRealm variables will likely be the same value.

Install required Management Reporter hotfixes

Before you can use Management Reporter in Business Analyzer, you must install the following Management Reporter hotfix:




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.

The example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted

herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person,

place, or event is intended or should be inferred.

Microsoft, Active Directory, PowerShell, Microsoft .NET Framework, Microsoft Dynamics, Microsoft Lync, Windows, and Windows

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

http://www.microsoft.com/dynamics

Configure the Microsoft Dynamics AX Environment for Companion Apps

Documents

Transcript of Configure the Microsoft Dynamics AX Environment for Companion Apps