Business Integration Solutions Documentation

WebService Get Request

Getting Started

This example will call a Business Central Webservice, and store the response as message to be passed on in the pipeline. To call the webservice we require some prerequisites.

  • The URL for the webservice
  • User credentials to access the service
  • Postman to create the authorization string

Create a new connection

  • Create a new connection, give it a name, and in the elements add the WEBSERVICEENDPOINT element.
  • Press Edit on the subpage ribbon to open the element

Get the URL

Open your Business Central Webclient by navigating to your environment with your browser. Search for the Web Services page and open it navigate to the record of Page 42 Sales Order. Copy the OData V4 URL:

http://bcsaas203-default:7048/BC/ODataV4/Company('CRONUS%20International%20Ltd.')/SalesOrder?tenant=BCSaaS203-default

Add Filters

Since Business Central Webservices use the querystring functionality to filter the dataset retrieved from the service. We'll be adding some set filters as an example We'll add filters to the 'Sell-To Customer' and 'Status' fields

The filter is stored within the $filter key

$filter=Sell_to_Customer_No eq '30000' and Status eq 'Released' We'll add this to the webservice URL so the url looks like this:

http://bcsaas203-default:7048/BC/ODataV4/Company('CRONUS%20International%20Ltd.')/SalesOrder?tenant=BCSaaS203-default&$filter=Sell_to_Customer_No%20eq%20%2730000%27%20and%20Status%20eq%20%27Released%27

The environment we're using this example on is a Sandbox container named BCSaaS203 with the tenant as default

We'll be using this URL in the example

Setting up authorization

There are multiple ways to authorize a web request, authorization is most of the times added to the headers of a web request, although there are scenarios where the authorization is added to the querystring. Common types are the following

  • No Authorization
  • API Key
  • Basic Auth
  • Bearer Token
  • OAuth 1.0
  • OAuth 2.0

Business Central Webservices supports Basic and OAuth 2.0 authorzations, with Basic authentication being deprecated in SaaS environments. We'll use for this example Basic Auth with a webservice key.

  1. Navigate to the Users and select the user you would like to use.
  2. Enable the Webservice key for that user
    • To copy the webservice, you must be logged in as that user in Business Central
  3. Copy the webservice key to a temporary location, we'll be using Postman to create the authorization header Webservice User Card
  4. Open Postman and create a new web request
    • If there is a request to create an account, at the bottom of the create account screen, there is a skip and go to app option
  5. In Postman Create new (ctrl+N) and select a new http request
  6. In the untitled Request, navigate to the Authorization Tab, select Basic Auth in the dropdown and enter your username and Webservice Key in the corresponding fields Postman Authorization Tab
  7. Switch to the Headers tab and copy the value of the Authorization Key Postman Headers Tab
    • In case you don't see the Authorization Key, press the x hidden button Postman Hidden Headers
  8. Go back to the Connection, and add the key and value to the Headers Webservice Endpoint Setup page on Headers Tab

Run a Test Call

To test our GET request, press the Test Call button in the ribbon of the Webservice Setup page. Press Call webservice on the new page There might be a pop-up requesting to allow TI-BIS to submit requests Pop-up Allowing http requests Webservice Test call Result The Result of the Test Call is in 2 parts

  • The Status code of the call (200-OK)
  • The body of the response
Status Code: 200 (OK)
{"@odata.context":"http://bcsaas203-default:7048/BC/ODataV4/$metadata#Company('CRONUS%20International%20Ltd.')/SalesOrder","value":[{"@odata.etag":"W/
"JzE5OzgzNzA2OTE5MzE4NDU0MDQxNDcxOzAwOyc=
"","Document_Type":"Order","No":"101005","Sell_to_Customer_No":"30000","Sell_to_Customer_Name":"John Haddock Insurance Co.","Quote_No":"","Posting_Description":"Order 101005","Sell_to_Address":"10 High Tower Green","Sell_to_Address_2":"","Sell_to_City":"Manchester","Sell_to_County":"","Sell_to_Post_Code":"MO2 4RT","Sell_to_Country_Region_Code":"GB","Sell_to_Contact_No":"CT000012","Sell_to_Phone_No":"","SellToMobilePhoneNo":"","Sell_to_E_Mail":"","Sell_to_Contact":"Miss Patricia Doyle","No_of_Archived_Versions":0,"Document_Date":"2024-01-11","Posting_Date":"2024-01-26","Order_Date":"2024-01-11","Due_Date":"2024-01-31","Requested_Delivery_Date":"0001-01-01","Promised_Delivery_Date":"0001-01-01","External_Document_No":"","Your_Reference":"","ShpfyOrderNo":"","ShpfyShopify_Risk_Level":" ","Salesperson_Code":"JO","Campaign_No":"","Opportunity_No":"","Responsibility_Center":"","Assigned_User_ID":"","Job_Queue_Status":" ","Status":"Released","WorkDescription":"","Currency_Code":"","Company_Bank_Account_Code":"","Prices_Including_VAT":false,"VAT_Bus_Posting_Group":"DOMESTIC","Customer_Posting_Group":"DOMESTIC","Payment_Terms_Code":"CM","Payment_Method_Code":"","EU_3_Party_Trade":false,"SelectedPayments":"No payment service is made available.","Shortcut_Dimension_1_Code":"SALES","Shortcut_Dimension_2_Code":"","Payment_Discount_Percent":0,"Pmt_Discount_Date":"2024-01-11","Journal_Templ_Name":"","Direct_Debit_Mandate_ID":"","ShippingOptions":"Default (Sell-to Address)","Ship_to_Code":"","Ship_to_Name":"John Haddock Insurance Co.","Ship_to_Address":"10 High Tower Green","Ship_to_Address_2":"","Ship_to_City":"Manchester","Ship_to_County":"","Ship_to_Post_Code":"MO2 4RT","Ship_to_Country_Region_Code":"GB","Ship_to_Contact":"Miss Patricia Doyle","Shipment_Method_Code":"EXW","Shipping_Agent_Code":"","Shipping_Agent_Service_Code":"","Package_Tracking_No":"","BillToOptions":"Default (Customer)","Bill_to_Name":"John Haddock Insurance Co.","Bill_to_Address":"10 High Tower Green","Bill_to_Address_2":"","Bill_to_City":"Manchester","Bill_to_County":"","Bill_to_Post_Code":"MO2 4RT","Bill_to_Country_Region_Code":"GB","Bill_to_Contact_No":"CT000012","Bill_to_Contact":"Miss Patricia Doyle","BillToContactPhoneNo":"","BillToContactMobilePhoneNo":"","BillToContactEmail":"miss.patricia.doyle@contoso.com","Location_Code":"","Shipment_Date":"2024-01-11","Shipping_Advice":"Partial","Outbound_Whse_Handling_Time":"","Shipping_Time":"","Late_Order_Shipping":false,"Combine_Shipments":true,"Transaction_Specification":"","Transaction_Type":"","Transport_Method":"","Exit_Point":"","Area":"","Language_Code":"ENG","Prepayment_Percent":0,"Compress_Prepayment":true,"Prepmt_Payment_Terms_Code":"CM","Prepayment_Due_Date":"2024-01-31","Prepmt_Payment_Discount_Percent":0,"Prepmt_Pmt_Discount_Date":"2024-01-11","Date_Filter":"''..09/20/22"},{"@odata.etag":"W/
"JzE5Ozg5MDIxNTI4Mzk3NTA1MjUxMjIxOzAwOyc=
"","Document_Type":"Order","No":"104008","Sell_to_Customer_No":"30000","Sell_to_Customer_Name":"John Haddock Insurance Co.","Quote_No":"","Posting_Description":"Order 104008","Sell_to_Address":"10 High Tower Green","Sell_to_Address_2":"","Sell_to_City":"Manchester","Sell_to_County":"","Sell_to_Post_Code":"MO2 4RT","Sell_to_Country_Region_Code":"GB","Sell_to_Contact_No":"CT000012","Sell_to_Phone_No":"","SellToMobilePhoneNo":"","Sell_to_E_Mail":"","Sell_to_Contact":"Miss Patricia Doyle","No_of_Archived_Versions":0,"Document_Date":"2024-01-17","Posting_Date":"2024-01-17","Order_Date":"2024-01-17","Due_Date":"2024-01-31","Requested_Delivery_Date":"0001-01-01","Promised_Delivery_Date":"0001-01-01","External_Document_No":"","Your_Reference":"","ShpfyOrderNo":"","ShpfyShopify_Risk_Level":" ","Salesperson_Code":"JO","Campaign_No":"","Opportunity_No":"","Responsibility_Center":"","Assigned_User_ID":"","Job_Queue_Status":" ","Status":"Released","WorkDescription":"","Currency_Code":"","Company_Bank_Account_Code":"","Prices_Including_VAT":false,"VAT_Bus_Posting_Group":"DOMESTIC","Customer_Posting_Group":"DOMESTIC","Payment_Terms_Code":"CM","Payment_Method_Code":"","EU_3_Party_Trade":false,"SelectedPayments":"No payment service is made available.","Shortcut_Dimension_1_Code":"SALES","Shortcut_Dimension_2_Code":"","Payment_Discount_Percent":0,"Pmt_Discount_Date":"2024-01-17","Journal_Templ_Name":"","Direct_Debit_Mandate_ID":"","ShippingOptions":"Default (Sell-to Address)","Ship_to_Code":"","Ship_to_Name":"John Haddock Insurance Co.","Ship_to_Address":"10 High Tower Green","Ship_to_Address_2":"","Ship_to_City":"Manchester","Ship_to_County":"","Ship_to_Post_Code":"MO2 4RT","Ship_to_Country_Region_Code":"GB","Ship_to_Contact":"Miss Patricia Doyle","Shipment_Method_Code":"EXW","Shipping_Agent_Code":"DHL","Shipping_Agent_Service_Code":"","Package_Tracking_No":"4515543524","BillToOptions":"Default (Customer)","Bill_to_Name":"John Haddock Insurance Co.","Bill_to_Address":"10 High Tower Green","Bill_to_Address_2":"","Bill_to_City":"Manchester","Bill_to_County":"","Bill_to_Post_Code":"MO2 4RT","Bill_to_Country_Region_Code":"GB","Bill_to_Contact_No":"CT000012","Bill_to_Contact":"Miss Patricia Doyle","BillToContactPhoneNo":"","BillToContactMobilePhoneNo":"","BillToContactEmail":"miss.patricia.doyle@contoso.com","Location_Code":"","Shipment_Date":"2024-01-17","Shipping_Advice":"Partial","Outbound_Whse_Handling_Time":"","Shipping_Time":"","Late_Order_Shipping":false,"Combine_Shipments":true,"Transaction_Specification":"","Transaction_Type":"","Transport_Method":"","Exit_Point":"","Area":"","Language_Code":"ENG","Prepayment_Percent":0,"Compress_Prepayment":true,"Prepmt_Payment_Terms_Code":"CM","Prepayment_Due_Date":"2024-01-31","Prepmt_Payment_Discount_Percent":0,"Prepmt_Pmt_Discount_Date":"2024-01-17","Date_Filter":"''..09/20/22"},{"@odata.etag":"W/
"JzE5OzY1Mjk2MTk3NDk3NDMwNDQ5OTkxOzAwOyc=
"","Document_Type":"Order","No":"104013","Sell_to_Customer_No":"30000","Sell_to_Customer_Name":"John Haddock Insurance Co.","Quote_No":"","Posting_Description":"Order 104013","Sell_to_Address":"10 High Tower Green","Sell_to_Address_2":"","Sell_to_City":"Manchester","Sell_to_County":"","Sell_to_Post_Code":"MO2 4RT","Sell_to_Country_Region_Code":"GB","Sell_to_Contact_No":"CT000012","Sell_to_Phone_No":"","SellToMobilePhoneNo":"","Sell_to_E_Mail":"","Sell_to_Contact":"Miss Patricia Doyle","No_of_Archived_Versions":0,"Document_Date":"2024-01-17","Posting_Date":"2024-01-17","Order_Date":"2024-01-17","Due_Date":"2024-01-31","Requested_Delivery_Date":"0001-01-01","Promised_Delivery_Date":"0001-01-01","External_Document_No":"","Your_Reference":"","ShpfyOrderNo":"","ShpfyShopify_Risk_Level":" ","Salesperson_Code":"JO","Campaign_No":"","Opportunity_No":"","Responsibility_Center":"","Assigned_User_ID":"","Job_Queue_Status":" ","Status":"Released","WorkDescription":"","Currency_Code":"","Company_Bank_Account_Code":"","Prices_Including_VAT":false,"VAT_Bus_Posting_Group":"DOMESTIC","Customer_Posting_Group":"DOMESTIC","Payment_Terms_Code":"CM","Payment_Method_Code":"","EU_3_Party_Trade":false,"SelectedPayments":"No payment service is made available.","Shortcut_Dimension_1_Code":"SALES","Shortcut_Dimension_2_Code":"","Payment_Discount_Percent":0,"Pmt_Discount_Date":"2024-01-17","Journal_Templ_Name":"","Direct_Debit_Mandate_ID":"","ShippingOptions":"Default (Sell-to Address)","Ship_to_Code":"","Ship_to_Name":"John Haddock Insurance Co.","Ship_to_Address":"10 High Tower Green","Ship_to_Address_2":"","Ship_to_City":"Manchester","Ship_to_County":"","Ship_to_Post_Code":"MO2 4RT","Ship_to_Country_Region_Code":"GB","Ship_to_Contact":"Miss Patricia Doyle","Shipment_Method_Code":"EXW","Shipping_Agent_Code":"","Shipping_Agent_Service_Code":"","Package_Tracking_No":"","BillToOptions":"Default (Customer)","Bill_to_Name":"John Haddock Insurance Co.","Bill_to_Address":"10 High Tower Green","Bill_to_Address_2":"","Bill_to_City":"Manchester","Bill_to_County":"","Bill_to_Post_Code":"MO2 4RT","Bill_to_Country_Region_Code":"GB","Bill_to_Contact_No":"CT000012","Bill_to_Contact":"Miss Patricia Doyle","BillToContactPhoneNo":"","BillToContactMobilePhoneNo":"","BillToContactEmail":"miss.patricia.doyle@contoso.com","Location_Code":"","Shipment_Date":"2024-01-17","Shipping_Advice":"Partial","Outbound_Whse_Handling_Time":"","Shipping_Time":"","Late_Order_Shipping":false,"Combine_Shipments":true,"Transaction_Specification":"","Transaction_Type":"","Transport_Method":"","Exit_Point":"","Area":"","Language_Code":"ENG","Prepayment_Percent":0,"Compress_Prepayment":true,"Prepmt_Payment_Terms_Code":"CM","Prepayment_Due_Date":"2024-01-31","Prepmt_Payment_Discount_Percent":0,"Prepmt_Pmt_Discount_Date":"2024-01-17","Date_Filter":"''..09/20/22"}]}

Only the body is stored in the message when using the WebserviceEndpoint element in your connections.

This completes the example of using the webservice endpoint with a GET request

Follow up steps

With the data received from the WebService you can create an internal document to use the data received further down the pipeline

  1. Setup the Webservice
  2. Create an External document from the Webservice Response
  3. Use the JsonToXML translator to transform the Webservice Response to XML/External document format
  4. Create an internal document with the Tables/Fields you want to update in Business Central
  5. Use the mapper to map the data to the internal document format
  6. Use the RecordGenerator to create/update the Business Central data based on the response.