Getting started SBA Implementation, testing and troubleshooting

SBA Implementation and Troubleshooting

Here is a little background:  Service Based Architecture (SBA) is a set of services using REST – the most common type of web service. It is a means to get around the limitation imposed by eConnect and its parallel system of SQL stored procedures, as well as limitations on Web Services - since SBA is running the same code base as the Microsoft Dynamics GP client. This is a recap and review to get started with SBA.

Installation

The installation of SBA is straightforward. Microsoft Dynamics GP will also need to be installed on the machine that SBA will be installed on. Below are also a couple of things to keep in mind:

• The Single Machine installation option does not exist. Always use the Custom option.
• Web Client component is not required for SBA. However, I highly recommend the installation of it specifically for troubleshooting Identity Manager related issues.
• Don’t forget to select SBA Session Manager.
• If you choose to use SSL, make sure the host name that is auto populated is correct. Depending on what kind of certificate you use you might end up with something like “*.contoso.com, OU=Domain Control Validated”. You will need to delete everything from the comma onward, and replace the wildcard to the appropriate sub-domain. This host name most also resolve to the server you are installing the components.
• During installation, you will be asked to enter a SQL Server Login Name, this user is the proxy user used for identity manager. It is recommended not to use sa, as well as a domain user account like “contoso\username”. This user will be created automatically in SQL.
• Double check that all Web Component related services are running after installation.
• Once installation is complete, you should be able to reach the management endpoint by entering the following URL – http(s)://host.domain/GPService/Management
• I will not be covering multi-tenant.

Security

This is essentially what we refer to as the Identity Manager portion of the Web Components. Users will be prompted for a directory account when accessing some SBA endpoints. This directory account will need to be tied to a Microsoft Dynamics GP account – this is the same way that we would achieve automatic login on Web Client.

If this seems to be a problem, try accessing the installation of Web Client – if logging in with the directory user does not automatically log you into Microsoft Dynamics GP, there is an issue with your identity manager.

You can check troubleshooting steps regarding this issue here:

https://community.dynamics.com/gp/b/dynamicsgp/archive/2015/07/14/gp-web-client-39-web-client-user-only-39-or-windows-authenticated-user-login-issues

Once you have the user account assigned, you will want to grant this user the POWERUSER role which will allow them to use all of the SBA procedures. Granular control is also possible. You can find SBA related security tasks under the Service Enabled Procedures type.

One final note regarding users, SBA is not really asymmetric. Though, most SBA procedures complete relatively quick, if another request to SBA is received and the last one has not completed, it will result in a “user unauthorized” error. So, it may be a good idea to consider a pool of SBA users for a high-volume usage.

Tools Setup and CORS Validation

I recommend using a Chrome Extension POSTMAN for testing various SBA procedures:

https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en

First thing to do once you open the tool, make sure you enter the SBA user credential under the Authorization tab. You should only need to use Basic Auth on a traditional Windows domain, but more information regarding Azure authentication can be found here:

https://community.dynamics.com/gp/b/dynamicsgpengineeringteamblog/archive/2015/08/04/service-based-architecture-authentication-intro

Once you start testing some of the SBA procedures, you may encounter the following error:

CORS validation failed for the origin ‘chrome-extension://fdmmgilgnpjigdojojpjoooidkmcomcm’. Please ensure this origin has been explicitly allowed access to call this service in the server configuration.

You can check troubleshooting steps regarding this error here:

https://community.dynamics.com/gp/b/dynamicsgpengineeringteamblog/archive/2014/12/18/sba-cors

However, I’ve also found it easier to add a new entry into the SBACorsAllowedOrigin table located in the database specified during Web Component setup (usually called GPCONFIGURATION). The name field can be anything, but the origin field needs to match the origin from the error message; chrome-extension://fdmmgilgnpjigdojojpjoooidkmcomcm in our case.

Now for the fun bit, how do you use POSTMAN to actually send data to SBA?

You first need to change from GET to POST by clicking on the button located left side of the address bar.

Once you have done that, you will be able to select the Body tab, where you can either paste in the payload in raw mode, or select a payload file in binary mode.

SBA URL Paths

Here are things to keep in mind regarding SBA and the URL PATH used for its procedures.

• SBA will throw an “Authentication failed because the credentials received were invalid” message. This does not always mean an authentication error. If you already have verified identity manager and that users have the correct security roles assigned, it may simply mean you have entered an invalid URL path.
  
  SBA is very sensitive to the tenants name and companies name section of the URL. You can simply open a browser and navigate to http(s)://host.domain/GPService/Management/Diagnostics to get a list of available tenant on you SBA installation.

"Tenants": {

   "Stats": {

     "Timestamp": "2017-03-09T09:23:27.9125471-06:00",

     "Age": "00:00:12"

   },

   "Tenants": [

     {

       "Name": "DefaultTenant",

       "IsActive": true,

       "ApplicationInstance": "DEFAULT",

       "GPVersion": "16",

       "Revision": "96c317e236d7bf752405bce03433d7da01450e77"

     }

   ]

},

        For the company name, your best bet would be to check the entries in the SY01500 table in the Dynamics system database. Make sure to copy the exact entry in the CMPNYNAM field, including any spaces. Trust me, it matters.

• Always use the Help page, accessible by navigating to http(s)://host.domain/GPService/ Tenants(Tenant Name)/Companies(Company Name)/Help
  But be warned, if you are using the wrong tenants name and company name; you’ll end up with the issue noted on bullet one.

Web Management Console and Logging

Log files for SBA can be found in the following locations.

• %programdata%\Microsoft Dynamics\GPSvc\Logs\DexterityControlService – Logs for the Dexterity Control Service.
• %programdata%\Microsoft Dynamics\GPSvc\Logs\GPService – Logs for the GP service itself. This is a good place to start to check for errors.
• %programdata%\Microsoft Dynamics\GPSvc\Logs\Intst_[instance_name]\DexterityRequests – if request logging is enabled, then a file will be logged here for each request coming into the service. Another good place to check in case of an error.

You can find out more about enabling logging here:

https://community.dynamics.com/gp/b/dynamicsgpengineeringteamblog/archive/2015/03/24/service-based-architecture-debugging

Thank you!
Karl