The Web Service Client communication point supports RPC and document-based web services. A single communication point can call multiple operations hosted by the same web service. If multiple operations are supported, then a message property on the message (rhapsody:consumerOperation) indicates which operation should be used.

Operational Modes

Supported Operational Modes: Output, Out -> In.

If running in Out->In mode and using an output only operation, the messages received from the communication point are identical to the message sent (assuming no fault occurred). If running in Output mode and using a request-response operation, the response message is discarded (custom fault processing still occurs, but cannot return a message to the route).

Using WSDLs

When parsing a WSDL, the Rhapsody engine extracts the following information:

  • The service name.
  • The available endpoints for the web service.
  • The available operations (and namespaces) for the web service.

All these values can be manually set, if required, irrespective of whether a WSDL is used to generate the configuration. Manually configured values can use Rhapsody variables as part of the configuration.

Generating SOAP Requests and Responses

This communication point provides the following methods to generate the outgoing SOAP request:

  • Use the Rhapsody message body as the entire SOAP envelope.
  • Use the Rhapsody message body as the contents of the SOAP body.
  • Build the contents of the SOAP body using a template, and map the message properties, fields or message body using XPaths to refer to locations in the template.
  • Construct the SOAP message using JavaScript.

It provides the following methods to generate the incoming SOAP response:

  • Replace the Rhapsody message body with the entire SOAP envelope from the response.
  • Replace the Rhapsody message body with the contents of the SOAP body.
  • Set message properties, the message body, and fields within the message using XPaths to extract values from the SOAP response.
  • Execute custom JavaScript when SOAP response is received.

CDATA Support

Through the following configuration property in the rhapsody.properties file, you can configure the web service framework to write either escaped or preserved CDATA sections to the content of SOAP requests and responses.

Property Default Value Description
WebServicesFramework.CDATA.preserve False

Enables the web service framework either to preserve CDATA sections or escape them:

  • If not set or set to false, then all literal CDATA sections in incoming and outgoing XML are escaped for both consumers and producers.
  • If set to true, then the CDATA sections are preserved if and only if no security bindings are set for both the producer and consumer (an HTTPS connection ought to be secure enough for most applications).

Configuration Properties

Click the Edit Communication Point Configuration link to view the properties you can configure.

General

Property

Description

WSDL URL

Click the Reload WSDL link to open the Load WSDL dialog, and enter the URL to retrieve the WSDL from, or its location on the local machine where Rhapsody IDE is running (not the location on the Rhapsody server):

Select the Specify an exact TLS version checkbox if you want the communication point to interpret your selected SSL Protocol as the exact version you want to use rather than the minimum version.

If you require HTTP basic/digest authentication or HTTPS client authentication to retrieve the WSDL, then select the Authenticate when loading WSDL checkbox, and either the Username and Password must be entered, or a Private Key must be selected. Select the Load button to retrieve and parse the WSDL.

If a Rhapsody variable containing any XML tags (in the form abcd<efgh>ijkl for example) is used for the username or password in a Web Service Client communication point, then the communication point will fail to configure.

