1. To-Increase Dynamics 365 for Finance & Operations
  2. Connectivity studio
  3. Activities

Set up web service action - Outbound
Application task

You can use an outbound web service action to request data from an external application and to process the response in D365 FO, via an external web service.

For each outbound web service action, you can define these messages:
Message Description
Request message The request message provides the web service with data from D365 FO.
Response message The response message processes the response from the web service in D365 FO.
Error message The error message processes the error from the web service in D365 FO.

 

Note: Only D365 FO can trigger an outbound web service action. When triggered, the outbound web service action automatically runs the defined messages.

Attributes

You can use attributes to add extra information to the web service URL or HTTP request.
The attribute type indicates how the attribute value is defined. You can use these types:
Attribute type Description
Value The attribute is a fixed value. Enter the fixed value in the Value or Custom field.
Document field The attribute value is derived from a field of the source document of the request message. Fill in the Document field field.
Record field

The attribute value is derived from a field of a selected record. Usually, this type is used to get records. Only use this type if you start the web service with a menu item from a specific page. Fill in these fields: Record table and Record field.

Example: You start the web service from the Sales orders page. You can use the attribute to get all sales orders for the customer of the selected sales order. In this case, you fill in the CustTable and ID.
Custom You can enter a static method that defines the range. The static method is applied to the source document of the request message.
Secret You can enter a secret reference to be used as attribute. The secret reference refers to a centrally stored secret which makes updating secrets easier. So, the secret value is not visible on the Web service action page. You only see the secret reference. Fill in the Secret reference field.

 

The attribute styles define how the attribute is applied to the request. You can use these attribute styles:

Attribute style Description
Header Sends a custom header with an HTTP request. The attribute is added to the header of the HTTP request.
Query

Most common attribute type. It applies to the whole request. It is added to the URL after the question mark (?) after the resource name.

Example: https://myserver.com/resource?attr1=Your Value&attr2=Your Value
Template

Parameterizes the resource path, adding a placeholder for a variable value.

Example: https://myserver.com/resource/{attr3}
Matrix

Applies to a specific resource path element. The attribute is added to the URL, between the resource or the template attribute and the QUERY attributes. The attribute is separated from the resource or the template attribute with a semicolon (;).

Example: https://myserver.com/resource/{attr3};;attr4=Your Value?attr1=Your Value
Plain Excludes the attribute from the HTTP request. For example, for testing purposes.
Body key pair Usually, for an outbound web service, the body contains the content. In some cases, for example for Dataverse, the body contains more data than only the content. The data is split in a list of, so called, key pairs. In this case, the content is stored in a key pair, instead of in the body. For each of the key pairs to be added to the request body, add an attribute to the outbound web service action.
To use key pairs in your body, use these settings:
  • Content type: application/x-www-form-urlencoded
  • Attribute type: Value
  • Attribute style: Body key pair
  • Attribute value: [Body]; only for the attribute that contains the request content.
Note: You only can apply this setup if the target document of the request message is of type JSON.


Standard procedure

1. Click Connectivity studio Integration Design.
2. Click the Web service tab.
3. Click New.
4. In the Web service action field, type the unique name of the web service action.
5. In the Project field, enter or select a value.
6. Define the goal of the outbound web service:
- Post: Create records in the external application.
- Put: Update records in the external application.
- Get: Get data from the external application.
- Patch: Update only a part of records in the external application.
- Delete: Delete records from the external application.
- Post or put: Create or update records in the external application.
  In the HTTP action field, select an option.
 

Note: If the HTTP action is 'Post or put', you must set up an attribute of type Document field or Record field with the Key check box selected. This key attribute is used to determine if, in the external application, the record already exists and must be updated, or if the record does not yet exist and must be created.
7. Sub-task: Set web service properties.
  7.1 Expand the Properties section.
  7.2 Define the direction of the web service action.
  In the Acts as field, select 'Outbound'.
  7.3 Define the access type of the web service:
- Basic: You can use this option if the web service access type is SOAP (Simple Object Access Protocol).
- REST: Use this option is the web service access type is REST (Representational State Transfer).
  In the Web service type field, select an option.
  7.4 Define the content type of the web service. For example, application/json, text/xml, or text/plain. The content type is added to the web service header.
  In the Content type field, type a value.
  7.5 Sometimes, a sent web request cannot be received by the web service. You can indicate the number of times to retry getting a web request received by the web service.
