Microsoft Dynamics BC Documentation
About: Webservice Event
In Business Integration Solutions, the Webservice Event triggers a pipeline when an external party calls the related Webservice. The Webservice Event uses the standard Microsoft Dynamics BC web service functionalities.
Usage
Use the Webservice Event to import data into Microsoft Dynamics BC and to export data from Microsoft Dynamics BC.
When you import data into Microsoft Dynamics BC, an external party makes a call to Microsoft Dynamics BC Webservice. The Webservice is linked to the BIS Webservice Event codeunit which triggers the pipeline. Other pipeline activities handle the rest of the data import.
There are two commands for importing the data from the external party into BC:
- Write Document: When you use this command, the data is exported to BC and added to the Message Queue. The BIS Pipeline waits for the Job Queue to finalize the import. This is an asynchronous process.
- Write Document With Response: When you use this command, the data is exported to BC and immediately processed through the complete pipeline in a synchronous process.
The Webservice Event can also be used for exporting data from Microsoft Dynamics BC to an external system. In this case, an external party calls BC Webservice, which is linked to a BIS Webservice Event and triggers the BIS pipeline. Based on an internal document, relevant data will be exported by the BIS pipeline.
Reading Data
Reading data will export data from Business Central when an external request has been made.
[WS-request]➡️[ReadDocument] ➡️[WebServiceId]➡️[String]
Writing Data
Writing data will receive a request and based on the document, will import data in Business Central.
[WS request]➡️[WS event]➡️[WriteDocument]➡️[WebServiceId,documentString]
Read and write
[WS request]➡️[WS event]➡️[WriteDocument]➡️[WebServiceId,documentString] ➡️ [WebServiceId,documentString]➡️[documentString]
Concept
The Webservice Event uses standard Microsoft Dynamics BC Webservice functionalities as much as possible. Please refer to the online help to know more about Working with Web Services.
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. Based on the pipeline configuration an export or an import of data takes place.
In an import pipeline, the Webservice Event will be followed by a Mapper and a Record Generator and in case of an export pipeline, the Webservice Event will most likely be followed up by an XML Generator, a Mapper and a Writer endpoint.
[Microsoft Dynamics 365 Business Central] ➡️ [Web Service Event] ➡️ [<Activities>] ➡️ [<End Point>]
Setup
The web service event setup page contains the following tabs
| Tab | Field | Description |
|---|---|---|
| General | Web Service ID | Unique web service identifier accross all connections |
| Direction | Indicates the direction of the web service (Read, Write or Read and Write) | |
| Job Queue Category Code | Job queue category code used when writting data to BC without expecting a reply back | |
| Continue on Error | Valid only when direction is "Read and Write". 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 |
| Filters | Filters applied on the dataset on which the web service call will be based |
Available Actions
| Direction | Function Name | SOAP Arguments | oData Arguments |
|---|---|---|---|
| Read | |||
| Write | WriteDocumentWithResponse | ||
| WriteDocument | WebServiceId,documentString | webServiceId,documentString |
Postman examples
Below you will find two examples, one for SOAP and one for ODATA V4, based on the same connection. The connection will start with an web service event, continue to an xml generator and end with an xml to json tralsator. All the pipeline elements, are based on a item document structure, filtering items from number 1000 to number 1110.
[Web Service Event] ➡️ [Xml Generator] ➡️ [Xml to Json Tralsnator]
The authorization used in both cases is "Basic Auth" based on username and password, because the examples are build within a BC based container. Adjust the authorization needed for your case.
SOAP Example
Get Request
When calling an web service event using SOAP, you will have to build a SOAP envelope for the method you are trying to reach. In our case, we are trying to call method "ReadDocument", which takes one parameter "webServiceId".
- Headers
- Body
- Result
Web service event soap request is Case sensitive , if the method or url is not followed case sensitive then the response will be null for more info refer below screen.
Post Request
To post or import data to business central call method "WriteDocument" , which takes parameters "webServiceId" and "documentString".
- Headers
- Body
- Result
ODATAV4 Example
When calling an web service event using ODATA, you will not need to send the web service id as a method parameter, but rather as a scope record in the calling URL. The calling body will have to include the required parameters in a json format. The example below is trying to reach method "ReadDocumentWithFilter", which will export a set of records from BC, based on a given filter.
- Headers
- Body
- Result
