Microsoft Dynamics BC Documentation

About: ASYNCWEBSERVICE

In Business Integration Solutions, the Async Web Service is similar to the Web Service Event but instead of acting as a trigger at the start of the process, it is put in the middle of a process. When the next activity in pipeline execution is the Async Web Service activity, the process status is set to pending and is paused, waiting for the correct incoming request to continue the process.

Usage

Use the Async Web Service to wait for an http request during the execution of a process (connection / publication / etc..).

The Async Web Service expects an id in the body of the request recieved by the external party. This id is used to identify that the incoming request should trigger the particular activity in the particular process.

The endpoints that can be used with Async Web Service are the following:

Endpoint	Description
WriteDocumentWithResponseById	Writes input data to the message body and triggers the pipeline to continue. When the pipeline execution stops, the message body is returned in the response.
WriteDocumentById	Writes input data to the message body and triggers the pipeline to continue. No content is returned in the response.
ReadDocumentById	Triggers the pipeline to continue with a specific document specified in the configuration of the activity. The message body is returned when the pipeline stops executing.
ReadDocumentWithFilter	Triggers the pipeline to continue with a specific document specified in the configuration of the activity, together with the inputted filter. The message body is returned when the pipeline stops executing.

Concept

Like the Web Service Event, the Async Web Service uses standard Microsoft Dynamics BC Webservice functionalities as much as possible.

An external party calls Microsoft Dynamics BC Webservice. The call goes to the BIS Webservice Event (codeunit) as it is provided with a link to the Microsoft Dynamics BC Webservice. The pipeline is triggered if the id specified in the body of the request matches the expected id in the configuration of the activity.

Setup

The Async Web Service activity requires a header mapper activity to be added in a previous step. The header mapper activity is needed to specify the expected id to be received to trigger the process to continue. In the example below, the expected id is the customer number in the message body at that time. This would mean that the request needed to continue the process needs to have the customer number in the id field in the body.

Header Mapper Configuration

Request (Read example)

POST http://<BCRootUrl>/ODataV4/Company('CRONUS%20International%20Ltd.')/BISWebServiceListener('<Configured Web Service ID>')/NAV.ReadDocumentById

{
    "id": "10000" // Example Customer No.
}

The Async Web Service setup page contains the following tabs

Tab	Field	Description	More Info
General	Web Service ID	Unique web service identifier accross all connections. This is used as part of the url as shown above.	Web Service Event
	Direction	Indicates the direction of the web service (Read, Write or Read and Write)
	Continue on Error	If this is true and the web service call returns an error, the pipeline doesn't stop
SOAPEndpoints		It displays all the available SOAP endpoints for the web service event
ODATAEndpoints		It displays all the available ODATA V4 endpoints for the web service event
Document	Document No.	Internal document on which the web service call will be based. This is only for Read directions.
Filters		Filters applied on the dataset on which the web service call will be based. This is only for Read directions.

Additional Request examples

The examples below will show the request url and body for other endpoints allowed for the Async Web Service.

Request for Read Document With Filter

POST http://<BCRootUrl>/ODataV4/Company('CRONUS%20International%20Ltd.')/BISWebServiceListener('<Configured Web Service ID>')/NAV.ReadDocumentWithFilterById

{
    "id": "IDExpectedByProcess",
    "tableFilterString": "Item: No. = 1000..1001" //Example filter for item table. This would work with an internal document pointing to the Item table.
}

Request for Write Document

POST http://<BCRootUrl>/ODataV4/Company('CRONUS%20International%20Ltd.')/BISWebServiceListener('<Configured Web Service ID>')/NAV.WriteDocumentById

{
    "id": "1000", //Example Item No.
    "documentString": "<document><Item><ItemNo>ITEMFROMASYNC</ItemNo><ItemDescription>Item from async</ItemDescription></Item></document>" //Example Item data.
}