Copyright © Cloud Software Group, Inc. All Rights Reserved

Service

Shared Configuration

A Service shared configuration resource describes an interface and its associated operations. The also specifies a set of endpoint bindings that expose the service to potential clients over specific transports.

The user interface for the Service shared configuration resource can change depending upon the additional products you have installed. For example, the TIBCO BusinessWorks BPEL Extension offers more options when configuring the Service resource. When you install a product that extends the Service resource, a new field named Implementation Type appears that allows you to specify the type of service you want to configure depending upon the product you select. See the documentation for the products you have installed for more information about configuring a Service resource using those products. This section describes the base TIBCO ActiveMatrix BusinessWorks Service resource.

Before creating a Service resource, you will need to create the following resources:

•	A WSDL file that contains an abstract interface description. The interface can include one or more operations.

•	Process definitions will provide the implementation for each operation in the service’s interface. You can specify the same process definition for more than one operation.

•	Either an HTTP Connection or JMS Connection shared configuration resource that specifies the transport used by clients of the service.

•	If you want to pass context information from the incoming request (for example, user name or security certificate), create a Context Resource that specifies the context data you want to use.

During deployment, Service resources must be added to a Process Archive. Although it is possible to add a Service resource to a Shared archive, the resource will not properly function when located in a Shared Archive. Add your Service resources only to Process Archives. Also when creating your enterprise archive file, the menu item Tools > Create Project EAR only adds processes with process starters to the Process Archive for the project. You must add any Service resources to the Process Archive by selecting the Processes tab and clicking the Add a Process Starter to this archive button.

To define a Service resource, follow this general procedure:

1.	Provide an abstract WSDL file (see WSDL) that describes the interface to the service.

2.	For each operation in the interface, specify a process definition that implements the operation.

3.	Specify one or more endpoint bindings to expose the service to potential clients.

4.	For each endpoint binding, specify a transport configuration (either HTTP Connection or JMS Connection).

5.	Specify any transport-specific information, such as endpoint URL for HTTP transports or JMS Destination Name for JMS transports.

6.	Specify any SOAP details, such as SOAP Version or encoding for each operation.

7.	Specify attachments, headers, or context information for input and output messages, if necessary.

Only Bytes Message must be used when using MTOM attachments.

See TIBCO ActiveMatrix BusinessWorks Process Design for more information about services.

Configuration

The Configuration tab has the following fields.

