Web Services in Rhapsody

A web service definition contains the configuration information to host the web service, including its name and namespace, addressing information, the operations and types, and any security.

Rhapsody supports two methodologies for creating web services: top-down and bottom-up.

The top-down approach uses an existing Web Services Description Language (WSDL). The WSDL is imported and is used to generate the web service configuration. You can then modify the configuration, and your changes will be reflected in the WSDL that is hosted by Rhapsody.
The bottom-up approach does not require a WSDL. Instead, you create a new web service, and configure all the settings manually. We recommend this approach when exposing an existing Rhapsody route as a web service.

The Web Services Manager provides a central location for managing web services:

Viewing Web Services
Managing Web Services
Editing a Web Service

Viewing Web Services

The Web Services Manager lists the web services hosted by Rhapsody:

The Web Services Manager displays the following information:

Column	Description
Name	The name of the web service.
State	The current state of the web service: `Running`. `Configuration Error`. `Retrying` - the web service is configured correctly but fails to start due to an error (for example, a binding or socket error).
Namespace	The namespace URI of the web service.
Binding Summary	Whether HTTP or HTTPS is in use, the port, the local address bindings (if in use), and the SOAP bindings supported.
Security Summary	The security binding and authentication mechanism in use.
Description	A description of the web service.
Watchlist	The watchlist associated with the web service.

Managing Web Services

The Web Services manager enables you to perform the following actions:

Action	Description
Add	Add a web service using the Web Services Properties dialog.
Edit	Edit a selected web service using the Web Services Properties dialog.
View	View a web service using the Web Services Properties dialog in read-only mode.
Delete	Delete a selected web service.
Edit Users	Launch the Web Services User Store manager to manage users. Refer to Managing Web Service User Stores for details.
Check Out	Check out a selected web service.
Check In	Check in a selected web service using the Check-in dialog. Any mandatory or improperly configured fields trigger a warning before you can check in your changes. Refer to Checking In for details.
Undo Check Out	Undo the changes in a checked out web service.
Show Uses	Display the components a web service is being used in.
View Errors	Determine why any web service are unconfigured.
Filter	Perform text-based filtering to filter the list of displayed web services.

Editing a Web Service

General Settings

Field	Description
Service Name	Web service names must not conflict with the Rhapsody API Web service names (namely, `RhapsodyComponentsService`, `MessageSearchingService`, `RhapsodyStatusService` and `SystemStatisticsService`), nor any service name reserved for future use in the API (names beginning with `Rhapsody`).
Service Namespace	Every web service needs a unique namespace in order for client applications to distinguish it from other services on the Web. The namespace is typically in the form of an internet URL for an owned domain. For example, you can use your company's Internet domain name as part of the namespace, `http://www.orionhealth.com/rhapsody/demo`. The namespace need not point to the actual web service URL.
Service Description	Comments describing the web service.
Protocol	Options: `HTTP`, `HTTPS` Default: `HTTP`. It is strongly recommended that all web services be secured either using HTTPS or the symmetric or asymmetric security bindings.
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 FIPS 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. Refer to SSL Cipher Suites for details.
Local Address	The local binding for the HTTP(S) connector. If a value is not specified, it binds to all local addresses. The local address can be set using Rhapsody variables or literals.
Port	The local port for the HTTP(S) connector. The local port can be set using Rhapsody variables or literals. Multiple Web services can run on the same port if the settings on the HTTP(S) connector are compatible.
Private Key	Click the Select Private Key link to select an existing private key from the Certificate Manager. A private key is required if using HTTPS, or the asymmetric or symmetric security bindings. Only RSA SSL private keys are available for selection if using HTTP.
SOAP 1.1 Binding	Select this checkbox if the Web service applications use SOAP 1.1 binding.
SOAP 1.2 Binding	Select this checkbox if the Web service applications use SOAP 1.2 binding.
WS-Addressing Support	Whether WS-Addressing headers are permitted or mandatory: `Required`. `Optional` (default). `Prohibited`. WS-Addressing headers are converted into Rhapsody message properties to allow the user to provide conditional processing and routing.
Asynchronous Requests	Whether Asynchronous Requests are permitted or mandatory: `Required` - the web service will require the `wsa:ReplyTo` header be set to a non-anonymous address. `Optional` - the web service will not check for a valid response address. `Prohibited` (default) - the web service will reject calls asking for asynchronous messaging. This field is only available if you select `Required` or `Optional` in the WS-Addressing Support field.

