# System Administrator’s Guide

# SOAP2SOAP Communication Services

The following section describes how to generate deploy and configure SOAP2SOAP Communication Services. These Communication Services can be created using the Platform Development Studio or directly from the Administration Console:

- About SOAP2SOAP Communication Services
- Generating and Deploying SOAP2SOAP Communication Services

- Generate a Communication Service
- Deploy a Communication Service
- Generated Artifacts for the Communication Service

- Managing and Configuring SOAP2SOAP Communication Services

- Configuration Workflow for SOAP2SOAP Plug-ins
- Provisioning Workflow for SOAP2SOAP Communication Services
- Reference: Attributes and Operations for SOAP2SOAP Plug-ins

## About SOAP2SOAP Communication Services

SOAP2SOAP communication services are generated using the Platform Development Studio or directly from the Oracle Communications Services Gatekeeper Administration console.

Based on a set of service WSDLs and callback WSDLs, a SOAP2SOAP communication service acts as a proxy service, and provides the functionality provided by the Oracle Communications Services Gatekeeper container services, such as:

- SLA enforcement
- EDR, CDR, and Alarms
- Authentication, access control, and accounting

SOAP2SOAP plug-in services can be instantiated using the plug-in manager. The plug-in instances process traffic and connects to individual network nodes. The instances are managed independently of each other.

For application-initiated requests, all requests are routed to the network node defined for the plug-in instance.

For network-triggered requests, the network-node should distinguish which application instance the request is targeted to by adding the application instance ID to the URL:

`http://<IP Address of AT server>:<port>/<context-root>_nt/<plug-in instance ID>_nt/<application instance ID>`

The endpoint at which the application instance has implemented the Web Service is provisioned: see Provisioning Workflow for SOAP2SOAP Communication Services.

If the number of HTTP requests that time-out during a certain time-period exceeds the maximum allowed, the plug-in instance is taken out of operation for a configurable time-period. The HTTP time-out behavior is valid for request between the plug-in instance and the network node. The purpose of this feature is to prevent network nodes that are malfunctioning from incoming request.

## Generating and Deploying SOAP2SOAP Communication Services

SOAP2SOAP Communication Services can be generated and deployed using the Administration console:

- Generate a Communication Service
- Deploy a Communication Service

See Generated Artifacts for the Communication Service for a description of the generated artifacts.

### Generate a Communication Service

To generate a SOAP2SOAP Communication Service from the Administration console, open the SOAP-SOAP Generation page by selecting OCSGSOAP-SOAP from the Domain Structure group and enter configuration properties for the Communication Service according to Table 33-1.

SOAP2SOAP Communication Services can also be generated using the Eclipse wizard provided with the Platform Development Studio. See section Using the Eclipse Wizard in Platform Development Studio - Developer’s Guide.

Table 33-1 SOAP-SOAP Communication Service generation fields
Field | Description
--- | ---
Name | Identifier that ties together a collection of Web Services. Will be a part of the names of the generated war and jar files and the package names for the for the Communication Service. Below is a list of the generated EARs and the WARs and JARs: wlng_at_<Communication service name>.ear: <Name>.war <Name>_callback.jar wlng_nt_<Communication service name>.ear: <Name>.war <Name>_service.jar <Name>_soap_plugin.jar
Version | The version to be used in Used in META-INF/MANIFEST.MF in the EARs for the Communication Service.
ServiceType | Defines the service type. Used in SLAs, EDRs, statistics, etc. The service type to use in the SLAs is: com.bea.wlcp.wlng.soap2soap.<ServiceType>.plugin.<interface name from WSDL> Example: SmsServiceType
ContextPath | The context path for the Web Service. Example: myService
Service WSDLs | Enter the name of and path to each WSDL file that includes the service definition to be implemented by the new Communication Service. Use one file per line. The files must reside on a file system that can be reached by the Administration server. Example: D:\standards\ParlayX2.1\wsdl\parlayx_sms_send_service_2_2.wsdl D:\standards\ParlayX2.1\wsdl\parlayx_sms_notification_manager_service_2_3.wsdl D:\standards\ParlayX2.1\wsdl\parlayx_sms_receive_service_2_2.wsdl
Callback WSDLs | Enter the name of and path to each WSDL file that includes the callback service definition to be used by the new Communication Service in sending information to the service provider’s application. Use one file per line. The files must reside on a file system that can be reached by the Administration server. Example: D:\standards\ParlayX2.1\wsdl\parlayx_sms_notification_service_2_2.wsdl

On successful generation of the Communication Service, the deployment screen is displayed, see Deploy a Communication Service.

### Deploy a Communication Service

When a SOAP2SOAP Communication Service has been generated using the Administration Console, see Generate a Communication Service the deployment screen is displayed.

When deploying directly from the Administrating console, fill in the entry fields described in Table 33-2 and click the button Deploy SOAP2SOAP. In this case, the Communication Service is deployed to the same domain as where it was generated.

Table 33-2 SOAP-SOAP Communication Service deployment fields
Field | Description
--- | ---
Name | Name of the Communication Service. Same as the name entered in the Name field in SOAP2SOAP Communication Service Screen. Do not change this.
Version | The version use when deploying the Communication Services.
UserName | User name for an Oracle Communications Services Gatekeeper administrative user.
Password | Password that corresponds to the user name.

The generated Communication Service can also be deployed using WebLogic tools, see Generated Artifacts for the Communication Service.

Once the Communication Service is deployed, create one or more plug-in instances, see Managing and Configuring SOAP2SOAP Communication Services.

### Generated Artifacts for the Communication Service

When generating a SOAP2SOAP Communication Service the following directory structure is created in the directory `$DOAMIN_HOME/soap2soap` on the Administration Server.

Listing 33-1 Directory structure when generating SOAP2SOAP Communication Services

    | +- <Communication service name>_<version>/

    | | | +- build.properties

    | | +- build.xml

    | | +- common.xml

    | | +- <Communication service name>/

    | | | | +- common/

    | | | | | +- resources/

    | | | | | | +- enabler/

    | | | | | | +- facade/

    | | | | | | +- handlerconfig.xml

    | | | | +- dist/

    | | | | | +- com.bea.wlcp.wlng.soap2soap.<service type>.store_<version>.jar

    | | | | | +- wlng_at_<Communication service name>.ear

    | | | | | +- wlng_nt_<Communication service name>.ear

    | | | | +- plugins/

    | | | | | +- soap/

    | | | | | +- tmp/

All Java source files, build files, configuration files, and deployable artefacts are created under the directory $DOMAIN_HOME/soap2soap. The source files are there mainly for reference, and the only files that are necessary to deploy the Communication Service are:

- `wlng_at_<Communication service name>.ear`
- `wlng_nt_<Communication service name>.ear`

wlng_at_<Communication service name>.ear should be deployed in the Access Tier server.

wlng_nt_<Communication service name>.ear should be deployed in the Network Tier server.

The generated Communication Service can be deployed as a part of the generation process, as described above or using standard WebLogic Server tools.

For information on how to deploy the files using WebLogic Server tools, see Deploy and Undeploy Communication Services and plug-ins.

## Managing and Configuring SOAP2SOAP Communication Services

This section contains a description of the configuration attributes and operations available for SOAP2SOAP-type of plug-in instances.

To see a | Refer to
--- | ---
Detailed list of necessary for managing and configuring a plug-in instance | Properties for SOAP2SOAP Plug-ins
Configuration workflow | Configuration Workflow for SOAP2SOAP Plug-ins
List of operations and attributes related to management and provisioning | Provisioning Workflow for SOAP2SOAP Communication Services
Reference of management attributes and operations | Reference: Attributes and Operations for SOAP2SOAP Plug-ins

### Properties for SOAP2SOAP Plug-ins

Property | Description
--- | ---
Managed object in Administration Console | <domain name>OCSG<server name>Communication Services<plug-in instance ID>
MBean | Domain=com.bea.wlcp.wlng Name=wlngt InstanceName is same as plug-in instance ID Type=com.bea.wlcp.wlng.httpproxy.management.HTTPProxyMBean
Network protocol plug-in service ID | Defined when generating the SOAP2SOAP plug-in using the Platform Development Studio. When generated fm the Administration console, the ID is <Name>_soap_plugin.
Network protocol plug-in instance ID | The ID is given when the plug-in instance is created, see Managing and Configuring the Plug-in Manager.
Supported Address Scheme | Defined when generating the SOAP2SOAP plug-in using the Platform Development Studio. When generated fm the Administration console, the address scheme is always an empty string.
North interfaces | Derived from the package name of the network protocol plug-in, as given when the plug-in was generated, and the name of the interface as defined in the WSDL. For application-initiated request: `<package name>.plugin.<Interface name>Plugin` For network-triggered requests: `<package name>.callback.<Interface name>Callback` See see Managing and Configuring the Plug-in Manager for information on how to list the interfaces.
Service type | Given when the plug-in was generated using the Platform Development Studio or the administration console.
Exposes to the service communication layer a Java representation of: | Depends on the WSDLs used.
Interfaces with the network nodes using: | The same protocol as exposed by the application-facing interfaces.
Deployment artifacts | <communication service identifier>_<protocol>_plugin.jar, <communication service identifier>_service.jar and <communication service identifier>_callback.war, packaged in wlng_nt_<communication service>.ear <communication service identifier>_callback.jar and <communication service identifier>.war, packaged in wlng_at_<communication service identifier>.ear <communication service identifier> was given in the Eclipse wizard or the Administration console when the communication service was generated. <protocol> is configurable when using the Eclipse wizard. If the Communication Service was generated using the Administration console, it is always `soap`.

### Configuration Workflow for SOAP2SOAP Plug-ins

Below is an outline for configuring the plug-in using the Oracle Communications Services Gatekeeper Administration Console:

1. Create one or more instances of the plug-in service: see Managing and Configuring the Plug-in Manager. Use the plug-in service ID as detailed in Properties for SOAP2SOAP Plug-ins.
2. Using the Management Console or an MBean browser, select the MBean for the plug-in instance. The MBean display name is the same as the plug-in instance ID given when the plug-in instance was created.
3. Configure the authentication credentials to be used by the plug-in towards the network node:

- Attribute: UserName
- Attribute: Password

4. Specify which authentication method to use towards the network node:

- Attribute: HttpBasicAuthentication
- Attribute: UserNameTokenAuthentication

5. Specify the URL of the network node to connect to:

- Attribute: UserNameTokenAuthentication

6. Specify the HTTP time-out behavior:

- Attribute: HttpTimeoutPeriod
- Attribute: HttpTimeoutThreshold
- Attribute: HttpWaitTime
- Attribute: ReactivateTime

7. Specify heartbeat behavior, see Configuring Heartbeats.
8. Set up the routing rules to the plug-in instance: see Configuring the Plug-in Manager. Use the plug-in instance ID and address schemes detailed in Properties for SOAP2SOAP Plug-ins.

Note: | If the SOAP2SOAP plug-in is the only plug-in for the service enabler, routing based on destination address is not applicable. All requests will be routed to the plug-in instance. If there are other, non-SOAP2SOAP, plug-ins in the service enabler, the routing applies.

9. Provide the administrator of the network node server with the URL to which it should deliver network-triggered requests. The default URL is

`http://<IP Address>:<port>/<context-root>_nt/<plug-in instance ID>/<application instance ID>`

default `<context-root>` is the communication service ID, as specified when the communication service was generated.

`<plug-in instance ID>` is the ID of the plug-in instance. The network node is assumed to specify which application instance the request is targeted to by adding the application instance ID as the suffix in the URL.

10. If desired, create and load a node SLA, see:

Defining Global Node and Service Provider Group Node SLAs

Managing Application SLAs

Continue with the provisioning of service provider accounts and application accounts.

### Provisioning Workflow for SOAP2SOAP Communication Services

For each application that uses SOAP2SOAP communication services and supports network-triggered requests, a mapping must be set up between the application instance ID and the URL for the Web service this application instance implements. Use the following operations to manage the callback URLS for the application instances:

- Operation: addApplicationEndPoint
- Operation: getApplicationEndPoint
- Operation: listApplicationEndPoints
- Operation: removeApplicationEndPoint

### Reference: Attributes and Operations for SOAP2SOAP Plug-ins

Below is a list of attributes and operations for configuration and maintenance:

- Attribute: HttpBasicAuthentication
- Attribute: HttpTimeoutPeriod
- Attribute: HttpTimeoutThreshold
- Attribute: HttpWaitTime
- Attribute: NetworkEndpoint
- Attribute: Password
- Attribute: UserName
- Attribute: ReactivateTime
- Attribute: UserNameTokenAuthentication
- Operation: addApplicationEndPoint
- Operation: getApplicationEndPoint
- Operation: listApplicationEndPoints
- Operation: removeApplicationEndPoint

### Attribute: HttpBasicAuthentication

Scope: Cluster

Unit: n/a

Format: Boolean

Specifies whether HTTP Basic Authentication shall be used when authenticating with the network node. Enter:

- `true` to use HTTP Basic Authentication
- `false` to not.

### Attribute: HttpTimeoutPeriod

Scope: Cluster

Unit: Seconds

Format: int

Specifies a time period during which a number of HTTP time-outs are counted.

### Attribute: HttpTimeoutThreshold

Scope: Cluster

Unit: n/a

Format: int

Specifies the number of HTTP time-outs allowed during a time-period. The time-period is specified in Attribute: HttpTimeoutPeriod.

If the number of time-outs are exceed, the plug-in instance transfers to state disconnected, which means that it does not accept new requests. It stays disconnected during the time-period defined in Attribute: ReactivateTime.

### Attribute: HttpWaitTime

Scope: Cluster

Unit: seconds

Format: Int

Specifies the HTTP time-out value. If this value is exceeded, the request is considered to be lost and the counter that tracks the number of requests that encountered HTTP time-outs is increased.

### Attribute: NetworkEndpoint

Scope: Cluster

Unit: n/a

Format: String

Specifies the URL to the network node.

### Attribute: Password

Scope: Cluster

Unit: n/a

Format: String

Specifies the password to use when connecting to the network node.

### Attribute: ReactivateTime

Scope: Cluster

Unit: seconds

Format: int

Specifies the time a plug-in instance is kept in state disconnected when the number of HTTP time-outs have exceeded the maximum number, specified in Attribute: HttpTimeoutThreshold, over a time-period, specified in Attribute: HttpTimeoutPeriod.

### Attribute: UserName

Scope: Cluster

Unit: n/a

Format: String

Specifies the username to use when connecting to the network node.

### Attribute: UserNameTokenAuthentication

Scope: Cluster

Unit: n/a

Format: Boolean

Specifies whether Web Services Security Username Token shall be used when authenticating with the network node.

- `True` to use UserName Token Authentication
- `False` to not.

### Operation: addApplicationEndPoint

Scope: Cluster

Adds the URL to which network-triggered requests per application instance should be forwarded. The application is assumed to implement the callback web service on this URL.

Signature:

    addApplicationEndPoint(AppinstanceId: String, CallbackUrl: String)

Table 33-3 addApplicationEndPoint
addApplicationEndPoint |
--- | ---
Parameter | Description
AppinstanceId | The application instance ID associated with the callback URL.
CallbackUrl | The URL to the implementation of the application instance’s implementation of the callback.

### Operation: getApplicationEndPoint

Scope: Cluster

Displays the URL to which network-triggered requests for a given application instance should be forwarded.

Signature:

    getApplicationEndPoint(AppinstanceId: String)

Table 33-4 getApplicationEndPoint
getApplicationEndPoint |
--- | ---
Parameter | Description
AppinstanceId | The application instance ID associated with the callback URL.

### Operation: listApplicationEndPoints

Scope: Cluster

Displays a list of all registered callback URLS.

Signature:

    listApplicationEndPoints()

Table 33-5 listApplicationEndPoints
listApplicationEndPoints |
--- | ---
Parameter | Description
- | -

### Operation: removeApplicationEndPoint

Scope: Cluster

Removes the URL to which the network-triggered requests for a given application instance are forwarded.

Signature:

    removeApplicationEndPoint(AppinstanceId: String)

Table 33-6 removeApplicationEndPoint
removeApplicationEndPoint |
--- | ---
Parameter | Description
AppinstanceId | The application instance ID associated with the callback URL.