Field	Global Var?	Description
Name	No	The name to appear as the label for the resource.
Description	No	Short description of the resource.
Enable for AMX	No	Selecting this check box allows you to configure this Service resource in ActiveMatrix. It also allows you to configure an ActiveMatrix endpoint for the existing services. Note: Select this check box only if you want to expose your Service to the ActiveMatrix world. If this check box is checked and unchecked, you will loose the Partner Link Configuration information from the partner binding table. Tabs visible after selecting the check box are: • Services • References • Properties • WSDL Source • Overview Following tabs are visible when this check box is not selected (by default): • Configuration • Partner Binding • WSDL Source • Overview
Implementation	No	This field allows you to add abstract WSDL files that describe the service. Click the + button to add a WSDL file. Click the X button to remove a WSDL file. Click the Rename Current Service Port to change the name of the currently selected service port.
Service Port Sub-Tabs Each service port will have a sub-tab containing the configuration for the service port.
Interface Namespace	No	Namespace for the interface file of the service. You can click the Go To Referenced Resource to view the interface file.
Operations Sub-Tab This sub-tab contains a table of all operations defined in the interface file. This table allows you to specify the resource that implements each operation.
Operation Name	No	Name of the operation. This column is a read-only list of operations contained in the interface file.
Operation Implementation	No	Double click on this field and use the Browse button to locate the resource that implements each operation. Process definitions that implement an operation must have an input, output, and error schemas that match the input, output, and fault messages of the operation. You can leave the implementation for an operation unspecified. In this case, an exception is thrown when a client attempts to invoke the unimplemented operation. Note: You can drag and drop a process definition from the project tree to the operation implementation cell. If the signature of the operation matches the process definition, the process be inserted. If the process definition or the WSDL changes, the icon for the process definition in the cell changes to a warning triangle indicating the operation and implementation signatures no longer match.
Endpoint Bindings Sub-Tab This sub-tab allows you to specify one or more endpoints that expose the service as well as the transport bindings for each endpoint. Use the + button to add endpoints, use the X button to delete endpoints, and use the arrow buttons to move the selected endpoint in the list.
Endpoint Name	No	Specify a name for the endpoint in this field.
Endpoint Type	No	Specify the type of endpoint by selecting from the list of types. • Local — A local endpoint is available to consumers within the same process engine. This type of endpoint provides a highly efficient way for local services to invoke each other without incurring the overhead of using a network transport. • SOAP — A SOAP endpoint is used to expose the service by way of the SOAP protocol to other partner services or web clients
Transport Sub-Tab
Transport	No	Use the Browse button to select a transport. In this release, HTTP Connection or JMS Connection resources can be used as transports.
Use Basic Authentication	Yes	This field is available when an HTTP transport is selected. When checked, this field specifies that incoming SOAP requests must supply a valid username and password. The user name and password specified in the incoming request must exist in the domain (users are created and managed in the domain using TIBCO Administrator).
Endpoint URI	No	This field is available when an HTTP transport is selected. This field specifies the Endpoint URI that clients can use to access the service.
JMS Destination	Yes	This field is available when a JMS transport is selected. This field specifies the name of the destination for incoming JMS messages for this service. The syntax of the destination name is specific to the JMS provider you are using. See your JMS provider documentation for more information about destination names. Note: If you are using TIBCO Enterprise Message Service as your JMS provider, you can use the Browse button next to this field after specifying a valid connection in the JMS Connection field. The Browse button displays a list of configured destinations in the JMS server that are appropriate for this activity.
JMS Destination Type	No	This field is available when a JMS transport is selected. This field specifies whether the JMS Destination is a Topic or a Queue.
JMS Message Type	No	This field is available when a JMS transport is selected. This field specifies the type of incoming messages on the specified destination. It can be either Text Message or Bytes message.
Enable W3C SOAP JMS 1.0 Compliance	No	Select the check box to comply with the W3C SOAP Over JMS 1.0 specification. By default, the check box is not selected and the service complies with the TIBCO specifications.
Target Service		This field is available when a JMS transport is selected. This field is available only when the check box Enable W3C SOAP JMS 1.0 Compliance is selected. Specify the target service value, if any. Note: If Target Service is configured, the value is reflected in the WSDL as a query parameter.
Reply Using Incoming Delivery Mode	No	This field is available when a JMS transport is selected. Select the check box if you want to send the reply using the incoming delivery mode. By default, the check box is not selected.
JMS Delivery Mode (Response)	Yes	This field is available when the Reply using Incoming Delivery Mode field is not selected. The delivery mode of the response message. Can be one of the following: • PERSISTENT: signifies the messages are stored and forwarded. • NON-PERSISTENT : messages are not stored and may be lost due to failures in transmission. • TIBCO EMS Reliable : this mode is only available when using TIBCO Enterprise Message Service. See the TIBCO Enterprise Message Service documentation for more information about this mode. By default, the field selection is PERSISTENT.
Acknowledge Mode	No	This field is available when a JMS transport is selected. This field specifies the acknowledgment mode to be used for incoming messages. It can be one of the following: • Auto : the message is automatically acknowledged when it is received. • Client: the message is acknowledged when the process implementing the operation ends successfully. • Dups OK : the message is acknowledged automatically when it is received. JMS provides this mode for lazy acknowledgment, but TIBCO ActiveMatrix BusinessWorks acknowledges messages upon receipt. • TIBCO EMS Explicit : (only available for TIBCO Enterprise Message Service) a message which is not acknowledged using the Confirm activity before the process instance ends, are redelivered instead of all messages in the session. The session is not blocked and one session handles all incoming messages for each process instance. Note — In the TIBCO ActiveMatrix BusinessWorks 5.10 release, a change occurs in the behavior of this feature. Now only the messages that are not confirmed, are redelivered. • TIBCO EMS Explicit Dups OK : (only available for TIBCO Enterprise Message Service) a message which is not acknowledged using the Confirm activity before the process instance ends, are redelivered instead of all messages in the session. The session is not blocked and one session handles all the incoming messages for each process instance. The messages however, would be lazily acknowledged.
JMS Application Properties		This field is available when a JMS transport is selected. Any application-specific message properties that is part of the message. This is specified by the JMS Application Properties shared configuration object.
JMS Application Properties (Response)		This field is available when a JMS transport is selected. Any application-specific message properties that is part of the response message. This is specified by the JMS Application Properties shared configuration object.
Max Sessions	No	This field is available when a JMS transport is selected and Client is selected as the Acknowledge Mode. If the JMS Destination Type is Topic, this field is read-only. If the JMS Destination Type is Queue, the value of this field can be altered. This field specifies the maximum number of JMS sessions to create for incoming queue messages. When a JMS queue message is received, the session is blocked until the message is acknowledged. Because the acknowledgment can come at a later time when the process ends, this field allows you to specify a maximum number of new sessions to be created for handling incoming messages. Once the maximum number of sessions is reached, no new incoming messages can be processed. Once an incoming message is confirmed, the total number of active sessions is decreased and another incoming message can be processed.
Operations	No	The operation that this process definition implements. The drop-down list in this field is populated with the operations contained in the specified port type in the specified WSDL. You can choose one operation to implement per process definition. If you want to implement multiple operations, you must create a process definition for each.
SOAP Details Sub-Tab
Default Style	No	The SOAP binding style for operations that do not explicitly set their binding style. You can specify either Document or RPC style.
SOAP Version	No	Specify either SOAP 1.1 or SOAP 1.2 for the version of the SOAP specification to which incoming messages should comply. See SOAP Specification Compliance for more information.
Operations	No	Select each operation from the drop down list to specify the SOAP Action, Style, or Encoding for the operation.
SOAP Action	Yes	The soapAction that is expected from incoming SOAP requests. This field is required, and by default, the operation name is used as the soapAction. Each operation in an interface must have a unique value for SOAP Action. See the SOAP specification for more information about soapAction.
Style	No	The SOAP binding style for the selected operation. You can specify either Document or RPC style, or you can specify that the value in the Default Style field should be used.
Encoding	No	The encoding type for the body of the SOAP input and output messages. This can be either literal or encoded. Encoded messages support more complex datatypes such as SOAP arrays. When encoded is specified, you can optionally specify the namespace for input, output, and fault messages.
Input Message Namespace	No	The namespace for input messages.
Output Message Namespace	No	The namespace for output messages.
Fault Message Namespace	No	The namespace for fault messages.

