Thursday, August 17, 2017

Accessing Dynamics 365 for Operations ODATA services with Postman

Postman is another application that you can use to call ODATA services. The application can do some Javascript scripting, making it more powerful than using Fiddler to call ODATA services.

As before, you will need an application registered through Azure portal so that you'll get a client ID with a client secret key, or a client ID with a username and password.

After that you'll need to download Postman from https://www.getpostman.com/

Open Postman, and if you're going to use your local D365O VM, then you'll need to go to the settings and turn off the "SSL certificate verification".

In Postman, you have something called Environments and Collections. An environment contains settings (ie. credentials) for a particular environment (ie. production, UAT, Dev, or local VM, etc). While a collection contains the ODATA requests. So the idea is you could use requests from any collection against any environment that you have specified.

To create a new environment, click the gear icon on the top right side of the application, then choose the Manage Environments and click the Add button.
Give a name for the new environment, and click the Bulk Edit link. Then type in the environment variables that you want to save.
I use something like:
ClientID:<client_Id>
ClientSecret:<client_secret>
Resource:https://<axurl>
Tenant:https://login.windows.net/<tenant>
You don't have to use the Bulk Edit and just use the table to input the same information, however usually it is faster to gather and format the information in the Bulk Edit mode.

If you don't have a client secret key but have a username and password combination for the client ID, then you can use something like this:
ClientID:<client_Id>
Resource:https://<axurl>
Tenant:https://login.windows.net/<tenant>
username:<username>
password:<password>
Replace those in bold with the valid values and click Add to actually save the new environment.

Get the access token

The next step would be to get the access token to the D365O. There are more than one way to do this, such as using the Postman Get New Access Token function, however I haven't been able to make this work that way. It might be that you'll need to register a new application in the Azure portal and use the specific callback url. If you want to do it that way, please see this post that might be helpful https://community.dynamics.com/ax/b/dynamicsnavax/archive/2017/05/23/dynamics-365-for-operation-web-service-calls-with-postman

I'm going to do the old way so that I don't have to do any special thing in the Azure portal. In the main section, make sure you can see a new tab, otherwise click the plus sign.


See the above screenshot, and make the changes on the highlighted parts. Please note that anything in the double curly brackets is referring to a Postman variable. In this case, they are all referring to the variables that we saved in the environment. 
Please also note that we use "No auth" in the authorization tab.
You can click Send button now, and that will get you the access token, however to make things easier for the next request, go to the Tests tab, and enter these codes:
var json = JSON.parse(responseBody);
postman.setEnvironmentVariable("bearerToken", json.access_token);
This pretty much instructs Postman to get the access_token value from the result and store it as an environment variable called bearerToken.

Click the Send button, and make sure that it returns the result with status HTTP 200. After that click the eye icon (the one before the gear icon), and see if it's added the bearerToken there.

You might want to save this request, and add it into a new collection.

Now that we have the access token, let's do some calls to the LedgerJournalHeaders service, similar to what we did in Fiddler before.

Get ledger journal headers

Create a new request, set the action to GET and enter this as the url: {{Resource}}/data/LedgerJournalHeaders
Then go to the Headers tab, and add a new entry with Authorization as the key, and set the value to Bearer {{bearerToken}}

Click the Send button and you'll get the result back. That's quite easy isn't it?
Anytime the token is expired, just open the get token service that you saved before, and run that again.

Insert a new ledger journal header

Create a new request, set the action to POST, and enter this as the url: {{Resource}}/data/LedgerJournalHeaders
Then go to the Headers tab, and add a new entry with Authorization as the key, and set the value to Bearer {{bearerToken}}
Next go to the Body tab and select raw, change the Text selection to JSON (application/json), and enter this:
{
"dataAreaId":"USMF",
"JournalName":"GenJrn",
"Description":"Test journal"
}
Click the Send button and you'll get the result back.

Update a ledger journal header

Create a new request, set the action to PATCH, and enter this as the url: {{Resource}}/data/LedgerJournalHeaders(JournalBatchNumber='<journalNumber>',dataAreaId='<dataAreaId>')
Replace that journalNumber and dataAreaId with valid values.

Then go to the Headers tab, and add a new entry with Authorization as the key, and set the value to Bearer {{bearerToken}}
Next go to the Body tab and select raw, change the Text selection to JSON (application/json), and enter this:
{
"dataAreaId":"USMF",
"Description":"Edited journal description"
}
Click the Send button and when you'll get status HTTP 204, then that means the request was successful.

Please note that D365O by default will get the values from the integration user's default company, regardless of the dataAreaId that you're actually specifying on the call. If you need to access a record on a different company, then you'll need to add ?cross-company=true


Delete a ledger journal header

Create a new request, set the action to DELETE, and enter this as the url: {{Resource}}/data/LedgerJournalHeaders(JournalBatchNumber='<journalNumber>',dataAreaId='<dataAreaId>')
Replace that journalNumber and dataAreaId with valid values.

Then go to the Headers tab, and add a new entry with Authorization as the key, and set the value to Bearer {{bearerToken}}
Click the Send button and when you'll get status HTTP 204, then that means the request was successful.


1 comment: