WCF SOAP

The WCF SOAP connection calls operations on Windows Communication Foundation (WCF) SOAP services, such as DeltaV Batch Campaign Manager. These services often require Windows authentication or WCF message security which require .NET, so the Intelligence Hub calls them through the WCF SOAP Agent. The agent is a .NET application that runs on Windows. See WCF SOAP Agent for how to install and configure the agent.

The agent loads the service’s WSDL files from a local folder at startup. The WCF SOAP connection allows connecting to the Agent and browsing the WSDL operations to create inputs and outputs.

Connection Settings

SettingDescription
HostIP address or host name of the WCF SOAP Agent.
PortPort the WCF SOAP Agent listens on. Default is 45490.
TokenThe connection token the agent uses to authenticate the Intelligence Hub connection. This must match the token in the agent’s settings.json.
Connect Timeout (seconds)The maximum amount of time to wait for a successful connection to the agent. If this time is exceeded the connection fails with an error. Default is 5.
Request Timeout (ms)The maximum amount of time to wait for a read or write response. If this time is exceeded the read or write fails with an error. The agent also uses this value as the timeout for calls to the SOAP service. Default is 30000.
CompressionWhen enabled, communication between the Intelligence Hub and the agent is compressed using GZip. This improves read times in cases where returned payloads are large. For smaller payloads, there may be little or no performance improvement.
AuthenticationHow the agent authenticates with the SOAP service. See Authentication below.
Ignore CertificateWhen enabled, the agent doesn’t validate the SOAP service’s HTTPS or message security certificate. Use this for testing against services that use self-signed certificates. Leave this disabled in production.
Session Start OperationThe operation the agent calls each time it connects to the SOAP service, for services that require a login call before other operations. Leave blank when the service doesn’t need one.
Session Start ParametersThe request body for the Session Start Operation, as XML. This value is stored encrypted because it may hold credentials. Leave blank to call the operation with no parameter values.

Authentication

TypeDescription
Service AccountThe agent uses the Windows account it runs under to authenticate with the SOAP services. Use this when the agent and the SOAP service are on the same Windows domain. This is the default.
WindowsThe agent uses the Windows credentials entered in Username, Password, and Domain.
BasicThe agent sends the Username and Password as username credentials. Use this for services secured with a username and password instead of Windows authentication.

Input Settings

Inputs call an operation on the SOAP service and return the response. The response can be in XML or JSON format. Use the ‘Find’ button to browse all operations.

If the service returns a SOAP fault, the read fails with an error that includes the fault code, reason, and detail.

SettingDescription
OperationThe WSDL operation to call when the input is read. Use Find to browse the operations loaded by the agent. Selecting an operation also fills in Request Body with a sample body for that operation. See Sample Request Body below.
Request BodyThe SOAP request body as XML. The body is sent as entered, so it must be valid XML for the operation. Use input parameters to insert values at read time. Leave blank to call the operation with no parameter values.
Response FormatThe format of the read result. Default is XML. See Response Format below.

Sample Request Body

The sample body from Find includes every element defined in the schema, with placeholder values.

Response Format

FormatDescription
XMLReturns the SOAP response body as XML text. This is the default.
JSONConverts the SOAP response body to JSON using the WSDL schema.

For example, an input with the following request body:

<GetUnits xmlns="http://example.com/Services">
  <server>SERVER1</server>
</GetUnits>

Returns the following with Response Format set to XML (formatted here for readability):

<GetUnitsResponse xmlns="http://example.com/Services">
  <GetUnitsResult xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"
                  xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <b:string>UNIT1</b:string>
    <b:string>UNIT2</b:string>
  </GetUnitsResult>
</GetUnitsResponse>

And the following with Response Format set to JSON:

[
    "UNIT1",
    "UNIT2"
]

Output Settings

Writes call an operation on the SOAP service and send the request body. Use the ‘Find’ button to browse all operations. The response body from the service isn’t returned. A write succeeds when the service responds without a fault.

Operation

The WSDL operation to call for each write. Use Find to browse the operations loaded by the agent. Selecting an operation also fills in Request Body with a sample body for that operation.

Request Body

The SOAP request body as XML. Use {{this.attribute}} references to insert values from the outgoing payload. For example:

<SetSetpoint xmlns="http://tempuri.org/">
  <Name>{{this.name}}</Name>
  <Value>{{this.value}}</Value>
</SetSetpoint>

Leave blank to send the payload itself as the request body. In this case the payload must be a string containing the XML body.

Appendix: DeltaV Batch Campaign Manager

DeltaV Batch Campaign Manager requires a login call before other operations. Set the following connection settings so the agent logs in each time it connects to the service.

SettingValue
Session Start OperationConnect
Session Start ParametersThe Connect request body with the user name, domain, and password of a Campaign Manager user. See the example below.

The request body must include all three elements:

<Connect xmlns="EmersonProcess.Web.Services.CampaignManager">
  <userName>myUser</userName>
  <domain>MYDOMAIN</domain>
  <password>myPassword</password>
</Connect>