# System Administrator’s Guide

# Managing and Configuring the Presence Communication Services

The following section describes configuration and maintenance attributes and operations for the communication services that expose Parlay X 2.1 Presence Web Services interfaces:

- Parlay X 2.1 Presence/SIP

- URI Cache
- Subscriptions Cache
- Notifications Cache
- Configuration Workflow for Parlay X 2.1 Presence/SIP
- Provisioning Workflow for Parlay X 2.1 Presence/SIP
- Management Operations for Parlay X 2.1 Presence/SIP
- Reference: Attributes and Operations for Parlay X 2.1 Presence/SIP

## Parlay X 2.1 Presence/SIP

This section contains a description of the configuration attributes and operations available for the Parlay X 2.1 Presence/SIP network protocol plug-in instance.

Parlay X 2.1 Presence/SIP uses two parts for SIP connectivity, a part that executes as a network protocol plug-in instance in Oracle Communications Services Gatekeeper container, and a part that executes as a SIP application in the SIP Server container.

The plug-in instance uses a set of caches:

- URI Cache
- Subscriptions Cache
- Notifications Cache

To see a | Refer to
--- | ---
Detailed list of necessary for managing and configuring the plug-in instance | Properties for Parlay X 2.1 Presence/SIP
Configuration workflow | Configuration Workflow for Parlay X 2.1 Presence/SIP
List of operations and attributes related to management and provisioning | Provisioning Workflow for Parlay X 2.1 Presence/SIP Management Operations for Parlay X 2.1 Presence/SIP
Reference of management attributes and operations | Reference: Attributes and Operations for Parlay X 2.1 Presence/SIP

### URI Cache

In Parlay X 2.1 Presence, the SIP URI of the user (the presentity in PresenceSupplier cases, the watcher in PresenceConsumer cases) is not passed as an argument. Instead Oracle Communications Services Gatekeeper maps the user URI to the application instance ID of the user application, The URI mapping is configured as a part of the service provider and application provisioning workflow and is then stored in the URI cache. For requests that originate from an application, the URI is fetched from this cache before being put into the `from` header in the SIP requests. For application terminating requests, the `to` header URI passed in the SIP NOTIFY requests is used to look up the account username/application instance ID.

Note: | In the case of the PresenceSupplier interface, the application can override the default mapping by including a tunneled parameter in the header of its request.

### Subscriptions Cache

Every subscription, pending or not, is stored in this cache during the subscription’s lifetime. It is added when an application invokes the `subscribePresence` method on the application-facing interface, and removed when the subscription is terminated.

### Notifications Cache

All registered notifications are cached. The entries are created when an application invokes `startPresenceNotification` on the application-facing interface and are removed when `endPresenceNotification` is invoked, the end criteria are reached, or the subscription is ended.

### Properties for Parlay X 2.1 Presence/SIP

Property | Description
--- | ---
Managed object in Administration Console | <domain name>OCSG<server name>Communication ServicesPlugin_px21_presence_sip
MBean | Domain=com.bea.wlcp.wlng Name=wlng_nt InstanceName=Plugin_px21_presence_sip Type=com.bea.wlcp.wlng.plugin.presence.sip.management.PresenceMBean
Network protocol plug-in service ID | Plugin_px21_presence_sip
Network protocol plug-in instance ID | Plugin_px21_presence_sip
Supported Address Scheme | sip
North interfaces | com.bea.wlcp.wlng.px21.plugin.PresenceConsumerPlugin com.bea.wlcp.wlng.px21.plugin.PresenceSupplierPlugin com.bea.wlcp.wlng.px21.callback.PresenceNotificationCallback
Service type | Presence
Exposes to the service communication layer a Java representation of: | Parlay X 2.1 Part 14: Presence
Interfaces with the network nodes using: | SIP: Session Initiation Protocol, RFC 3261.
Deployment artifacts NT EAR wlng_nt_presence_px21.ear | Plugin_px21_presence_sip.jar, px21_presence_service.jar, and px21_presence_sip.jar
AT EAR: Normal wlng_at_presence_px21.ear | px21_presence.war, px21_presence_callback.jar, and rest_presence.war
AT EAR: SOAP Only wlng_at_presence_px21_soap.ear | px21_presence.war and px21_presence_callback.jar

This plug-in service does not support multiple instantiation using the Plug-in Manager. There is a one to one mapping between plug-in service and plug-in instance. The plug-in instance is created when the plug-in service is started.

### Configuration Workflow for Parlay X 2.1 Presence/SIP

1. Using the Management Console or an MBean browser, select the MBean detailed in Properties for Parlay X 2.1 Presence/SIP
2. Configure the attributes of the network protocol plug-in instance:

- Attribute: DefaultNotificationCount
- Attribute: DefaultNotificationDuration
- Attribute: NotificationCleanupTimerValue
- Attribute: NotificationCleanupTimerValue

3. Configure connection information to the SIP server:

- Attribute: SubscriptionCleanupTimerValue

4. 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 Parlay X 2.1 Presence/SIP.
5. If desired, create and load a node SLA, see:

Defining Global Node and Service Provider Group Node SLAs

Managing Application SLAs

Move on to the provisioning of service provider accounts and application accounts.

### Provisioning Workflow for Parlay X 2.1 Presence/SIP

For every application a mapping between a SIP URI and application instance ID needs to be defined using Operation: setApplicationInstanceSIPURI.

To display the mapping, use Operation: getApplicationInstanceSIPURI.

If an application is deleted, the data for the application needs to be removed using Operation: removeApplicationInstanceFromCache.

### Management Operations for Parlay X 2.1 Presence/SIP

- Operation: clearCache
- Operation: listNotificationsCache
- Operation: listSubscriptionsCache
- Operation: listURImappingCache
- Operation: updateSubscriptionToBeconfirmed

### Reference: Attributes and Operations for Parlay X 2.1 Presence/SIP

Managed object: Communication Services->Plugin_presence_sip

MBean: com.bea.wlcp.wlng.plugin.presence.sip.impl.PresenceMBean

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

- Attribute: DefaultNotificationCount
- Attribute: DefaultNotificationDuration
- Attribute: NotificationCleanupTimerValue
- Attribute: PresenceServerAddress
- Attribute: PresenceXDMSAddress
- Attribute: PresenceXDMSPresrulesPostfix
- Attribute: PresenceXDMSPresrulesPrefix
- Attribute: PresenceXDMSProviderClassName
- Attribute: SubscriptionCleanupTimerValue
- Attribute: SubscribeExpiryValue
- Operation: clearCache
- Operation: getApplicationInstance
- Operation: getApplicationInstanceSIPURI
- Operation: listNotificationsCache
- Operation: listSubscriptionsCache
- Operation: listURImappingCache
- Operation: removeApplicationInstanceFromCache
- Operation: removeNotification
- Operation: removeSubscription
- Operation: setApplicationInstanceSIPURI
- Operation: updateSubscriptionToBeconfirmed

### Attribute: DefaultNotificationCount

Scope: Cluster

Unit: n/a

Format: int

Specifies the default notification count value. This value is used if none is provided in the `startNotification` requests from the application.

### Attribute: DefaultNotificationDuration

Scope: Cluster

Unit: seconds

Format: int

Specifies the value of the default notification duration. This value is used if none is provided in the `startNotification` request form the application.

Example values:

- 86400 seconds is 1 day
- 604800s is 1 week

### Attribute: NotificationCleanupTimerValue

Scope: Cluster

Unit: seconds

Format: int

Specifies the value of the timer used for checking on and cleaning up old notifications.

Each time the timer expires, it initiates a check for old notifications. If an old notification is found during the check it will be removed internally and a `statusEnd` callback is made to the application.

### Attribute: PresenceServerAddress

Scope: Cluster

Unit: n/a

Format: String formatted as a SIP URI

Specifies the address to which the subscribe messages are sent. It can be the IP address of the presence server or another IMS node that proxies the request.

### Attribute: PresenceXDMSAddress

Scope: Cluster

Unit: n/a

Format: String formatted as a SIP URI

Specifies the XCAP root URI of the XDM server.

### Attribute: PresenceXDMSPresrulesPostfix

Scope: Cluster

Unit: n/a

Format: String formatted as a partial path.

Specifies the last-part of the XCAP Document selector for presence rules. This part is after the XCAP User Identifier(XUI). Generally the selector URI should be the string of the following type: [XCAP_ROOT]/[AUID]/users/[XUI]/[document_name]

Example:

    /presrules

### Attribute: PresenceXDMSPresrulesPrefix

Scope: Cluster

Unit: n/a

Format: String formatted as a path

The pre-part of the XCAP Document selector for presence rules. This part is before the XCAP User Identifier(XUI). Generally the selector URI should be the string of the following type: [XCAP_ROOT]/[AUID]/users/[XUI]/[document_name]

Example:

    /services/pres-rules/users/

### Attribute: PresenceXDMSProviderClassName

Scope: Cluster

Unit: n/a

Format: Class name as string

The class name of XDM Server provider. This is a pluggable function to allow third party vendors of XDMS to customize their own XCAP client. This class must implement the "com.bea.wlcp.wlng.plugin.presence.sip.south.xcap.XCAPClient" interface.

### Attribute: SubscriptionCleanupTimerValue

Scope: Cluster

Unit: seconds

Format: int

Specifies the value of the timer used for checking on and cleaning up old subscription.

Each time the timer expires, it initiates a check for old subscriptions. If an old subscription is found during the check it will be removed a callback is made to the application.

### Attribute: SubscribeExpiryValue

Scope: Cluster

Unit: seconds

Format: int

Specifies the maximum lifetime of a subscription.

This value might not be accepted by the Presence Server. The Presence Server may override this expiry value, and give the suggested value to be used in the first NOTIFY sent to the plug-in instance. In that case, the lifetime for the presence subscription will be according to the value received from the Presence Server.

### Operation: clearCache

Scope: Cluster

Clears one or all caches used by this plug-in instance.

Note: | Use this method with care.

Signature:

    clearCache(cacheToClear: String)

Table 28-1 clearCache
clearCache
Parameter | Description
--- | ---
cacheToClear | Name of the cache to clear. Valid options: NOTIFICATIONS -clears the notification cache SUBSCRIPTIONS -clears the subscriptions cache URIMAPPINGS -clears the URI mappings cache ALL -clears all caches.

### Operation: getApplicationInstance

Scope: Cluster

Displays the application instance ID associated with a SIP URI. The application instance is identifies an application.

Signature:

    getApplicationInstance(Uri: String)

Table 28-2 getApplicationInstance
getApplicationInstanceGroup
Parameter | Description
--- | ---
Uri | The SIP URI.

### Operation: getApplicationInstanceSIPURI

Scope: Cluster

Displays the SIP URI associated with an application instance. The application instance is used by an application.

Signature:

    getApplicationInstanceSIPURI(ApplicationInstanceID: String)

Table 28-3 getApplicationInstanceSIPURI
getApplicationInstanceSIPURI
Parameter | Description
--- | ---
ApplicationInstanceID | ID of the application instance.

### Operation: listNotificationsCache

Scope: Cluster

Displays the cache where notification information is stored. Used for troubleshooting.

Note: | Use with caution; lists data from all entries in the notification cache.

Signature:

    listNotificationsCache()

Table 28-4 listNotificationsCache
listNotificationsCache
Parameter | Description
--- | ---
- | -

### Operation: listSubscriptionsCache

Scope: Cluster

Displays the cache where subscription information is stored. Used for troubleshooting.

Note: | Use with caution; lists data from all entries in the subscriptions cache.

Signature:

    listSubscriptionsCache()

Table 28-5 listSubscriptionsCache
listSubscriptionsCache
Parameter | Description
--- | ---
- | -

### Operation: listURImappingCache

Scope: Cluster

Displays the cache where URI mappings information is stored. Used for troubleshooting.

Note: | Use with caution; lists data from all entries in the URI mappings cache.

Signature:

    listURImappingCache()

Table 28-6 listURImappingCache
listURImappingCache
Parameter | Description
--- | ---
- | -

### Operation: removeApplicationInstanceFromCache

Scope: Cluster

Removes entries that are associated with an application instance from the URI mappings cache. If an application instance has been removed, the associated entries in the cache must be removed, too.

Signature:

    removeApplicationInstanceFromCache(ApplicationInstance: String)

Table 28-7 removeApplicationInstanceFromCache
removeApplicationInstanceFromCache
Parameter | Description
--- | ---
ApplicationInstance | ID of the application instance.

### Operation: removeNotification

Scope: Cluster

Removes a notification. The application will not be notified that the notification has been removed.

Signature:

    removeNotification(ApplicationInstanceID: String, Presentity: String)

Table 28-8 removeNotification
removeNotification
Parameter | Description
--- | ---
ApplicationInstanceID | ID of the application instance.
Presentity | ID of the presentity.

### Operation: removeSubscription

Scope: Cluster

Removes a subscription and notifications. The application will not be notified that the subscription has been removed.

Signature:

    removeSubscription(ApplicationInstanceID: String, Presentity: String)

Table 28-9 removeSubscription
removeSubscription
Parameter | Description
--- | ---
ApplicationInstanceID | ID of the application instance.
Presentity | ID of the presentity.

### Operation: setApplicationInstanceSIPURI

Scope: Cluster

Associates a SIP URI with an application instance. See URI Cache.

Signature:

    setApplicationInstanceSIPURI(appInstGrpId: String, URI: String)

Table 28-10 setApplicationInstanceSIPURI
setApplicationInstanceSIPURI
Parameter | Description
--- | ---
ApplicationInstanceID | ID of the application instance.
URI | SIP URI. For example: sip:name@somedomain.org

### Operation: updateSubscriptionToBeconfirmed

Scope: Cluster

Updates the xml rule in XDMS to status: confirm.

Forces a blocked subscription to be pending/confirmed.

Signature:

    updateSubscriptionToBeconfirmed(presentity: String, watcher: String)

Table 28-11 setApplicationInstanceSIPURI
setApplicationInstanceSIPURI
Parameter | Description
--- | ---
Presentity | ID of the application instance.
Watcher | SIP URI. For example: sip:name@somedomain.org