Advanced SOAP Settings

For each operation, you can specify advanced configuration options. To access the advanced configuration options, perform the following:

1.	Click the Endpoint Bindings Tab.

2.	Select the desired endpoint and click the SOAP Details sub-tab.

3.	Select the operation in the Operations field.

4.	Click the Advanced button next to the operation name.

The Advanced SOAP Settings dialog appears. The following sections describe the tabs on this dialog.

Input Attachments

See Messages With Attachments for more information about message attachments.

The Input Attachments tab has the following fields.

Field	Description
Mime Content Type	The table containing this column allows you to specify the mime content type of each message part. This is especially useful for describing parts that contain attachments. See the mime specification for more information on the valid syntax of the content type. If specified, the content type appears in the WSDL for the specified part. Use the X, +, and arrow keys to delete, add, and move parts in the list.
Message Part	The message part that you would like to specify the content type for. This field is a drop down list of message parts.
Write to File	Checking this field specifies that incoming messages whose attachments exceed the specified threshold size should be written to a file instead of stored in memory. This allows you to accept large incoming attachments without consuming a great deal of memory. When this field is checked, the Directory and Threshold Size fields appear. Leaving this field unchecked specifies that attachments of incoming messages should be kept in memory. Once written, the files created by using this option are not deleted automatically. You must manage the storage used by these files and delete them when they are no longer used. Although Write to File exists for SwA and MTOM, Soap over JMS completely depends on the heap size configuration as JMS specifications do not support writing JMS messages in parts as is the case with Soap over HTTP, which can be written over wire in parts. Hence, writing large JMS messages to JMS after configuring Write to File, completely depends on the Heap size.
Directory	This field only appears when the Write to File field is checked. The directory to write attachments that are above the specified threshold. The process engine does not attempt to create the directory if the specified directory does not exist. Therefore, create the directory before starting the process engine.
Threshold Data Size (bytes)	This field only appears when the Write to File field is checked. The maximum size (in bytes) of an incoming message attachment that can be kept in memory. Attachments larger than the specified size are written to a file in the specified directory. The file’s name is output so that subsequent activities in the process definition can access the file and read its contents. Specifying zero (0) in this field causes all incoming messages to be saved to a file.

Input Headers

The Input Headers tab allows you to specify a SOAP message parts used for any SOAP headers expected in the incoming request. The specified input headers are also included in the concrete bindings in the generated WSDL file.

Use the +, X, and arrow keys to add, delete and move the input header messages in the list.

The Input Headers tab has the following fields.

Field	Description
Message Name	The message in a WSDL file to use as the input header for the incoming SOAP request. This WSDL file does not have to be the same as the file used for output headers or the file used to configure the port type and operation of the incoming request. Use the Browse button in this field to search for valid WSDL File resources and to select the desired message in the WSDL File.
Part Name	This field contains a drop down list with all parts of the specified SOAP message. You can specify a namespace or encoding for the part, if applicable.
Namespace	Namespace for the selected input header message.
Encoding	Encoding to use for the selected input header message.
Undescribed	Select this check box to declare the header as Undescribed header.
Cardinality	This field contains a drop-down list with two options: Repeating and Optional.