Operations

You can perform Add, Edit and Remove operations.

Each of the parameter types (Input, Output and Faults) have the same configuration options.

Field	Description
Name	The (local) name of the operation to call.
Description	A description of the Web service operation.
Operation Mode	Options: `In-Only`, `Request-Response` Default: `In-Only` If this is an Input Only operation, then the Output and Faults tabs are not available. If this is a Request-Response operation, then the Output parameters are required, but the Faults parameters are optional. The Input parameters are always required.
SOAP Action	The expected value in the SOAP Action HTTP header when this operation is called. If this is not set, an appropriate default value is used (`urn:<OperationName>`).
Use existing type	Select from a list of standard XML types or any elements defined in the schema from an imported WSDL (if available), and two special values: `<Any Type>` - the operation will receive XML in any valid XML format. The datatype is not defined in the web service, so anything is accepted. `<Empty Type>` - no data is expected to be received in this operation.
Use named type	Select this option if the data type of the operation is defined in a schema related to this web service. The Name and Namespace reference the data type in the schema.
Use custom type	Simple data types can be created within the web service framework using a custom type. Click the Edit Custom Type link to create a new custom data type. Refer to Custom Types for details.
WS-Addressing Action	The URI of the expected value in the `wsa:Action` SOAP header when WS-Addressing is enabled. It can only be set if WS-Addressing is enabled for the Web service. If not set, then a default value is automatically generated as defined in the WS-Addressing Metadata specification.
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. The signing and encryption options are very similar to those at the Web service level. However, each has a new value (which is the default) to use the settings defined at the Web service level. Note that as with the options at the Web service level, these options must be extended to allow the user to map between namespaces and prefixes. The other difference is that the signing and encryption options for Faults always default to `Do not Sign` or `Do not Encrypt`, but can be changed. This is because you will rarely want to encrypt faults even if the remainder of the messages are encrypted. Only available when using asymmetric or symmetric security binding.

Custom Types

You can add any number of parameters and order them as required. It is perfectly valid to create a custom type with no parameters at all.

Field	Description
Allow additional parameters not listed below	Allows the parameter to accept any other children that may be found by adding an `<xs:any>` element to the type. This option differs from selecting `<Any Type>` for a particular parameter in that it provides no control over the incoming top-level element names.
Name	A valid XML NCName.
Type	Select a type from the list. The available types are the standard XML types, types defined in the original WSDL used to generate the Web service (not available for bottom-up Web services), and two special values: `<Any Type>` - causes a new element to be created with the specified name, containing complex type with mixed content that allows any attributes and any element children. `<Empty Type>` - the same as creating a custom type with no children. `<Any Type>` is the same as creating a custom type with the Allow additional parameters not listed below checkbox selected.
Required	Whether required or optional.
Repeating	Whether repeating or not.

Security Settings

