wsadmin (Jython) scripting procedures for CEA

The Communications Enabled Applications (CEA) samples package includes a wsadmin (Jython) script library to simplify the development and testing of scripts to automate related configuration changes. The script library is provided as a samples, and as such, IBM has no obligation to provide maintenance, support, updates, enhancements or modifications.

The script library file, AdminCEA.py, is located in the scripts directory of the CEA samples package. Refer to the Samples section in the information center for instructions to obtain the CEA samples package.

The AdminCEA.py script library file includes following procedures that we can use to manage CEA settings:

• showCEASettingsForCell

• configureCEASettingsForCell

• showCEASettingsForServer

• configureCEASettingsForServer

• showCEASettingsForCluster

• configureCEASettingsForCluster

The AdminCEA.py file also includes the following procedures that we can use to manage SIP application routers:

• showAllRouters

• showDefaultRouter

• showAllCustomRouters

• showCustomRouters

• createRouter

• modifyRouter

• deleteRouter

• moveServerToCustomRouter

• moveServerToDefaultRouter

• moveClusterToCustomRouter

• moveClusterToDefaultRouter

Add AdminCEA.py to WebSphere Application Server

To add AdminCEA.py to WebSphere Application Server...

1. Create the following directory:
   app_server_root/scriptLibraries/communications/V80

2. Copy AdminCEA.py file to the directory created in the previous step. The next time that you start wsadmin, the new procedures are automatically sourced into wsadmin shell.

Use the procedures

To use one or more of these procedures, call the appropriate procedures from within our script; for example:

AdminCEA.moveServerToCustomRouter("localhostNode01", "server1", "RouterOne")

To learn more about creating wsadmin scripts, see the scripting the application serving environment (wsadmin) information.

Procedures for configuring CEA settings

showCEASettingsForCell

Use this procedure to show the context root and virtual host for the CEA communications service application. Use the configureCEASettingsForCell procedure to learn about each setting.

Syntax

showCEASettingsForCell()

Example usage

showCEASettingsForCell()

configureCEASettingsForCell

Use this procedure to define the context root and virtual host for the CEA communications service application.

Syntax

configureCEASettingsForCell(context_root, virtual_host)

context_root

Context root of the REST interface. Use this option to assign a different context root to the REST interface. The context root is combined with the defined servlet mapping for the REST interface to compose the full URL that users type to make a REST request. For example, if the context root is /gettingstarted and the servlet mapping is CommServlet/call, then the URL is http://host:port/gettingstarted/CommServlet/call.

virtual_host

Name of the virtual host to which the REST interface is currently mapped.

Example usage

configureCEASettingsForCell("\commsvc.rest", "default_host")

(zos)

configureCEASettingsForCell("/commsvc.rest", "default_host")

showCEASettingsForServer

Use this procedure to show the state of the CEA communications service application, REST interface maximum hold time, telephony access method, and related telephony interface settings for a specific server. Use the configureCEASettingsForServer procedure to learn about each setting.

Syntax

showCEASettingsForServer(node, server_name)

node

Node on which the server is located.

server_name

Name of the server that you are using this procedure to manage.

Example usage

showCEASettingsForServer(localhostNode01,server1)

configureCEASettingsForServer

Use this procedure to define the state of the CEA communications service application, REST interface maximum hold time, telephony access method, and related telephony interface settings for a specific server.

Syntax

configureCEASettingsForServer(node, server_name, enable_CEA, max_request_hold_time, telephony_access_method, gateway_address, gateway_port, gatewayProtocol, extract_username_from_request, super_username, third_party_WSDL_provider))

node

Node on which the server is located.

server_name

Name of the server that you are using this procedure to configure.

enable_CEA

Specifies to enable CEA. Valid values are true and false. The default value is false.

max_request_hold_time

Time in seconds in which a GET /event call to the REST interface waits for new or changed data or status before timing out. The default value is 30.

telephony_access_method

Whether to use a SIP CTI gateway or a third-party WSDL provider for telephony access. Valid values are SIP_CTI_GATEWAY and THIRD_PARTY_WEB_SERVICE. The default value is SIP_CTI_GATEWAY.

gateway_address

Address or fully qualified domain name, FQDM, of the CTI gateway we want connected to by the CEA service. The default value is localhost.

gateway_port

Port of the CTI gateway to be connected to by the CEA service. The default value is 5060.

gatewayProtocol

Protocol to be used when connecting to the CTI, TR/87, gateway. Valid values are TCP, UDP, and TLS. The default value is TCP.

extract_username_from_request

Specifies to extract the user name from the HTTP request. Valid values are true and false. The default value is false.

When this functionality is enabled, an attempt is made to extract the user name from the HTTP request. If the name cannot be extracted, the Superuser name is used. This name is used when opening a new TR/87 session to the CTI gateway.

Avoid trouble: After you enable the Extract user name from request option, an attempt is made to extract the user name from the HTTP request. However, the user name has a null value even for authenticated users. The CEA Rest Service Servlet is an unprotected URI. Thus, we also must enable the Use available authentication data when an unprotected URI is accessed option. Use the console to enable the Use available authentication data when an unprotected URI is accessed option under Security > Global security > Web and SIP security > General settings. After you enable this option, the user name is available to the CEA Rest Service Servlet during the request.gotcha

super_username

Name used when opening a new TR/87 session to the configured CTI gateway. This requires that the CTI gateway be configured with a superuser account used to create phone calls on behalf of all end users. The default value is ceauser.

third_party_WSDL_provider

Specifies to use a third-party Web services provider for telephony access. Instead of using SIP CTI, this approach uses a third-party service that has implemented specific Web services to utilize a different method to connect to the telephony infrastructure.

Example usage

configureCEASettingsForServer("localhostNode01", "server1", "false | true", "30", "SIP_CTI_GATEWAY | THIRD_PARTY_WEB_SERVICE", "localhost", "5060", "TCP | UDP | TLS", "false | true", "ceauser", '""')

showCEASettingsForCluster

Use this procedure to show the state of the CEA communications service application, REST interface maximum hold time, telephony access method, and related telephony interface settings for a specific cluster. Use the configureCEASettingsForCluster procedure to learn about each setting.

Syntax

showCEASettingsForCluster(cluster_name)

cluster_name

Name of the cluster that you are using this procedure to manage.

Example usage

showCEASettingsForCluster("cluster1")

configureCEASettingsForCluster

Use this procedure to define the state of the CEA communications service application, REST interface maximum hold time, telephony access method, and related telephony interface settings for a specific cluster.

Syntax

configureCEASettingsForCluster(cluster_name, enable_CEA, max_request_hold_time, telephony_access_method, gateway_address, gateway_port, gatewayProtocol, extract_username_from_request, super_username, third_party_WSDL_provider))

cluster_name

Name of the cluster that you are using this procedure to configure.

enable_CEA

Specifies to enable CEA. Valid values are true and false.

max_request_hold_time

Time in seconds in which a GET /event call to the REST interface waits for new or changed data or status before timing out. The default value is 30.

telephony_access_method

Specifies to use the SIP CTI gateway for telephony access. Valid values are true and false.

gateway_address

Address or fully qualified domain name, FQDM, of the CTI gateway we want connected to by the CEA service. The default value is localhost.

gateway_port

Port of the CTI gateway to be connected to by the CEA service. The default value is 5060.

gatewayProtocol

Protocol to be used when connecting to the CTI, TR/87, gateway. Valid values are TCP, UDP, and TLS. The default value is TCP.

extract_username_from_request

Specifies to extract the user name from the HTTP request. When enabled, an attempt is made to extract the user name from the HTTP request. If the name cannot be extracted, the Superuser name is used. This name is used when opening a new TR/87 session to the CTI gateway. Valid values are true and false. The default value is false.

Avoid trouble: After you enable the Extract user name from request option, an attempt is made to extract the user name from the HTTP request. However, the user name has a null value even for authenticated users. The CEA Rest Service Servlet is an unprotected URI. Thus, we also must enable the Use available authentication data when an unprotected URI is accessed option. Use the console to enable the Use available authentication data when an unprotected URI is accessed option under Security > Global security > Web and SIP security > General settings. After you enable this option, the user name is available to the CEA Rest Service Servlet during the request.gotcha

super_username

Name used when opening a new TR/87 session to the configured CTI gateway. This requires that the CTI gateway be configured with a superuser account used to create phone calls on behalf of all end users. The default value is ceauser.

third_party_WSDL_provider

Specifies to use a third-party Web services provider for telephony access. Instead of using SIP CTI, this approach uses a third-party service that has implemented specific Web services to utilize a different method to connect to the telephony infrastructure.

Example usage

configureCEASettingsForCluster("cluster1", "false | true", "30", "SIP_CTI_GATEWAY | THIRD_PARTY_WEB_SERVICE", "localhost", "5060", "TCP | UDP | TLS", "false | true", "ceauser", '""')

Procedures for managing SIP application routers

showAllRouters

Use this procedure to show the targets assigned to the default SIP application router and the startup order (weight) of the applications deployed on each target, as well as the targets assigned to each custom SIP application router.

Syntax

showAllRouters()

Example usage

showAllRouters()

showDefaultRouter

Use this procedure to show the targets assigned to the default SIP application router and the startup order (weight) of the applications deployed on each target.

Syntax

showDefaultRouter()

Example usage

showDefaultRouter()

showAllCustomRouters

Use this procedure to show the targets assigned to each custom SIP application router.

Syntax

showAllCustomRouters()

Example usage

showAllCustomRouters()

showCustomRouters

Use this procedure to show the targets assigned to a specific custom SIP application router.

Syntax

showCustomRouter(router_name)

Example usage

showCustomRouter("RouterOne")

createRouter

Use this procedure to create a new custom SIP application router.

Syntax

createRouter(router_name, router_provider)

router_name

Logical name representing the application router.

router_provider

Provider name of the application router. This router provider is defined in the custom application router jar file, which must be in the application server's classpath.

Example usage

createRouter("RouterOne", "RouterProviderOne")

modifyRouter

Use this procedure to modify the name and description of a custom SIP application router.

Syntax

modifyRouter(router_name, new_router_name, new_router_provider)

router_name

Logical name representing the application router.

new_router_name

New logical name to use to represent the application router.

new_router_provider

New provider name of the application router. This router provider is defined in the custom application router jar file, which must be in the application server's classpath.

Example usage

modifyRouter("RouterOne", "Router1", "RouterProvider1")

deleteRouter

Use this procedure to delete a custom SIP application router.

Syntax

deleteRouter(router_name)

router_name

Logical name representing the application router.

Example usage

deleteRouter("RouterOne")

moveServerToCustomRouter

Use this procedure to move a server to a custom SIP application router.

Syntax

moveServerToCustomRouter(node, server_name, router_name)

node

Node on which the server is located.

server_name

Name of the server to move to a custom SIP application router.

router_name

Logical name representing the application router.

Example usage

moveServerToCustomRouter("AppSrvCEANode01", "server1", "RouterOne")

moveServerToDefaultRouter

Use this procedure to move a server to the default SIP application router.

Syntax

moveServerToDefaultRouter(node, server_name)

node

Node on which the server is located.

server_name

Name of the server to move to the default SIP application router.

Example usage

moveServerToDefaultRouter("AppSrvCEANode01", "server1")

moveClusterToCustomRouter

Use this procedure to move a cluster to a custom SIP application router.

Syntax

moveClusterToCustomRouter(cluster_name, router_name)

cluster_name

Name of the cluster to move to a custom SIP application router.

router_name

Logical name representing the application router.

Example usage

moveClusterToCustomRouter("cluster1", "RouterOne")

moveClusterToDefaultRouter

Use this procedure to move a cluster to the default SIP application router.

Syntax

moveClusterToDefaultRouter(cluster_name)

cluster_name

Name of the cluster to move to the default SIP application router.

Example usage

moveClusterToDefaultRouter("cluster1")

Related tasks

Configure SIP application routers

Samples documentation

Scripting the application serving environment (wsadmin)