There hasn’t been much documentation released on how to actually use Microsoft Dynamics GP 2015 service-based architecture. In an effort to share information, I’ve outlined my own interactions with GP’s service-based architecture and how I got it to work.

What’s included in this overview:

  • Installing Microsoft Dynamics GP 2015
  • Tenant configuration for GP 2015
  • CORS validation
  • Web service security​
  • Making calls to the web service
  • Helpful URLs
  • Logs

Installing Microsoft Dynamics GP 2015

The installation itself is pretty straightforward. Like most software, you just run through the wizard on the install media, although there were a couple of things I found to be kind of tricky:

  • When prompted for Session Central Service credentials during the install, don’t use your own (even in a dev environment). The service account has to serve as a delegate and you can’t delegate for yourself.
  • If you choose to use SSL (as you definitely should for any production environment), when you choose a certificate in the drop-down, the Host Name will be automatically populated. If you click Next, you’ll be told that the Host Name can’t contain special characters. If your Host Name looks like mine did, “*.mydomain.com, OU=Domain Control Validated”, you will need to delete everything from the comma onward and choose a specific sub-domain (I was using a wildcard certificate).
  • If you choose to install (as I did) in a multi-tenant configuration, you have to do additional configuration on the tenant (see below).
  • Pretty much nothing works if you are not connected to your AD controller.
  • Two (GPService and GP Session Central Service) of the 5 (minimum) Windows services installed to support SBA, never start successfully after a reboot, even if they are set to Automatic (Delayed Start). I expect this will be fixed (and may already), but I did this testing against the RTM version.

Additional Configuration

Assuming you have everything up and running, there are still a few tasks that need to be addressed in order to make a service call.

Tenant configuration

Based on the responses I got from Microsoft while running a case on this, it looks like majority of users deployed SBA in single tenant mode, in which case your tenant configuration is stored in the TenantConfiguration.xml in the GPService folder. However, if you’re using multi-tenant, then it’s stored in the database.

To configure your tenant:

  1. Open the Web Management Console.
  2. Click on Tenant Manager.
  3. Double click your Tenant.
  4. Click on GP Services under Application Settings
  5. Set the following values:
    • DynamicssetLocation: the full path to your GP Dynamics.set file (i.e. C:\Dynamics\GP2015\Dynamics.set)
    • DexiniLocation: the full path to your GP Dex.ini file (i.e. C:\Dynamics\GP2015\Data\Dex.ini)
    • SQLUserName: the same SQL user you entered during installation.
    • GPVersion: 14
    • GPInstanceName: the name of your GP instance or DEFAULT if using the default instance.
    • RequestLoggingEnabled: if set to true, you’ll get a lot more detail on each individual call to the server (see more information on Logs below).
    • OperationTimeOut: leave empty.

CORS validation

I was using the Chrome extension POSTMAN to make it easier to test the various HTTP verbs, but I was getting 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.
It turns out, you have to open up the configuration database (defaults to GPCONFIGURATION) and add a new row to the SBACorsAllowedOrigin table. The Name column doesn’t matter, but the origin column should match the origin between the quote marks in the exception above.

Web service security

Although the web service connects to the database itself as the same user every time (e.g. the one you specify in the tenant configuration), access to the procedures by the calling user is managed through security within Dynamics GP itself.

In order to access the web services at all, a user needs to be set up and the Directory Account set to the Windows Account of the identity that will be making the requests. Theoretically, this should all work with the new organizational accounts (e.g. Office 365 or Windows Azure AD) also, but I have not had the time yet to figure out how to pass through those credentials (should be by OAuth, I think).

If you give the user a POWERUSER role, they will be able to use all of the web service procedures. If you want to give more granular control, then you can use Security Tasks (Tools > Setup > System > Security Tasks) and Security Roles (Tools > Setup > System > Security Roles) to give explicit access.

When creating a security task, there’s a new Type (Service Enabled Procedures) that can be used to give access at the procedure level.

Making calls to the web service

From here, things are pretty straightforward. It’s just basic REST with a couple of pointers. By convention, REST treats collections of things like folders on a web server, at least when it comes to the URL. See below for some examples working with a demo item (in JSON format) to get a hang of how the calls are made.

1. Create an item

​Method: POST (note: not PUT)
URL: https://mymachine:myport/GPService/Tenants(Test)/Companies(Fabrikam,%20Inc.)/Inventory/Items(note: the item number isn’t included in the URL)
Headers:
Content-Type: application/json
Accept: application/json
Body:
{
“Payload”:{
“ItemNumber”:”DEMO”,
“ItemShortName”:”Demo Item”,
“ItemDescription”:”Demo Item created with SBA”,
“UOfMSchedule”:”EACH”
}
}

A couple of things to note here. First, the information you’re sending will always be in a sub-object calledPayload. Second, the procedures do vary somewhat from the functionality we’re used to in the older web services or eConnect. From what I can tell (in this case, at least) defaulting values from an inventory class aren’t really supported.

2. Retrieve all items

Method: GET
URL: https://mymachine:myport/GPService/Tenants(Test)/Companies(Fabrikam,%20Inc.)/Inventory/Items
This will return the items in XML format. To return them in JSON format, just append .json to the end of the URL: https://mymachine:myport/GPService/Tenants(Test)/Companies(Fabrikam,%20Inc.)/Inventory/Items.json

3. Retrieve a single item

Method: GET
URL:https://mymachine:myport/GPService/Tenants(Test)/Companies(Fabrikam,%20Inc.)/Inventory/Items(ItemNumber)

4. Update an item

Method: PATCH
URL:https://mymachine:myport/GPService/Tenants(Test)/Companies(Fabrikam,%20Inc.)/Inventory/Items(ItemNumber)
Headers:
Content-Type: application/json
Accept: application/json
Body:
{
“Payload”:{
“ItemNumber”:”DEMO”,
“ItemShortName”:”Demo Item”,
“ItemDescription”:”Demo Item updated with SBA”,
“UOfMSchedule”:”EACH”
}
}

*Note* Although this functionality is specific by procedure (it just depends on how that given procedure was coded), in the case of items, although the procedure supports merging a partial item object (in other words, it will update ItemDescription if you include it in your Payload object but will not change it if that property is simply missing), it does required field validation only against the supplied object. Therefore, you have to pass all required fields even if the only one you want to update is ItemDescription.

5. Remove an Item

Method: DELETE
URL:https://mymachine:myport/GPService/Tenants(Test)/Companies(Fabrikam,%20Inc.)/Inventory/Items(ItemNumber)

6. Discovery Service

Finally, a lot more detail for the methods that are available can be found at https://mymachine:myport/GPService/Tenants(Test)/Companies(CompanyName)/Help. This has all of the methods by product and some information about the call and response.

Helpful URLs

  • https://mymachine:myport/GPService/Tenants(Test)/Companies(Fabrikam,%20Inc.)/Utility/Ping: returns a timestamp if the minimum amount of stuff is working.
  • https://mymachine:myport/GPService/Management/Diagnostics: gives a good bit of information on your install. At a minimum, you need to have at least 1 Tenant listed and one value in the RoutingTable or you won’t be getting a lot out of the service.

Logs

The following locations have diagnostic information.

  • %programdata%\Microsoft Dynamics\GPSvc\Logs\DexterityControlService: log for the Dexterity Control Service.
  • %programdata%\Microsoft Dynamics\GPSvc\Logs\GPService: log for the GP service itself (the main entry point, so the first place to check for errors).
  • %programdata%\Microsoft Dynamics\GPSvc\Logs\Inst_[instance_name]\DexterityRequests: 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.

This area actually has been fairly well documented on the now-defunct Developing for Dynamics GP blog.