A retry is only done in case of one of these errors:
- 429: A response status code that indicates that the web service has surpassed its rate limit, or number of requests they can receive in a given period of time.
- 503: A response status code that indicates that the web service is temporarily unavailable.
  In the Maximum retries field, enter a number.
  7.6 Sometimes, a sent web request cannot be received by the web service. If you have defined the number of times to retry getting a web request received by the web service, also define the number of seconds between the retries.
  In the Delay operation with field, enter a number.
  7.7 Define the request message for the web service action.
The goal of the request message depends on the HTTP action of the web service action. In general, the request message provides the web service with data from D365 FO.
  In the Request message field, enter or select a value.
 

Note: If the HTTP action is Get, the request message is optional.
  7.8 Define the response message for the web service action.
The goal of the response message depends on the HTTP action of the web service action. In general, the response message processes the response from the web service in D365 FO.
  In the Response message field, enter or select a value.
 

Note: Only if the HTTP action is Get, it is mandatory to define a response message.
  7.9 You can define an error message for the web service action.
The error message processes errors that you receive from the web service in D365 FO.
  In the Error message field, enter or select a value.
  7.10 Enter the name of the applicable resource in the external web service.
The resource name is added to the URL for this web service action.
  In the Resource field, type a value.
 

Note:
- Click Save to see the result in the field below.
- The base URL is defined in the web service application setup of the related project.
8. Sub-task: Set up attributes.
  8.1 You can use attributes to add extra information to the web service URL or HTTP request.
  Expand the Attributes section.
  8.2 Click New.
  8.3 You can enter the sequence number of the attribute in the list of attributes. This can be important if the Web service type is REST.
  In the Line number field, enter a number.
 

Note: You can also change the sequence with the Move up and Move down buttons.
  8.4 Enter a meaningful name for the attribute.
  In the Name field, type a value.
  8.5 Use the attribute type to indicate how the attribute value is defined. You can use these types:
- Value: The attribute is a fixed value.
- Document field: The attribute value is derived from a field of the source document of the request message.
- Record field: The attribute value is derived from a field of a selected record.
- Custom: You can enter a static method that defines the range.
- Secret: You can enter a secret reference to be used as attribute.
  In the Type field, select an option.
 

Note: For more information on the attribute types, refer to the topic introduction.
  8.6 If the type is:
- Value, enter the attribute value.
- Custom, enter a static method to define the range. For example, you can use the SysQueryRangeUtil class to apply advanced date queries. Other examples are: 'curExt()' (gets the current company), 'strFmt("%1..%2", prevMth(today()), today())' (gets the orders from the last month), and 'DateTimeUtil::utcNow()' (filters on the current date/time).
  In the Value or Custom field, type a value.
 

Note: This field is only available if the type is Value or Custom.
  8.7 Enter the field of the source document of the request message from which attribute value is derived.
  In the Document field field, enter or select a value.
 

Note: This field is only available if the type is Document field.
  8.8 Enter the table from which you want to select the field from which the attribute value is derived.
  In the Record table field, enter or select a value.
 

Note: This field is only available if the type is Record field.
  8.9 Enter the field from which the attribute value is derived.
  In the Record field field, enter or select a value.
 

Note: This field is only available if the type is Record field.
  8.10 Enter a secret reference to be used as attribute. The secret reference refers to a centrally stored secret which makes updating secrets easier.
  In the Secret reference field, enter or select a value.
 

Note: This field is only available if the type is Secret.
  8.11 You can use attributes to set varying parts of the HTTP request.
- Header: Sends a custom header with an HTTP request. The attribute is added to the header of the HTTP request.
- Query: Most common attribute type. It applies to the whole request.
- Template: Parameterizes the resource path, adding a placeholder for a variable value.
- Matrix: Applies to a specific resource path element. The attribute is added to the URL, between the resource or the template attribute and the QUERY attributes.
- Plain: Excludes the attribute from the HTTP request.
- Body key pair: The attribute is added as a key pair to the request body.
  In the Style field, select an option.
 

