List of Services

The following table lists all the service endpoints that were available in Microsoft Dynamics AX 2012 and the new service endpoints that have been introduced in Dynamics 365 for Operations. One thing to note is that the SOAP-based services in Dynamics 365 for Operations remain the same as they were in Dynamics AX 2012.

Service endpoint	Dynamics 365 for Operations
Document Services (AXDs)	Data Entities
SOAP-based Metadata Service	REST metadata service
SOAP-based Query Service	OData 4.0
OData Query Service	OData 4.0
SOAP-based Custom Service	Yes
JSON-based Custom Service	Yes (New)
OData Service	Yes (New)
REST Metadata Service	Yes (New)

Key Changes in Services

• All the service groups under the AOT\Service group node are automatically deployed.
• All services that must be deployed must be part of a service group.

The SOAP endpoint is at https://<host_uri>/soap/Services/<service_group_name>.

Code Example: https://usnconeboxax1aos.cloud.onebox.dynamics.com/soap/services/UserSessionService?wsdl

The following documentation is from the Dynamics AX 2012 X++ Custom SOAP Services, and it will help you design and write services in Dynamics 365 for Operations:

• Using Custom Services [AX 2012] (TechNet)
• Walkthrough: Exposing an X++ Class as a Data Contract [AX 2012] (TechNet)

More Code Examples – We have some sample code examples for consuming custom services at https://github.com/Microsoft/Dynamics-AX-Integration/tree/master/ServiceSamples/SoapConsoleApplication

JSON-based Custom Service

This Dynamics 365 for Operations feature enables X++ classes to be consumed as JSON services. In other words, the return data set is in JSON format. JSON, which stands for JavaScript Object Notation, is a compact, lightweight format that is commonly used communicate data between the client and the server.

In Dynamics 365 for Operations, after the developer has written the services under service groups, the service groups are always deployed on two endpoints:

• SOAP endpoint (mentioned in the previous section)
• JSON endpoint

The JSON Endpoint is at: https://<host_uri>/api/Services/<service_group_name>/<service_group_service_name>/<operation_name>.

Code Example: https://usnconeboxax1aos.cloud.onebox.dynamics.com/en/api/services/UserSessionService/AifUserSessionService/GetUserSessionInfo

You can find a Microsoft Office Mix presentation about this topic here.

More Code Examples – We have some sample code examples for consuming Json services at https://github.com/Microsoft/Dynamics-AX-Integration/tree/master/ServiceSamples/JsonConsoleApplication

OData Services

Dynamics 365 for Operations has introduced an OData REST endpoint. This endpoint exposes all the data entities that are marked as IsPublic in the Application Object Tree (AOT). It supports complete CRUD (create, retrieve, update, and delete) functionality that users can use to insert and retrieve data from the system.

Detailed labs for this feature are on the LCS methodology. You can find an Office Mix presentation about OData Services here.

Supported Features from the OData Specification

The following table lists the high-level features that are enabled in Dynamics 365 for Operations OData, per the OData specification.

OData v4 feature	Details	OData v4 specification reference
CRUD	HTTP Verb support for POST, PATCH, PUT, and DELETE
Query options	$filter $count $orderby $skip $top $expand $select
Server-driven paging	The maximum page size that is served is 1,000.
Actions that are bound to entities		http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398355
Actions that are bound to entity sets
Built-in operators for $filter	Equals Not Equals Greater Than Greater Than or Equal Less Than Less Than or Equal And Or Not Addition Subtraction Multiplication Division	http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part2-url-conventions/odata-v4.0-errata02-os-part2-url-conventions-complete.html#_Toc406398096
Contains option in $filter	Implemented as a wildcard character Example: http://host/service/EntitySet?$filter=StringField eq ‘*retail*’
Batch requests		http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398359
Metadata annotations	/data/$metadata has out-of-box annotations.
EnumType support	Example of how EnumType is supported in $metadata:

Code Examples – We have some sample code examples for consuming Odata services at https://github.com/Microsoft/Dynamics-AX-Integration/tree/master/ServiceSamples/ODataConsoleApplication

Cross-company Behavior

By default, OData returns only data that belongs to the user’s default company. To see data from outside the user’s default company, specify the ?cross-company=true query option. This option will return data from all companies that the user has access to.

Example: http://[baseURI]/data/FleetCustomers?cross-company=true

To filter by a particular company that isn’t your default company, use the following syntax:
http://[baseURI]/data/FleetCustomers?$filter=dataAreaId eq ‘usrt’&cross-company=true

Validate Methods

The following table summarizes the validate methods that the OData stack calls implicitly on the corresponding data entity.

