Training
Module
Work with web services in Dynamics 365 Business Central - Training
Use SOAP and OData to read and update records, and handle UI interaction in Business Central.
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
You use the SOAP send adapter to call a Web service. The SOAP send adapter reads the message context on the BizTalk Message object to get the proxy name and calls the associated external Web service proxy.
The SOAP send adapter authenticates with the destination server by using one of the following authentication types:
Anonymous. The default setting.
Basic. The SOAP connection sends the user name and password in plain text.
Digest. The SOAP connection sends the user name and password in an encrypted format.
Kerberos or NTLM. Neither the user name nor the password is sent over a SOAP connection. The SOAP adapter always uses the credentials of the process under which the SOAP send adapter runs for this authentication type.
Additionally, the SOAP send adapter can provide a client Secure Sockets Layer (SSL) certificate to the Web server if the server requires or accepts it.
If you enabled Enterprise Single Sign-On (SSO), when the SOAP send adapter receives a message with the request to the SSOTicket property, the adapter connects to an SSO server to validate and redeem the ticket. After the SOAP adapter validates the ticket, it is decrypted and the credentials for the affiliate system are retrieved from the credential store. The SOAP adapter then uses the credentials to connect to the affiliate system, and the SOAP request is processed.
The SOAP send adapter can establish a secure connection with servers that accept or require client certificates. If you specify a client certificate, the SOAP send adapter uses the certificate when connecting with servers that require or accept client certificates. If you do not specify a client certificate and the destination server requires client certificates, the SOAP send adapter fails to send the message and follows the standard retry logic.
The SOAP send adapter uses the client certificate from the Personal store of the account under which the BizTalk Server process is running. The SOAP adapter specifies the certificate by its thumbprint. If the SOAP send adapter fails to load the certificate for any reason, the message that it was sending is suspended.
When a message is successfully transmitted, the BizTalk Messaging Engine publishes an associated Acknowledgement (ACK) message to the MessageBox database if delivery notifications are enabled. Likewise, when a message is suspended by the BizTalk Messaging Engine or an orchestration is suspended by the orchestration engine, BizTalk Server publishes an associated Negative Acknowledgement (NACK) message to the MessageBox. The NACK message contains context properties and a message body part consisting of a SOAP fault. If the NACK message is generated due to a failed transmission from the HTTP or SOAP adapters, the SOAP fault contains the Headers element and the Body element of the response from the destination Web server. The following is an example of the SOAP fault in a NACK generated for a failed SOAP transmission:
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/" SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP:Body>
<SOAP:Fault>
<faultcode>Microsoft BizTalk Server Negative Acknowledgment</faultcode>
<faultstring>An error occurred while processing the message, refer to the details section for more information</faultstring>
<faultactor>http://localhost/receivestandard.asp</faultactor>
<detail>
<ns0:NACK Type="NACK" xmlns:ns0="http://schema.microsoft.com/BizTalk/2003/NACKMessage.xsd">
<NAckID>{4E646707-03AA-4493-95C7-A64B09E2987D}</NAckID>
<ErrorCode>0x80131600</ErrorCode>
<ErrorCategory>0</ErrorCategory>
<ErrorDescription>The remote server returned an error: (404) Not Found.</ErrorDescription>
<ErrorDetail>
<HttpErrorDetail xmlns="http://schema.microsoft.com/BizTalk/2006/HttpErrorDetails.xsd">
<Headers>Server: Microsoft-IIS/5.1 Date: Wed, 21 Apr 2005 00:27:47 GMT X-Powered-By: ASP.NET Connection: close Content-Type: text/html Content-Length: 67 </Headers>
<Body>We could not locate the page you requested. Please check the URL.</Body>
</HttpErrorDetail>
</ErrorDetail>
</ns0:NACK>
</detail>
</SOAP:Fault>
</SOAP:Body>
</SOAP:Envelope>
Note
The Headers element and the Body element are limited to 48 KB. The Headers element is rounded to the nearest complete header value pair without exceeding the limit. The Body element is truncated to 48 KB.
Note
NACK and ACK messages are discarded if there are no matching subscriptions for them. NACK and ACK messages are not suspended by the Messaging Engine.
To subscribe to a NACK message, you can do one of the following:
Create a send port with a filter for the appropriate message context property. See Message Context Properties in the UI guidance and developers API namespace reference for a listing of system message context properties including those related to message acknowledgment.
Send from an orchestration port marked with Delivery Notification = Transmitted. If an orchestration port is marked with Delivery Notification = Transmitted, the orchestration will wait until it receives either an ACK or a NACK for the message that was transmitted. If a NACK is generated then it will be routed to the orchestration and the orchestration will throw a DeliveryFailureException. The DeliveryFailureException is deserialized from the SOAP fault that is contained within the NACK message body. To retrieve the exception message string from the SOAP fault that is returned to the orchestration, cast the DeliveryFailureException to a SoapException and then access the InnerXml from the SOAP Detail section. The following code sample demonstrates how to do this:
// Cast the DeliveryFailureException to a SoapException…
System.Web.Services.Protocols.SoapException se = (System.Web.Services.Protocols.SoapException)e.InnerException;
System.Diagnostics.Trace.WriteLine(se.Detail.InnerXml);
//e is an Microsoft.XLANGs.BaseTypes.DeliveryFailureException
//object type created in an Exception handler
The code sample above will return an XML fragment similar to the following:
<ns0:NACK Type="NACK" xmlns:ns0="http://schema.microsoft.com/BizTalk/2003/NACKMessage.xsd">
<NAckID>{4E646707-03AA-4493-95C7-A64B09E2987D}</NAckID>
<ErrorCode>0x80131600</ErrorCode>
<ErrorCategory>0</ErrorCategory>
<ErrorDescription>The remote server returned an error: (404) Not Found.</ErrorDescription>
<ErrorDetail>
<HttpErrorDetail xmlns="http://schema.microsoft.com/BizTalk/2006/HttpErrorDetails.xsd">
<Headers>Server: Microsoft-IIS/5.1 Date: Wed, 21 Apr 2005 00:27:47 GMT X-Powered-By: ASP.NET Connection: close Content-Type: text/html Content-Length: 67 </Headers>
<Body>We could not locate the page you requested. Please check the URL.</Body>
</HttpErrorDetail>
</ErrorDetail>
</ns0:NACK>
What Is the SOAP Adapter?
SOAP Adapter Security Recommendations
Training
Module
Work with web services in Dynamics 365 Business Central - Training
Use SOAP and OData to read and update records, and handle UI interaction in Business Central.