Note:
- Usually, the external web service administrator can provide you with the required attributes and attribute styles.
- For more information on the attribute styles, refer to the topic introduction.
  8.12 If the HTTP action is 'Post or put', you must set up an attribute of type Document field or Record field with the Key check box selected. This key attribute is used to determine if, in the external application, the record already exists and must be updated, or if the record does not yet exist and must be created.
  Select the Key check box.
 

Note: This field is only available if the HTTP action is 'Post or put', and if the type is Document field or Record field.
  8.13 If the attribute type is Document field or Record field, you can indicate if the value of the defined document field or record field is linked to an external ID or revision number. So, for the document field or record field value, an external ID must exist in the application of the source connector of the request message.
  In the External ID field, select an option.
 

Note: If the attribute type is Document field or Record field, and the External ID field is not available, click Save to make it available.
  8.14 Most attributes result in a change of the syntax of the resource URL. However, sometimes a different syntax is required for an attribute.
You can define the custom attribute syntax in this field. For the:
- Attribute name use %1.
- Attribute value use %2.
Example:
A standard template attribute syntax is ../{'attribute name'}. When run, the variable {'attribute name'} is replaced by the attribute value. This results in, for example: ../1234.
For example, for OData, when requesting customer information, another syntax is required: ../account({attribute value}).
In the Custom URL part field enter /account(%2). This results in, for example: ../account(1234).
  In the Custom Url part field, type a value.
9. Sub-task: Set custom handler, class, and action menu item.
  9.1 Expand the Custom section.
  9.2 For an outbound web service action, the standard handler classes are:
- BisWsClientHandler: Runs the outbound web service action. For the request message, the target connector must be of type Windows folder. For the Response message and error message, the source connector must be of type Windows folder.
- BisWsClientHandlerV3: Runs the outbound web service action, using streaming. For the request message, the target connector must be of type Web service. For the Response message and error message, the source connector must be of type Web service.
You can use a customized handler class. To do so, extend a standard handler class.
  In the Handler field, enter or select a value.
  9.3 To actually run the web service HTTP request, a separate class is used. If your HTTP request works different compared to the standard HTTP request, you can create your own HTTP class. Make sure, it implements the same interface with the same methods as exist in the HttpRequest class.
The standard client HTTP classes are:
- BisWsClientHttpFileRequest: Calls the external web service if files are used to exchange data. The result of the handler class is the input for the web service call. This class also handles the response from the web service. This response is the input for the handler class to process the response in D365 FO.
- BisWsClientHttpRequest: Calls the external web service if streaming used to exchange data. The result of the handler class is the input for the web service call. This class also handles the response from the web service. This response is the input for the handler class to process the response in D365 FO.
  In the Client Http class field, enter or select a value.
  9.4 You can use a custom action menu item to manually start an outbound web service action.
To make this work:
- Create the custom menu item. The action menu item must be of type class and must be linked to the 'BisWsCmdActionRunWebservice' class. To avoid best practice warnings, in the menu item setup, define the permissions for the roles who can use the action menu item. As the action menu item is not linked to a RunBase class, you cannot run it in batch.
- Add the action menu item to the form from where you want to start the web service action. For example, the Sales orders form to post a sales order.
- Enter the name of the action menu item for the desired web service action in the Action menu item name field. For example, a web service action to post a sales order.
As a result, for a selected record, you can manually run the web service action from the form to which you added the action menu item.
  In the Action menu item name field, enter or select a value.
 

Note:
Example: On the Sales orders form, you can select a record and click the action menu item button. This starts a web service action to post a sales order. The web service action is processed, and the selected sales order is posted.
10. Sub-task: Set history settings.
  10.1 Expand the History section.
  10.2 You can create a report in Microsoft Excel format that contains the errors that occurred during a web service action run. You can, for example, use this to inform the sender of data on the errors. The report is created when the web service action run is finished. The report is stored in the folder as defined in the Business integration parameters, in the History report path field.
  Select Yes in the Create history report field.
11. In the Secret reference field, enter or select a value.
12. Close the page.
Related to Notes

Set up outbound web services

 		 

See also

Provide feedback