OData	Methods (listed in the order in which they are called)
Create	Clear() Initvalue() PropertyInfo.SetValue() for all specified fields in the request Validatefield() Defaultrow Validatewrite() Write()
Update	Forupdate() Reread() Clear() Initvalue() PropertyInfo.SetValue() for all specified fields in the request Validatefield() Defaultrow() Validatewrite() Write()
Delete	Forupdate() Reread() checkRestrictedDeleteActions() Validatedelete() Delete()

REST Metadata Service

This is a new service endpoint that has been introduced in Dynamics 365 for Operations. This is a read-only service. In other words, users can make only GET requests. The main purpose of this endpoint is to provide metadata information for elements. It is an OData implementation.

This endpoint is hosted at http://[baseURI]/Metadata.

Currently, this endpoint provides metadata for the following elements:

• Labels – This gets labels from the system. They have a dual pair key, language, and ID, so that you can retrieve the value of the label.
  Example: https://[baseURI]/metadata/Labels(Id=’@SVC_ODataLabelFile:Label1′,Language=’en-us’)
• Data entities – This returns a JSON-formatted list of all the data entities in the system.
  Example: https://[baseURI]/Metadata/DataEntities

We will support more sets of metadata as new scenarios require it.

Authentication

OData Services, JSON-based Custom Service, and REST Metadata Service support standard OAuth 2.0 authentication. You can read more about OAuth 2.0 here.

Microsoft currently supports Authorization Code Grant flow.

Two kinds of application are supported in Microsoft Azure Active Directory (AAD):

• Native client application – This flow uses a user name and password for authentication and authorization.
• Web application (Confidential client) – A confidential client is an application that can keep a client password confidential to the world. The authorization server assigned this client password to the client application. This will be supported post-RTW.

OAuth – Authorization Code Grant Flow

Register a Native Application with AAD

Before any clients can communicate with Dynamics 365 for Operations services, they must be registered in AAD.

These steps will help you register an application with AAD.

Note: These steps don’t have to be completed by all the people in your organization. Only one Azure admin user can add the application and share the client ID with the developers.

Prerequisite: You must have an Azure subscription and admin access to Active Directory.

1. In a web browser, go to http://manage.windowsazure.com/.
2. Enter the user name and password of the user who has access to the Azure subscription. After the credentials are authenticated, Azure Portal opens.
3. In Azure Portal, in the left navigation pane, click Active Directory.
   1. 
4. In the grid, select the Active Directory instance that is being used for Dynamics AX.
5. On the top toolbar, click Applications.
   1. 
6. In the bottom pane, click Add. The Add application wizard starts.
7. Add a new native client application. Enter information in the wizard as shown in the following screen shots.
   1. 
   2. 
   3. 
8. Click the check mark button to complete the wizard. After you complete the wizard, the new application page opens.
   1. 
9. On the top toolbar, click Configure.
10. Scroll down until you see the Permissions to other applications section. Click Add Application in this section.
    1. 
11. Select Microsoft Dynamics ERP in the list
12. Click the Complete check button in the right corner of the page.
13. In the Delegate Permissions list, select all the check boxes. Note: We are working on cleaning up this list.
    1. 
14. Make a note of the following two pieces of information:
    1. Client ID – As you scroll toward the top of this page, you will see Client ID displayed.
    2. Redirect URI

After you have these two pieces of information, you’re ready to write your client code.

Integration and Integration Types

Microsoft’s Enterprise Integration Vision

Microsoft BizTalk

• Logic App adapter – 2016 support for Logic App
• Call Operations REST/OData
  • Send pipeline with custom behavior to implement AAD authentication
• Keep using as on premise middleware
• Can integrate with Operations
  • Enqueue/Dequeue/JobStatus/Ack
  • OData/Rest

Azure Service Bus

• Asynchronous messaging cloud platform
• Decoupled communication
• Reliability
• Load balance\buffering

Microsoft QuartzAX

A self-hosted solution that can import/export files to/from Operations

Pros

• Easy to configure
• Easy to use
• Free

Cons

• Manageability
• Scalability
• Error handling and real time alerts
• Dual scheduling

Microsoft Logic Apps

• IPaaS
• Cloud and on premise connectors
• Light up other Azure services
• Operations connector available
  • CRUD
  • Execute action
• Generic HTTP connector
  • Enqueue/Dequeue/JobStatus/Ack
• Enterprise Integration Pack – B2B workflow
• Preferred way to interact with recurring job

Pros

• Scalability
• Manageability
• Guaranteed delivery
• Error handling
• Real time alerts

Cons

• Not free
• Only available in the cloud

Microsoft Flow

• No Azure subscription needed
• Citizen integrators
• Flow is built on top of Logic Apps
• They have the same workflow designer
• Connectors that work in one can also work in the other

Microsoft Flow vs. Logic Apps