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
| Setting | Description |
|---|---|
| Host | IP address or host name of the WCF SOAP Agent. |
| Port | Port the WCF SOAP Agent listens on. Default is 45490. |
| Token | The 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. |
| Compression | When 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. |
| Authentication | How the agent authenticates with the SOAP service. See Authentication below. |
| Ignore Certificate | When 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 Operation | The 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 Parameters | The 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
| Type | Description |
|---|---|
| Service Account | The 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. |
| Windows | The agent uses the Windows credentials entered in Username, Password, and Domain. |
| Basic | The 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.
| Setting | Description |
|---|---|
| Operation | The 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 Body | The 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 Format | The 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
| Format | Description |
|---|---|
| XML | Returns the SOAP response body as XML text. This is the default. |
| JSON | Converts 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.
| Setting | Value |
|---|---|
| Session Start Operation | Connect |
| Session Start Parameters | The 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>