Microsoft Dynamics AX 2012 ÂŽ
Configure the Microsoft Dynamics AX environment for companion apps White Paper
February 2015 www.microsoft.com/dynamics/ax
Send suggestions and comments about this document to adocs@microsoft.com. Please include the title with your feedback.
Table of Contents Introduction ................................................................................................ 3 Prerequisites............................................................................................... 4 Create a new Windows Azure Service Bus namespace with a companion ACS namespace ........................................................................................... 5 Configure an Active Directory Federation Service for authentication .......... 6 1. 2. 3. 4. 5. 6.
Enable the service endpoint for Windows Authentication. ....................................................... 6 Verify that the required certificate exists and is configured properly ........................................ 8 Export the certificate ......................................................................................................... 9 Verify claim descriptions ...................................................................................................11 Add the trust relationship and claim rule .............................................................................12 Save the AD FS FederationMetadata.xml file ........................................................................18
Configuring the Access Control Service ..................................................... 19 Add and configure the identity provider ..................................................................................20 Configure the relying party applications ..................................................................................22 Configure rule groups ...........................................................................................................23 Add a claim rule for the identity provider ............................................................................. 24
Update the relying party federation metadata .......................................... 26 Configuring the on-premises server for Companion apps .......................... 27 Install the required hotfixes for Microsoft Dynamics AX 2012 R2 ................................................27 Install Microsoft Dynamics AX Connector for Mobile Applications ................................................27 To install the Microsoft Dynamics AX Connector for Mobile Applications ................................... 28
Configuring the Windows 8 or mobile phone applications ......................... 34 Appendix 1: Configuring the Approvals app .............................................. 35 Viewing recent approval items ...............................................................................................35 Configuring the Approvals app ...............................................................................................35 Configuring the tiles .............................................................................................................37 Configuring the Overview tab ................................................................................................38 Adding reports .....................................................................................................................38 Using Microsoft Lync integration ............................................................................................38
Appendix 2: Windows Phone 8 .................................................................. 40 Appendix 3: Microsoft Dynamics Business Analyzer .................................. 41 Install and Configure Business Analyzer ..................................................................................42 Optional: Configure Management Reporter ..............................................................................43 Add a trust relationship and claim rule for Business Analyzer with Management Reporter .......... 43 Configure settings and update the database schema for Management Reporter ........................ 47 Install required Management Reporter hotfixes ..................................................................... 49 2 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. NOTE: If you are using Windows Server 2008, you must download and install the AD FS 2.0 software to deploy your AD FS server infrastructure. However, if you are using Windows Server 2012 R2, you can install the AD FS server role using Server Manager. Server Manager provides improved AD FS configuration wizard pages that perform server validation checks before you continue with the AD FS server role installation and will automatically list and install all the services that AD FS depends on during the AD FS server role installation. 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.
3 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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/enus/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. Install Azure PowerShell. http://azure.microsoft.com/en-us/documentation/articles/install-configure-powershell/#Install
4 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
Create a new Windows Azure Service Bus namespace with a companion ACS namespace Note: As of August 2014, you cannot use the Azure Management Portal to create the service bus namespace for use with Microsoft Dynamics AX companion applications. You must use Azure PowerShell to create the service bus service namespace. The Microsoft Dynamics AX Connector for Mobile Applications deploys a listening endpoint that services the message coming from the Microsoft Dynamics AX mobile phone application. This endpoint address is structured around the Windows Azure namespace that you will create. To create a new service bus service namespace with a companion ACS namespace, complete the following steps: 1. Open Azure PowerShell. 2. In the PowerShell command prompt, enter the following command to connect Azure PowerShell to your Azure subscription: Add-AzureAccount
3. When you are prompted for your credentials, enter your credentials for your Azure subscription. 4. In the PowerShell command prompt, enter the following command to add a new service bus service namespace with a companion ACS namespace: New-AzureSBNamespace –name “InsertNameHere” –location “InsertRegionHere”
Property
Description
-name
Enter the name of the service namespace.
-location
Enter your region. The list of region values
5. If you followed the steps correctly and there were no errors, the following information is displayed.
Name: Region: DefaultKey: Status: CreatedAt: AcsManagementEndpoint: ServiceBusEndpoint: ConnectionString:
[Name] [Region] 2pRUX4K5EhE5XKvDsaS+816/Nrqzztkgur/CKsib40w= Active 8/26/2014 7:24:31 PM https://name-sb.accesscontrol.windows.net/ https://name.servicebus.windows.net/ Endpoint=sb://SBName.servicebus.windows.net/;SharedSecretIssuer=own er;SharedSecretValue=2pRUX4K5EhE5XKvDsaS+816/Nrqzztkgur/CKsib40w=
6. Copy the DefaultKey, ServiceBusEndpoint, and ConnectionString for reference later. You will use the 256-bit secret default key when you configure the Microsoft Dynamics AX Connector for Mobile Applications service that is deployed on the server. For more details, see Configuring the on-premises server for Companion apps.
5 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
Configure an Active Directory Federation Service for authentication AD FS communicates with your organization’s instance of Active Directory Domain Services to authenticate users of the Microsoft Dynamics AX companion apps. Users are authenticated based on credentials that are sent by the companion app. Upon successful authentication, AD FS returns a token to the companion app. Before this communication can happen between AD FS and Active Directory Domain Services, you must configure AD FS. For more information about Active Directory federation servers, see http://technet.microsoft.com/enus/library/dd807089(v=ws.10).aspx. The following diagram shows the ADFS configuration steps to complete:
1. Enable the service endpoint for Windows Authentication. 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. 3) After you enable the service endpoint, the authentication server URL of this Federation Service will be formatted like the following URL: https://<FederationServiceName>/adfs/services/trust/13/usernamemixed. Example: https://contosoadfs.com/adfs/services/trust/13/usernamemixed 4) Click Start > Administrative Tools > Service to open the Windows Services list. Restart the AD FS 2.0 Windows service.
6 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
5) In the Endpoints list, ensure that the three endpoints in the Metadata section are enabled, as shown in the following screen shot.
Figure 2: Windows Endpoints list
7 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
2. Verify that the required certificate exists and is configured properly The Microsoft Dynamics AX Connector for Mobile Applications service requires the thumbprint of the X.509 token signing certificate used by the Federation Service. You must verify that the required certificate exists and is configured properly. Both the service communications and tokensigning certificates are configured when you run the AD FS 2.0 setup wizard. Consider the following information: o
You can see the list of certificates by clicking Certificates under the Services node in the left navigation pane of the AD FS 2.0 Management tool. For more information about certificate requirements for federation servers, see http://technet.microsoft.com/enus/library/dd807040(v=ws.10).aspx.
o
Before you can add any new certificates, you may have to disable the automatic certificate rollover feature by using Windows PowerShell commands. For steps on how to add a tokensigning certificate, see http://technet.microsoft.com/en-us/library/dd807039(v=WS.10).aspx.
Figure 3: AD FS 2.0 Management Certificate Alert
o
Set the X5.09 token signing certificate as the primary certificate.
8 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
3. Export the certificate After you verify that the X.509 Token-Signing certificate exists and was configured correctly, you must export the certificate and save it to the Trusted Root Certification Authorities store on the server machine that hosts the Microsoft Dynamics AX Connector for Mobile Applications service. To export the certificate, complete the following steps: 7. Click Start > Administrative Tools > AD FS 2.0 Management to open the AD FS 2.0 Management tool. 8. Select the token signing certificate in the Certificates list. Right-click, and then select View Certificate.
Figure 4: Certificates list
9 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
9. On the Details tab of the Certificate form, select Thumbprint and then click Copy to File, as shown in the following screen shot.
Figure 5: Certificate dialog box
10. Save the certificate 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. 11. 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. NOTE: If you are not using a token-signing certificate that is issued by a trusted Certification Authority, you can use a self-signed certificate. You must export this certificate from your ADFS server and add it to the Trusted People certificate store on this machine. However, using a self-signed certificate is not an optimal configuration choice. 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/. You can validate that your service is set up correctly by opening the URL https://contosoadfs.com/adfs/fs/federationserverservice.asmx in a browser.
10 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
ď&#x201A;ˇ
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.
4. 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â&#x20AC;&#x2122;ll need this when you configure the MRServiceHost.settings.config file. For more information, see 8. Optional: Configure Management Reporter.
Figure 6: Claim descriptions list
11 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
5. Add the trust relationship and claim rule Active Directory Domain Services is the claim provider trust for issuing claims about an authenticated user.
Figure 7: 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. 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/200706/FederationMetadata.xml
12 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
In our example, this address is https://contosomobilesb.accesscontrol.windows.net/FederationMetadata/2007-06/FederationMetadata.xml, as shown in the following screen shot.
Figure 8: 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://contosomobilesb.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. 3. Click Next.
13 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
4. On the Specify Display Name page, enter a display name or leave the default value, and then click Next.
Figure 9: Add Relying Party Trust Wizard Specify Display Name page
14 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
5. 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 10: Add Relying Party Trust Wizard Choose Insurance Authorization Rules page
6. 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 11: Edit Claim Rules page
15 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
7. Click Add Rule. You will be guided through the Add Transform Claim Rule Wizard. 8. 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 12: Select Rule Template page
9. On the Configure Rule page, enter a name for the claim rule. 10. In the Incoming claim type field, select Windows account name.
16 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
11. Select the Pass through all claim values option, as shown in the following screen shot, and then click Next.
Figure 13: Configure Rule page
12. In the Edit Claim Rules form, you can see the newly created claim rule. Click Apply and then OK to save your changes.
Figure 14: Edit Claim Rules form
17 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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.
6. 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/200706/FederationMetadata.xml. 2. Save the FederationMetadata.xml file to any location on your PC. 3. Upload the FederationMetadata.xml file to the ACS management portal (if the Federation Service does not have an Internet-facing IP address), or 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.
18 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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â&#x20AC;&#x201C;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 15: Access Key dialog box
The Access Control Service page will open.
Figure 16: Windows Azure Access Control Service page
19 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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 17: 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. On the Edit WS-Federation Identity Provider page, enter a display name for the identity provider, such as Contoso ADFS. 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.
20 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
Figure 18: Identity Provider Settings page
In the Used By section, under Relying party applications, ensure that the Service Bus check box is selected.
Figure 19: Used By section of the Identity Provider Settings page
21 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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 20: 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 21: Windows Azure Relying Party Application Settings page
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.
22 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
Select the Default Rule Group for ServiceBus check box to use the default rule group, as described in the Configure rule groups section.
Figure 22: Windows Azure Authentication Settings page
Configure rule groups 1) In the left navigation pane, click Rule Groups. Select the Default Rule Group for ServiceBus check box to configure the default rule group.
Figure 323: Windows Azure Rule Groups page
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.
23 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
Delete the rules that have Output claim values of Manage and Send.
Figure 24: 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. 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. 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 Under Input claim value, leave the fields as-is. Under Output claim type, select the Enter type option, and then enter the value net.windows.servicebus.action. Under Output claim value, select the Enter value option, and then enter Send.
24 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
Optionally, add a description.
Figure 25: Windows Azure Edit Claim Rule page
This completes the required Access Control Service configuration.
25 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
Update the relying party federation metadata 1) On the Federation Service server, open the AD FS 2.0 Management tool. In the left navigation pane, expand Trust Relationships, and then select Relying Party Trusts. 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. Click Update.
Figure 26: Relying Party Trusts page
26 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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 Please check the Partnersource page for the latest information on available hotfixes: https://mbs.microsoft.com/partnersource/northamerica/news-events/news/MSDYN_MobileAppsAX
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
o
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
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. 27 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
To install the Microsoft Dynamics AX Connector for Mobile Applications 1) Download and unzip the Microsoft Dynamics AX Connector for Mobile Applications Zip package. The Connector is also available on the partnersource page: https://mbs.microsoft.com/partnersource/northamerica/news-events/news/MSDYN_MobileAppsAX 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 27: Microsoft Dynamics AX Connector for Mobile Applications Setup Wizard Welcome page
Select the I accept the terms in the License Agreement check box, and then click Next.
Figure 28: Microsoft Dynamics AX Connector for Mobile Applications Setup End-User License Agreement
28 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
On the Destination Folder page, accept the default folder location for the connector, or click Change to select another location. Then click Next.
Figure 29: Destination Folder page
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 30: Service account page
Click Install. Click Finish. Click Start > Administrative Tools > Service to open the Windows Services list.
29 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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 31: Services
30 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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 (DefaultKey) 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 Export the 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/Service s/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)
The following text is preconfigured in this field: net.tcp://<AOS_MACHINE_NAME>:8201/DynamicsAx/Service s/TimesheetServices 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 ApprovalsServices (if using the Approvals application)
The following text is preconfigured in this field: net.tcp://<AOS_MACHINE_NAME>:8201/DynamicsAx/Service s/ApprovalServices Replace <AOS_MACHINE_NAME> with the name of the machine that hosts AOS. Replace the default AOS port number, 8201, if a different port is used. 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)
The following text is preconfigured in this field: net.tcp://<AOS_MACHINE_NAME>:8201/DynamicsAx/Service s/EmailApproalsServices Replace <AOS_MACHINE_NAME> with the name of the machine that hosts AOS. Replace the default AOS port number, 8201, if a different port is used.
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 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.
ADFS URL
An authentication server URL. This is the endpoint URL of the AD FS server that was set up in the Enable the service endpoint for Windows Authentication section. In our example, this URL is in the form https://contosoadfs.com/adfs/services/trust/13/usernamemixed
31 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
Support Email
An email address the mobile user will see to contact in case of any issues. For example, support@contoso.com
On the Start menu, click the Microsoft Dynamics AX Connector for Mobile Applications shortcut. The GUI for configuring the connector parameters will open. Use the information in the following table to configure the connector parameters. 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 32: RapidStart Services parameters setting form
32 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
Enter values for each parameter, and then click Save. 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 33: RapidStart Services parameters setting form
33 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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.
34 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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
35 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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
Although the extended context for timesheets and expenses is built into the app and canâ&#x20AC;&#x2122;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
36 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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â&#x20AC;&#x2122;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. In the AOT, click Classes > PSAPRojQuotationDocument. 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 RecId
_tableId, _recId)
{ SalesQuotationTable t; 37 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
if(_tableId == tableNum(SalesQuotationTable)) { t = SalesQuotationTable::findRec(_recId); return t.invoiceAmount(); } return 0; }
Complete an Incremental CIL compilation. Return to the Windows Store App configuration screen, and select Value as the new field to show on the tile. 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â&#x20AC;&#x2122;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. 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. 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.
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 38 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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.
39 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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-dynamicsax: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.
40 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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.
1
2
Create a Windows Azure Service Bus namespace
4
3
Configure an Active Directory Federation service for authentication
Configure the Access Control Service
Update party federation metadata
5 2a
Optional: Add a trust relationship and claim rule for Business Analyzer with Management Reporter
Configure the onpremises server for companion apps
6
Optional: Configure Management Reporter
7
Install and configure Business Analyzer
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 ď&#x201A;ˇ
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 41 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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â&#x20AC;&#x2122;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.) Tap or click Configuration. Turn the Sample Report Mode setting off. Enter your user name and password. 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 Tap Connect.
42 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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/enus/download/details.aspx?id=17331. Download the following Windows PowerShell script package: http://go.microsoft.com/fwlink/?LinkId=389274 Complete the following procedures in the following order: 1) Add a trust relationship and claim rule for Business Analyzer with Management Reporter Configure Management Reporter settings and enable Management Reporter data retrieval for app users 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
Click Start. On the Select Data Source page, select the Enter data about the relying party manually option, and then click Next. On the Specify Display Name page, enter a display name, and then click Next. On the Choose Profile page, select the AD FS profile option, and then click Next. On the Configure Certificate page, click Next.
43 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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
44 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
On the Configure Identifiers page, add the Service Bus endpoint, and then click Next.
Figure B3: Configure Identifiers page
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. Click Add Rule to display the Add Transform Claim Rule Wizard.
45 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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
On the Configure Rule page, enter a name for the claim rule.
46 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
In the Attribute store field, select Active Directory.
Figure B5: Configure Rule page
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 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: http://go.microsoft.com/fwlink/?LinkId=389274 The package is a .zip file that contains two Windows PowerShell scripts: Configure-ManagementReporterActOnBehalfOf â&#x20AC;&#x201C; 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.
47 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
ConfigureAzure-ManagementReporter â&#x20AC;&#x201C; 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/enus/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â&#x20AC;Ś
AdfsName
Configure an Active Directory Federation Service for authentication
https://contosoadfs.com
48 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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+NHSJLRK0IEPuz7 kR2gbnps=
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: http://go.microsoft.com/fwlink/?LinkId=386401
49 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS
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.
50 CONFIGURE THE MICROSOFT DYNAMICS AX ENVIRONMENT FOR COMPANION APPS