Output Attachments

See Messages With Attachments for more information about message attachments.

The Output Attachments tab has the following fields.

Field	Description
Attachment Style	This field allows you to choose the attachment style for the outbound/response messages. Two attachment styles are available: SwA and MTOM.
Attachments
Mime Content Type	The table containing this column allows you to specify the mime content type of each message part. This is especially useful for parts that contain attachments. See the mime specification for more information on the valid syntax of the content type. If specified, the content type appears in the WSDL for the specified part. Use the X, +, and arrow keys to delete, add, and move parts in the list.
Message Part	The message part that you would like to specify the content type for. This field is a drop down list of message parts.

Output Headers

The Output Headers tab allows you to specify a SOAP message parts used for any SOAP headers expected in the outgoing reply. The specified output headers are also included in the concrete bindings in the generated WSDL file.

Use the +, X, and arrow keys to add, delete and move the input header messages in the list.

The Output Headers tab has the following fields.

Field	Description
Message Name	The message in a WSDL file to use as the output header for the SOAP request. This WSDL file does not have to be the same as the file used for input headers or the file used to configure the port type and operation of the incoming request. Use the Browse button in this field to search for valid WSDL File resources and to select the desired message in the WSDL File.
Part Name	This field contains a drop-down list with all parts of the specified SOAP message. You can specify a namespace or encoding for the part, if applicable.
Encoding	Encoding to use for the selected output header message.
Undescribed	Select this check box to declare the header as Undescribed header.
Cardinality	This field contains a drop-down list with two options: Repeating and Optional.

Fault Headers

This Fault Headers tab enables the user to configure headers for declared faults. With this you will be able to configure different schemas to be mapped to the headers for different Fault messages.

This Fault Headers tab has the following fields.

Field	Description
soapFaults	The Faults available for configuration are listed in the soapFaults drop-down.
Part Name	This field contains a drop-down list with all parts of the specified soapFault message.
Message Name	The message in a WSDL file to use as the fault header for the incoming soapFault request. Use the Browse button in this field to search for valid WSDL File resources and to select the desired fault message in the WSDL File.

Input Context

The Input Context tab allows you to specify a Context Resource that contains transport-specific data. The data you provide to the context resource is available to the process definition that implements the operation.

The Input Context tab has the following fields.

Field	Description
Shared Context	The Context Resource that specifies the schema you want to use. The schema of this resource should include elements for each data element from the transport information you want to provide to a process definition that implements the operation.
Expose Security Context	This field is available for either HTTP or JMS transports. This field is only available when a Context resource is specified in the Shared Context field. Places the information from the user’s security context (either authentication or SSL certificate information) into the Context/SecurityContext element of the Input Context. This is a fairly expensive operation and SSL certificates can consume memory resources, so check this option only if you require information from the user’s security context for later use in your process definition.
Mapping Panel	The mapping panel is similar to the mapping panel provided in the Input tab of activities. This panel allows you to map transport-specific information from the incoming request to the data elements of the specified Context Resource. The mapping panel appears only when a Context resource is specified in the Shared Context field. See TIBCO ActiveMatrix BusinessWorks Process Design for more information about mapping and transforming input data.

When the Expose Security Context field is checked, the following schema is available in the Mapping Panel field.

Element	Datatype	Description
Context	complex	This element holds the optional SecurityContext element and the RemoteAddress and RemoteHost elements described below.
SecurityContext	complex	This output element is only available when the Expose Security Context field is checked on the Configuration tab. This element contains information about the requestor’s authentication or certificate information, depending upon the security scheme used. See the description of the following elements contained in the SecurityContext element for more information.
Transport	complex	This element is only available when HTTP is the transport, this element is not available when JMS is the transport. This element contains the transport-level security context. This includes the following: • CertificateToken— complex element containing the subject, issuer, serial number, fingerprint, and X509 certificate. • UsernameToken — complex element containing the username, password, and nonce (random number, if one is set by the calling application).
WSSE	complex	This element contains the WSS policy security context. This includes the Authentication and Signature elements. See the description of these elements below.
Authentication	complex	This element contains the authentication information from the client. The type of information in this elements depends upon how the client authenticated. This element can contain one of the following: • UsernameToken — complex element containing the username, password, and nonce (random number, if one is set by the calling application). • KeyInfo — the client’s public key.
Signature	complex	This element contains information from the user’s digital signature. This element contains the following: • Value — this element contains the raw signature sent by the client. • Token — either a UsernameToken or a KeyInfo element. A UsernameToken element contains the username, password, and nonce, if available. A KeyInfo element contains information about the client’s digital certificate or public key.
RemoteAddress	String	IP address of the remote host that sent the HTTP request. This element is only available when HTTP is the specified transport. This element is not available for the JMS transport.
RemoteHost	String	Host name of the remote host that sent the HTTP request. This element is only available when the Enable DNS Lookups field is checked on the Advanced tab of the HTTP Connection used by this activity. This element is only available when HTTP is the specified transport. This element is not available for the JMS transport.

Output Context

The Output Context tab allows you to specify a Context Resource that contains data the process definition implementing the operation has provided. The data can then be mapped to Headers of the output message returned to the client.

The Output Context tab has the following fields.

Field	Description
Shared Context	The Context Resource that specifies the schema you want to use. The schema of this resource should include elements for each data element you want to provide to the output Headers for the message.
Mapping Panel	The mapping panel is similar to the mapping panel provided in the Input tab of activities. This panel allows you to map data provided by the implementation of the operation to the transport-specific headers of the reply message sent to the client. The mapping panel appears only when a Context resource is specified in the Shared Context field. See TIBCO ActiveMatrix BusinessWorks Process Design for more information about mapping and transforming input data.

Fault Context

The Fault Context tab allows you to select a fault context resource that is set with SOAP fault attributes. The data can then be mapped to Fault Elements of the Fault message returned to the client.

The Fault Context tab has the following fields.

Field	Description
Shared Context	The Context Resource that specifies the SOAP fault schema you want to use for mapping with the Fault Elements.
Mapping Panel	The mapping panel is similar to the mapping panel provided in the Input tab of activities. This panel allows you to map data provided by the implementation of the operation to the transport-specific Fault Elements of the fault message sent to the client. The mapping panel appears only when a Context resource is specified in the Shared Context field. The Context Data shows the Context resource element.

 

Partner Binding

The Partner Binding tab allows you to bind partners invoked by all operations in a service on the Partner Binding tab of the Service. Only partners that require binding appear on this tab. The Partner Binding tab has the following fields:

Field	Description
Partner Bindings	The Partner Bindings field allows you to specify binding information for partner definitions. The Partner Name and Process fields in the table are non-editable. Partner Name - name of the partner as specified in the Process Definition. Process - The process in which the partner is declared. PortType Namespace - is a non-editable field displaying the PortType Namespace corresponding to the Port Type selected. Partner Link - the partner link configuration for the partner. This field can optionally be specified by double-clicking on the field and browsing the list of available partner link resources in the project.
Dynamic Call Processes	The Dynamic Call Processes field allows you to specify a list of processes that can be dynamically invoked by processes invoked by all operations in the service. You can add or remove processes from the list.

Processes declared in the Dynamic Call Processes field are automatically included in Enterprise Archive (EAR) files.

WSDL Source

The WSDL Source tab displays the concrete WSDL interface file that is generated based on the information specified on the Configuration tab of this resource. This tab has the following fields.

Field	Global Var?	Description
Service URI	No	The Service URI portion of the URL that can be used to retrieve the WSDL file. For clients to retrieve WSDL files from TIBCO ActiveMatrix BusinessWorks, you must define a process definition that accepts HTTP requests and uses the Retrieve Resources activity to generate the WSDL file. See Using Retrieve Resources for more information. The URL to retrieve WSDL files is the following:   http://<host>:<port>/<serviceURI>?wsdl where <serviceURI> is the value in this field.
Target Namespace	No	Target namespace of the Service. Note: The Target Namespace of the service should be an abstract WSDL if embedding Interface or Types.
Embed In WSDL	No	Check one or more of the following to embed the selected item(s) in the concrete WSDL file instead of using import statements: • Interface — When checked, specifies that all referenced WSDL files should be included inline in the concrete WSDL file. Otherwise, all referenced WSDL files are imported. Note: To use Abstract WSDL in the Partners tab of the Client Process Definition containing Invoke Partner activity, uncheck Interface. • Types — When checked, specifies that all referenced XSD files should be included inline in the concrete WSDL file. Otherwise, all referenced XSD files are imported. • JNDI Properties — When checked, specifies that JDNI properties should be included inline in the service specification in the WSDL Source tab.
WSDL Code	No	This field displays the concrete WSDL file that describes this service. Click the Save WSDL File button to save the concrete WSDL file to disk, if desired.

Overview

The Overview tab provides a tree view of the service that you can expand and collapse to view the exposed endpoints and operations for the service.

Copyright © Cloud Software Group, Inc. All Rights Reserved