To load the WSDL into Rhapsody when the WSDL has external references to other WSDLs or schemas using absolute paths (for example http://<server>:<port>/path/to/schema.xsd):

  1. Download the WSDL and all referenced files to a local folder (for example: C:\WSDL).

  2. Replace the external URLs in the main WSDL with the local file paths of the downloaded references (for example, replace http://<server>:<port>/path/to/schema.xsd with schema.xsd since schema.xsd is now in the same folder as the WSDL).

  3. Load the main WSDL using the Parse WSDL from file option.

The default timeout of one minute is used. The value can be changed by setting the WebServicesConsumerService.wsdl.timeoutInSeconds option in rhapsody.properties file.

The SSL Protocol can also be selected when reloading a WSDL from a web service, and defaults to the SSL protocol on that web service client. Refer to TLS/SSL Support in Rhapsody for details. It is recommended that all calls to web services be secured if supported by the server, either by using TLS or the symmetric or asymmetric security bindings.

Endpoint URL

Selects the URL to use to send requests to the web service, or enter a custom endpoint. The custom endpoint can either be a message property (specified by starting the property name with a dollar '$' symbol), or a combination of a literal and Rhapsody variables.

When you select a WSDL, the Endpoint URL is automatically set.

SOAP Binding

Selects the SOAP version:

  • SOAP 1.1.
  • SOAP 1.2 (default).

When you select a WSDL, the SOAP binding is automatically updated to match the selected Endpoint URL.

Send WS-Addressing Headers

Determines whether the WS-Addressing headers should be sent in the outgoing SOAP request and expected in the SOAP response. It is enabled by default.

Connection Timeout (ms)

The length of time, in milliseconds, Rhapsody should wait for a connection attempt to succeed before aborting it. The default is 60,000 milliseconds. One of the following actions is taken after connection timeout:

  • If a static endpoint URL is used, the connection retries are made as configured for this communication point (as in General tab) because a connection timeout is viewed as a connection failure.
  • If a message property is used to specify a custom endpoint URL, the message is sent to the error connector, but subsequent messages are still sent because a connection timeout is viewed as a message error.

HTTPS Client Authentication

Whether to use HTTPS Client Authentication:

  • Required.
  • Optional.
  • Disabled (Default).

This property is unavailable if the selected Endpoint URL is a literal or value selected from the WSDL, and the URL does not use HTTPS. It is available if the URL is HTTPS, a message property or a Rhapsody variable.

The Web Service Client communication point does not support pre-emptive authentication.

SSL Protocol

The SSL Protocol that should be used. Disabled if connecting to an older Rhapsody engine that does not support this functionality. Newly created web service clients default to TLSv1.2 with strong ciphers. Refer to SSL Protocol Versions for details.

SSL Cipher Suites

Limits the SSL cipher suites that can be used, allowing a minimum encryption level to be set:

  • Very Strong Cipher Suites (AES-256).
  • FIPS Cipher Suites (AES-128, AES-256, TripleDES-168) (default).
  • Strong Cipher Suites (AES-128, AES-256, TripleDES-168, RC4-128).

Disabled if connecting to an older Rhapsody engine that does not support this functionality. Newly created web service clients default to TLSv1 with strong ciphers. Refer to SSL Cipher Suites for details.
Server Authentication

Determines how server authentication is performed when an HTTPS connection is in use:

  • Use Certificate Authorities for Authentication - the web service client ensures that the certificate presented by the server is signed by a trusted certificate authority, and is for the server that it is connecting to.
  • Authenticate Using Provided Certificate - the web service client ensures that the certificate presented by the server is either the exact certificate provided in the Web Service Certificate option, or a certificate that is signed by that certificate. The Web Service Certificate configuration option is mandatory in this case.
  • Anonymous Authentication - the web service client does not perform any authentication. This option is not recommended.

Web Service Certificate

Click the Select link to select the certificate used by the web service. If the connection uses HTTPS, then this certificate is used to authenticate the remote server if the Server Authentication property is set to Authenticate Using Provided Certificate. Even if HTTPS is not in use, this parameter may be provided as it is required when using asymmetric or symmetric security binding.

Only available if using HTTPS with the Authenticate Using Provided Certificate option for Server Authentication, or asymmetric/symmetric security binding.

Client Private Key

Click the Select link to select the private key this communication point should use when talking to the web service. It is required if HTTPS client authentication is required or optional, but may be set even if that is not the case, as it is required when using asymmetric security binding.

Only available if using HTTPS client authentication or asymmetric security binding.

Message Definition

Click the Select link to select the message definition to use when parsing the WSDL. The message definition is optional, but needed for the following operations:

  • Building the SOAP request from a template where some of the insertion values are from fields in the message.
  • Extracting values from the SOAP response where some of the extracted values are to be inserted into fields in the message.
  • Browsing fields in the message for configuring the above operations.

Custom SOAP Header

Can be set to a literal, message property or Rhapsody variable.

When using a message property to set the Custom SOAP Header configuration property, ensure the message property is populated with the full SOAP header. Additionally, ensure Custom SOAP Header is set to this message property and nothing else.

For example, setting Custom SOAP Header to $customHeader is valid where the message property customHeader has been populated with the appropriate full SOAP header. On the other hand, setting Custom SOAP Header to <soap:Header>$customHeader</soap:Header> is invalid since it contains literals as well as a message property.

Proxy

Property Description
Proxy Enabled Whether the communication point should connect via a proxy.
Proxy Hostname The hostname for the proxy server.
Proxy Port The port for the proxy server. If set to a value less than 1, the default HTTP port will be used.
Proxy Username The username to authenticate with the proxy server, if required.
Proxy Password The password to authenticate with the proxy server, if required.

Security

Property

Description

Security Binding

Defines how the key exchange mechanism works:

  • No Security Binding (default).
  • Transport Security Binding.
  • Asymmetric Security Binding.
  • Symmetric Security Binding.

Note that even if there is no security binding, the connection can still be secure if it uses HTTPS with an appropriate authentication mechanism.

Authentication Method

Determines how the client will authenticate itself to the web service:

  • No Authentication (default).
  • HTTP Basic/Digest Authentication.
  • HTTPS Client Authentication - the Endpoint URL must be an HTTPS endpoint (or unknown if it is a message property) and a private key must be provided.
  • Username Token Plaintext Authentication - the web service client adds authentication information (username and password) to the SOAP header, and sets the mustUnderstand attribute to true (or 1) to enforce authentication on the server side.
  • Username Token Digest Authentication - the web service client adds authentication information (username and password) to the SOAP header, and sets the mustUnderstand attribute to true (or 1) to enforce authentication on the server side.
  • X509 Token Authentication - only available when the asymmetric binding mechanism is used, as it requires the client to have a private key.

Username

The username that can be a literal, a Rhapsody variable, or a reference to a Rhapsody message property. The username is required when using HTTP Basic/Digest Authentication or Username Token Authentication.

Rhapsody variables are referenced using the $(variableName) notation; Rhapsody message properties are referenced using the $propertyName notation.

Password

The password that can be a literal, a Rhapsody variable, or a reference to a Rhapsody message property. A blank password is permitted (although not recommended) for Username Token Authentication.

Rhapsody variables are referenced using the $(variableName) notation; Rhapsody message properties are referenced using the $propertyName notation.

As message properties are visible in the Management Console to users with the appropriate access rights, it is highly recommended that you encrypt passwords provided in this message using the Encrypt Password function in the Rhapsody IDE. Alternatively, you can use Configuration Templates, which do not require providing the password in a message property.

If the passwords are retrieved from a Rhapsody variable using JavaScript, then the retrieval functions can leave them in this format. Refer to Encrypted Rhapsody Variables for details.

Algorithm Suite

Controls which set of algorithms are used for security. The default value is BASIC_256.

Only available when using asymmetric or symmetric security binding.

Protection Order

Determines whether messages are signed first or encrypted first:

  • Encrypt Then Sign.
  • Sign Then Encrypt (default).

Only available when using asymmetric or symmetric security binding.

Initiator Token

How the client's certificate should be referenced in the SOAP request:

  • Include Binary Security Token (default) - embed the x509 certificate in the request.
  • Reference using SHA-1 Thumbprint - used when the web service already has access to the certificate and can retrieve it when necessary.

Only available when using the asymmetric security binding.

Recipient Token

How the web service's certificate should be referenced in the SOAP request:

  • Include Binary Security Token (default) - embed the x509 certificate in the request.
  • Reference using SHA-1 Thumbprint.

Only available when using asymmetric or symmetric security binding.

Timestamp mode

Determines whether a timestamp is included in the security header of the SOAP request and required in SOAP responses:

  • Don't use timestamps (default).
  • Include timestamp in requests and require timestamp in responses.
  • Include timestamp in requests, timestamp optional in responses.

Only available when using transport, asymmetric or symmetric security binding (although it does not add anything when used with transport binding).

Use Derived Keys

Select to enable the use of the <DerivedKeyToken> element as defined by the WS-SecureConversation 1.4 document.
Encrypt Signatures

Select to encrypt the signature. Refer to Section 6.4 of the WS-SecurityPolicy 1.3 document for details.

Signing / Encryption

Options to sign and encrypt message content. The messages are effectively always signed and encrypted when using transport security binding as it uses HTTPS. Refer to Signing and Encryption Parameters for details.

Only available when using asymmetric or symmetric security binding.
Use Endorsing Supporting Tokens

Select to enable Endorsing Supporting Tokens. Refer to Section 8.3 of the WS-SecurityPolicy 1.3 document for details.

Signing and Encryption Parameters

Property

Description

Inherit settings from web service configuration

Select to inherit the signing and encryption settings from the web service.

Encryption Mode

Determines whether the messages are encrypted and how:

  • Do not Encrypt (default).
  • Encrypt Entire Body.
  • Encrypt Body Parts.

Signing Mode

Determines whether the messages are signed and how:

  • Do not Sign (default).
  • Sign Entire Body.
  • Sign Body Parts.

XML Namespace Mapping

Provides a mapping of XML prefixes to namespace URIs. It is used to declare namespace prefixes used in the XPaths that select the components to sign and encrypt. If this map is empty and one of the encryption or signing modes is changed to sign/encrypt parts of the message, then an entry is automatically added here for the service namespace (as that is the namespace that is likely to be used).

Only available if either the encryption or signing mode indicates that parts of the message body will be encrypted or signed.

XPaths to Encrypt

A set of XPaths (one per line) identifying components in the message that should be encrypted. A value here does not mean that the message must include a value at that location. Rather, it means that if the value is present, it must be encrypted.

XPaths to Sign

A set of XPaths (one per line) identifying components in the message that should be signed.

Operations

An operation is configured in four parts:

  • How to call the operation.
  • How to generate the SOAP request.
  • How to process the SOAP response.
  • How to handle SOAP faults.

Refer to Web Service Operations for details.

Management

Field

Description

Custom SOAP Headers

The custom SOAP headers that are expected in the incoming requests.

Custom header entries in a SOAP request can be enforced by clients by setting the mustUnderstand attribute to true. If this attribute is set to true, then all expected custom header entries must be defined by setting their name and namespace (as required by the SOAP specification) in the Web Service Client communication point's configuration. If the custom header entries are not defined or defined incorrectly, then incoming messages are rejected, resulting in a connection error. 

If a SOAP request contains custom headers entries with the mustUnderstand attribute set to false, then the headers entries are ignored, whether defined or not.

If you intend to use custom header entries, then you are responsible for implementing support for them in the Rhapsody configuration.

If you want to use a Rhapsody variable that contains XML to set the custom header, ensure you pre-escape the XML to avoid configuration errors. For example, use the following value in a Rhapsody variable:

Escaped XML 
&lt;urn:SessionHeader xmlns:urn=&quot;urn:enterprise.soap.sforce.com&quot;&gt;&lt;urn:sessionId&gt;00D630000008yXI!AQIAQJYQv9V9I3dnKzY7E0A0pCVNwghid8Jy5okgLGg3Lkf7D3I3OGWLRPion5_HTRUy_6ASrIHB6ByE_JTikP_GeKmToHC8&lt;/urn:sessionId&gt;&lt;/urn:SessionHeader&gt;

instead of:

Unescaped XML 
<urn:SessionHeader xmlns:urn="urn:enterprise.soap.sforce.com">
  <urn:sessionId>00D630000008yXI!AQIAQJYQv9V9I3dnKzY7E0A0pCVNwghid8Jy5okgLGg3Lkf7D3I3OGWLRPion5_HTRUy_6ASrIHB6ByE_JTikP_GeKmToHC8</urn:sessionId>
</urn:SessionHeader>