Field	Description
Security Binding	Asymmetric and symmetric security bindings require a private key to be configured: `No Security Binding` (default). `Transport Security Binding` - only available if HTTPS is being used. `Asymmetric Security Binding` `Symmetric Security Binding`
Authentication Method	The authentication method: `No Authentication` (default). `Basic HTTP Authentication` - when security binding is enabled for this authentication method, authentication is delegated to HTTP layer. Therefore, the communication point may not send SOAP response if authentication fails, requiring the client side to refer to the HTTP header to determine the cause of failure (for example, a 401 response code). `Username Token Authentication` `X509 Token Authentication` - only available when asymmetric binding is used, as it requires a private key to be configured. `HTTPS Client Certificate Authentication` - only available if HTTPS is used. It is strongly recommended that client authentication is enabled using one of the available methods. As Basic HTTP Authentication and Username Token Authentication can result in an effective plaintext password being sent, it is recommended that these methods only be used with HTTPS.
Authenticated Users	Displays the users in the Web Service User Store. Click the Edit Authenticated Users link to add or edit users, or edit the certificates associated with the users. This property is disabled if Authentication Method is set to `No Authentication`.
Algorithm Suite	Lists the available algorithm suites as defined in the WS-SecurityPolicy 1.1 specification (the default is `BASIC_256`). It is only available when using asymmetric or symmetric binding.
Protection Order	Determines whether messages are signed first or encrypted first: `Sign Then Encrypt` (default). `Encrypt Then Sign` Only available when using asymmetric or symmetric security binding.
Header Layout	The header layout strictness: `Strict` (default). `Lax` `Lax with Timestamp First` `Lax with Timestamp Last`
Include Timestamp in Requests	Determines whether a timestamp is included in the security header of the SOAP request. Only available when using transport, asymmetric or symmetric security binding (although it does not add anything when used with transport binding). By default, this checkbox is selected.
Only allow signing of entire headers and body	This checkbox is selected by default. It does not apply when using the transport security binding.
Use Derived Keys	Enables use of the `<DerivedKeyToken>` element as defined by the WS-SecureConversation 1.4 document.
Encrypt Signatures	Encrypts 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	Enables 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 this checkbox if you want to inherit the signing and encryption settings from the web service.
Encryption Mode	Determines whether the messages are encrypted: `Do not Encrypt` (default). `Encrypt Entire Body`. `Encrypt Body Parts`.
Signing Mode	Determines whether the messages are signed: `Do not Sign` (default). `Sign Entire Body`. `Sign Body Parts`. The `Sign Body Parts` option is not available if the Only allow signing of entire headers and body checkbox is selected.
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.

Management Settings

Field	Description
Custom SOAP Headers	The custom SOAP headers that are expected in the incoming requests. Custom headers can be enforced by clients by setting the `mustUnderstand` attribute to `true.` If this attribute is set, then all customer headers must be defined. Incoming messages will be rejected if the `mustUnderstand` attribute is set and customer SOAP headers are not defined (as required by the SOAP specification). If a SOAP request contains custom SOAP headers without setting the `mustUnderstand` attribute, then it makes no difference whether the header is defined in the configuration. If you define any custom headers, 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 <urn:SessionHeader xmlns:urn="urn:enterprise.soap.sforce.com"><urn:sessionId>00D630000008yXI!A</urn:sessionId></urn:SessionHeader> instead of: Unescaped XML <urn:SessionHeader xmlns:urn="urn:enterprise.soap.sforce.com"<urn:sessionId>00D630000008yXI!A</urn:sessionId></urn:SessionHeader>

Field

Description

Custom SOAP Headers

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

Custom headers can be enforced by clients by setting the mustUnderstand attribute to true. If this attribute is set, then all customer headers must be defined. Incoming messages will be rejected if the mustUnderstand attribute is set and customer SOAP headers are not defined (as required by the SOAP specification). If a SOAP request contains custom SOAP headers without setting the mustUnderstand attribute, then it makes no difference whether the header is defined in the configuration.

If you define any custom headers, 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!A&lt;/urn:sessionId&gt;&lt;/urn:SessionHeader&gt;

instead of:

Unescaped XML

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

Generating the WSDL

The WSDL tab enables you to view the WSDL that will be used for this Web service.

When a web service is generated from an existing WSDL, but existing WSDL has external references to other WSDLs or schemas using absolute paths (for example, http://<server>:<port>/path/to/schema.xsd), those external schemas need to be loaded whenever the web service is reconfigured (for example, startup, RLC load, etc.). Timeouts are applied to connect them. If they are no longer available due to invalid hostnames, for example, during Rhapsody startup or RLC loading, the connection or read timeouts are reported but Rhapsody continues to startup and RLC loading. The default timeout of 10 seconds is used and the value can be changed by setting WebServicesProducerService.wsdl.timeoutInSeconds property in rhapsody.properties file.

Selecting the Generate WSDL button sends the current configuration to the engine (without checking in any changes) and generates the WSDL for that configuration. The WSDL is then cached until any changes are made to the configuration. Any errors or warnings that are found when generating the WSDL are displayed as follows: