Hello All,

This article serves as a single contact for Service Based Architecture (SBA) Installation and Troubleshooting.   For related troubleshooting with Web Client, that can be found here at Dynamics GP Web Client Troubleshooting.

For a recap and consolidation of getting started with SBA you can find that at SBA Implementation

Service Based Architecture (SBA) is a feature that provides a REST web service which exposes Dynamics GP business logic as service operations.

The Following will be covered. 

Prerequisites

  1. The >Web Server (IIS) Feature Must be installed with these settings

  2. The Website must have a SSL Certificate bound to it
    1. The installation will not allow you to proceed with the deployment of the Web Management Console without this requirement.
  3. For the Dynamics GP Client that will be used for SBA (typically the Web Server Host), the Service Based Architecture Feature must be installed.
  4. A Web Client SQL Server Login must be setup for Service Based Architecture
    1. A Domain User that accesses the SBA endpoint must be setup as a user in Dynamics GP
    2. To facilitate the mapping of a domain user to a GP user, the Web Client SQL Server login must be utilized.
    3. If the System Database is not yet setup, you will see it in the initial setup of the System Database. If it is already present, you will need to set this up from the Additional Tasks window.
    4. User that is specified in the Manage Web Client SQL Server Login window should NOT be a GP User.
  5. Dynamics GP User Setup
    1. User Security Setup Window
    1. Domain User must be mapped to a GP User
      1. User Setup window on the Windows Account Tab
    2. GP User must have access to the companies that the Domain User needs to integrate
      1. User Access Setup Window
    3. GP User must have access to the resources in GP the Domain User will integrate

      As an example, if Doman\User needs to access to create customers through SBA, Domain\User would need to be tied to a GP User, the GP User would need to have access to the company in which the Domain\User would create customers and the GP User would need access to the Customer Maintenance window Dynamics GP.

    1. Tenant Services:  **This is only required if a Multitenant environment is desired.  At a minimum, the installation has been done of Tenant Services before the installation of SBA. No Setup is needed.

    Deployment of SBA (Single Tenant)

    *** The installation is done from the GP media.
    *** Do to the similarity of the installations, steps for a single tenant and multitenant installation are included together.

    1. Dynamics GP Media
      After Launching Setup.exe as Administrator in the folder that houses the GP media and installing any prerequisite software, the above window will be provided.
      1. The Web Components option needs to be selected.
        *Note* : The option for Web Client and Web Components perform the same action.
    2. License Agreement Window
      1. The installation cannot continue until the option for “I accept the terms in the License Agreement” has been selected.
      2. Click the Next >> button to continue.
    3. Installation Option Window

      The two options on this window are:
      Single Machine – Installs components for a Single Machine deployment with the default settings
      Custom – The desired components and settings can be selected for the installation.
      1. The option for Custom should always be selected. With this option, when a repair is done, settings made during the installation can be changed.
    4. Select Features Window
      1.  The screens Below show the minimum settings to deploy only Service Based Architecture and only in a Single Tenant Deployment.  If the above was for a Multitenant deployment, the selection of the Tenant Manager snap-in under Web Management Console would also be needed. Though the screenshots above done show it, you can deploy Web Client and Service Based Architecture to the same machine in the same installation.

        b. Once selected, click the Next >> button to continue.
    5. Web Components Database
      1. ON this window, enter in the name of the SQL Server with instance (if applicable) that will house the GPCONFIGURATION Database.
      2. Credentials must be supplied that have rights in SQL to create a database and its objects.
      3. Once entered, click the Next button to continue.
    6. Windows User Group Window
      1. With only the Service Based Architecture options selected, the only field available for entry is the Web Management Console Users field. If Web Client was installed, the Web Client Users field would also be available.
      2. In the Web Management Console Users field, you will want to enter those users and groups that would be administering Service Based Architecture.
      3. Once entered, click the Next >> button to continue.
    7. Tenant Configuration Window
      1. If a Single Tenant deployment is desired, accept the defaults on this window and click the Next >> button to continue.
      2. If a Multitenant deployment is desired, the following will need to be done:
        1. Check the “Deploy for multiple tenants” checkbox
        2. Enter in the URL for the Discovery Service in Tenant Services
        3. Enter in the URL for the Management Service in Tenant Service
        4. Click the Next button to Continue.
          For the Discovery Service value, you will want to enter the base address for this service. It can be found in the Microsoft.Dynamics.MultitenantServices.Discovery.config, which is located in the following folder by default:
          C:\Program Files\Microsoft Dynamics\Tenant Services\DiscoveryService
          The information is found in the following section:
                    <baseAddresses>
                      <add baseAddress="http://Machine:Port/TenantDiscoveryService" />
                    </baseAddresses>
          For the Management Service, you will want to enter the base address for this service. It can be found in the Microsoft.Dynamics.MultitenantServices.Management.config, which is located in the following folder by default:
          C:\Program Files\Microsoft Dynamics\Tenant Services\ManagementService
          The information is found in the following section:
                    <baseAddresses>
                      <add baseAddress="http://Machine:Port/TenantManagementService" />
                    </baseAddresses>
    8. Web Management Console Configuration
      1. Select the Website that has an SSL Certificate bound to it.
      2. An identity for the user running the application pool for the GP Web Application must also be provided.
      3. Once entered, click the Next >> button to continue.
    9. GP Configuration Window

      1. This window is only present in a Single Tenant Deployment.
        1. This information is needed in a Multitenant Deployment as well, but it is entered in the application settings on the Tenant.
      2. For the Sql Server Login Name and Password, the same credentials that were supplied in Dynamics Utilities for the Web Client SQL Server Login must be supplied here.
      3. The GP Instance Name must be the instance of Dynamics GP that will be exposed to Service Based Architecture. The first installed GP Client will be on the DEFAULT Instance. Each instance after that will be named.
      4. The three paths for the Dynamics GP runtime folder, the Dynamics.set and the Dex.ini must be valid.
      5. Once the fields have been populated, select the Next >> button to continue
    10. GP Service Window
      1. The port number will default in, but any open port can be selected.
      2. An SSL certificate is required for the endpoint. After selecting the certificate from the drop-down menu, the host name field will be populated. Ensure that the base address that it lists is correct.
      3. A valid account must be provided for the service that will be laid down for the installation.
      4. Once this information is entered, click on the Next >> button to continue.
    11. Dexterity Service Control Window
      1. The port number will default in, but any open port can be selected.
      2. An SSL certificate is not required for the endpoint. If a certificate is selected, the host name field will be populated. Ensure that the base address that it lists is correct.
      3. A valid account must be provided for the service that will be laid down for the installation.
      4. Once this information is entered, click on the Next >> button to continue.
    12. Install Program Window
      1. The only action item on this window is to click the Install button.
      2. Once the installation is complete, the Microsoft Dynamics GP Web Components Configuration Wizard will appear to facilitate the creation of any needed databases.
    13. Welcome Window
      1.  Next to continue
    14. SQL Connection Information Window
      1. The only information that needs to be provided is an account that has access to create a database in SQL if the account used to install doesn’t have those rights.
      2. Click the Next >> button to continue.
    15. Configuration Status and Actions Window
      1. Next to continue
    16. Configuration Complete

    Validating the Deployment

    Validating the Services Are started

    1. GP Dexterity Service
      1. Includes the name of the instance and the version in the name of the name of the service
        This gets laid down with the installation of the Service Based Architecture feature in the GP Client
    2. GP Dexterity Service Control
      1. This is laid down with the Service Base Architecture installation
    3. GP Service
      1. This is laid down with the Service Base Architecture installation

    Verifying Access to the Help URL

    The Help URL is used to see examples and confirm access to the Service Based Architecture endpoint

    • https://Server:Port/GPService/Tenants(TenantName)/Help
    • https://Server:Port/GPService/Tenants(TenantName)/Companies(CompanyName)/Help

    ***Note:
    The user that installed Service Based Architecture should be able to access this URL without being mapped as a user in Dynamics GP.
    If you include the Company Name in the URL, the samples that are provided will be able to be directly run.

    Verifying Access to Dynamics GP Data

    • If the domain user calling the endpoint doesn’t have access to this information in Dynamics GP, they will not get the request to produce results.
    • Each of the URLs ends with .xml. By doing this, the results can be displayed in the Web Browser. If .xml is not included, you will be prompted to save or open the JSON file.
      • The contents of this file can be opened in a text application, like Notepad.

    Examples: 

    • https://Server:Port/GPService/Tenants(TenantName)/Companies(CompanyName)/Dynamics/Purchasing/Vendors.xml
    • https://Server:Port/GPService/Tenants(TenantName)/Companies(CompanyName)/Dynamics/Inventory/Items(100XLG).xml
    • https://Server:Port/GPService/Tenants(TenantName)/Companies(CompanyName)/Dynamics/Companies.xml

    Troubleshooting

    Diagnostic URL - https://Server:Port/GPService/Management/Diagnostics

    • This URL provides a great deal of information for the Service Based Architecture Environment
      At a minimum, you need to have at least 1 Tenant listed and one value in the Routing Table or you won’t be getting a lot out of the service.
    • Information included with this is:
      • Environment Information
      • Application Configuration Data
      • Session Host Data
      • Tenant Data
      • GP Instance information
      • Assembly information

    URL For Testing SBA

    • https://mymachine:myport/GPService/Tenants(Test)/Companies(Fabrikam,%20Inc.)/Utility/Ping
      • Returns a timestamp if the minimum amount of stuff is working.

    Session Host URL - https://Server:Port/GPService/Management/Hosts/Server.xml 

    • This URL provides information on the Session Host in the SBA environment.
    • Information included with this is:
      • Session Host Data
      • Utilization Data

    Logging
    The following locations have diagnostic information.  There is also often correlating errors found in Event Viewer, to further explain what is going on.

    • Log for the Dexterity Control Service.
      • %programdata%\Microsoft Dynamics\GPSvc\Logs\DexterityControlService: 
    • Log for the GP service itself (the main entry point, so the first place to check for errors).
      • %programdata%\Microsoft Dynamics\GPSvc\Logs\GPService: 
    • If RequestLoggingEnabled is true in your Tenant configuration, then a file will be logged here for each request coming into the service that has useful stuff like the URL of the request and the script log of the GP process that handled it.
      • %programdata%\Microsoft Dynamics\GPSvc\Logs\Inst_[instance_name]\DexterityRequests:


    Security

    • The specified user is not authorized to perform operations in this context.
      • Confirm that the user logged into windows is a mapped user to Dynamics GP
      • Confirm that the Service Account User for SBA service is mapped to a user in Dynamics GP.
      • Confirm that you have identical matching Web Client SQL Server Logins per
        • Prerequisite Step 4
        • Deployment Step 9
    • Web Client SQL Server Login

    HTTP Error