SDX 6.4.x Application Library Guide > Activating Services Through SOAP > Web Service Interface for PCMM

Web Service Interface for PCMM

PCMM Web Service Interface Specification (PKT-SP-MM-WS-101-051221) defines a common Web service SOAP/XML interface between a generic application server and a PCMM application manager. The interface allows an application server to dynamically request resources on the cable operator's access network. It provides operations for requesting, releasing, and querying network resources on the cable network. The SDX PCMM Web service interface supports the following operations, which are specified in the PCMM Web service interface:

• CommitResources
• ReleaseResources
• QueryAvailableServices
• QueryContexts

Each of these operations is implemented as a method in the SDX PCMM Web service interface.

SDX PCMM Web Service Interface Methods

This section describes the methods in the SDX PCMM Web service interface.

CommitResources

• Specifies the resources that are being requested in the CommitResource message.
• Argument—CommitResourcesReq

• classifier—Object that identifies the traffic flow that the application server is requesting services for. The object contains:

• protocol
• sourceIpAddress
• sourceIpMask
• sourcePortStart
• sourcePortEnd
• destinationIpAddress
• destinationIpMask
• destinationPortStart
• destinationPortEnd

For more information, see Configuring Classify-Traffic Conditions for Dynamic Service Activator.

• trafficProfile—Provides information about the bandwidth and QoS characteristics desired for a request. You express the traffic profile through SDX policies. You can configure the policies one of the following ways:

• FlowSpec action—See Configuring FlowSpec Actions for Dynamic Service Activator.
• Specifying a traffic class in the service class name action—See Service Class Name Action.
• Bandwidth parameter—See DOCSIS Action.

• TimeUsageLimit—Specifies, in seconds, a limit on the lifetime of a context. An application server may specify multiple TimeUsageLimit elements to request different limits in the upstream and downstream directions. If the application server does not specify a TimeUsageLimit, the application manager determines the TimeUsageLimit.
• SubscriberID—IPv4 address or SubscriberURI
• ServiceName—Name of SDX service
• contextID—Globally unique identifier that the application manager must use if it is included in the message

• Expected output—CommitResourcesRsp. The CommitResourcesRsp object contains the ContextID of the activated service.

ReleaseResources

• Specifies the resources that are being requested to be released in the ReleaseResources message.
• Argument—ReleaseResourcesReq

• Subscriber URI—IP address of the subscriber
• ServiceName—Name of SDX service
• contextID—Globally unique identifier that the application manager must use if it is included in the message

• Expected output—ReleaseResourcesRsp

QueryAvailableServices

• Searches for the services that are available for a specified subscriber.
• Argument—QueryAvailableServicesReq

• Client ID—ID configured for the client
• Client Password—Password of the client

• Expected output—QueryAvailableServicesRsp

QueryContexts

• Searches for the context ID and context status for a subscriber
• Argument—QueryContextsReq

• Subscriber URI—IP address of the subscriber
• ServiceName—Name of SDX service
• contextID—Globally unique identifier that the application manager must use if it is included in the message

• Expected output—QueryContextsRsp

Configuring PCMM Policies and Parameter Substitutions

This section describes how to define your SDX policies and parameter substitutions so that they comply with the PCMM Web service interface. In Policy Editor, there is sample data that shows the types of policies and parameters that you can configure. It is in the subtree under Policies -> sample -> pcmm -> pcmm-ws.

If you use parameter substitutions, the PCMM Web service interface provides the values for the substitutions. You must name your parameters as specified in this section.

Configuring Classify-Traffic Conditions for Dynamic Service Activator

Table 10 lists the classify-traffic condition fields that you can configure for PCMM classifiers that will be used with PCMM Web service interface. It also provides the parameter names that you must use if you configure parameter substitutions for the classifier.

 Table 10:  Parameter Names for Classify-Traffic Conditions  

 Field
 Parameter Name

 Protocol

 protocol


 Source IP Address

 sourceIpAddress


 Source IP Mask

 sourceIpMask


 Port

 sourcePortStart and sourcePortEnd
 destinationPortStart and destinationPortEnd


 Destination IP Address

 destinationIpAddress


 Destination IP Mask

 destinationIpMask



 

Configuring FlowSpec Actions for Dynamic Service Activator

You can use a FlowSpec action to specify the traffic profile in CommitResource messages. Table 11 lists the fields that you can use for PCMM policies that will be used with PCMM Web service interface. It also provides the parameter names that you must use if you configure parameter substitutions for the FlowSpec action.

 Table 11:  Parameter Names for FlowSpec Actions  

 Field Name
 Parameter Name

 Service Number

 serviceNumber


 Token Bucket Rate

 bucketRate


 Token Bucket Size

 bucketDepth


 Peak Data Rate

 peakRate


 Minimum Policed Unit

 minPolicedUnit


 Maximum Packet Size

 maxDatagramSize


 Rate

 reservedRate


 Slack Term

 slackTerm



 

Service Class Name Action

You can use a service class name action to specify the traffic profile in CommitResource messages. Table 12 lists the field that you can use for PCMM policies that will be used with PCMM Web service interface. It also provides the parameter names that you must use if you configure parameter substitutions for a service class name action.

 Table 12:  Parameter Name for Service Class Actions

 Field
 Parameter

 Service Class

 TrafficClass



 

DOCSIS Action

You can use a DOCSIS action to specify the priority and bandwidth in the traffic profile in CommitResource messages. Table 13 lists the fields that you can use for PCMM policies that will be used with PCMM Web service interface. It also provides the parameter names that you must use if you configure parameter substitutions for the DOCSIS action.

 Table 13:  Parameter Name for DOCSIS Actions

 Field
 Parameter

 Traffic Priority

 priority


 Maximum Sustained Traffic Rate

 bandwidth


 Maximum Traffic Burst

 bandwidth


 Minimum Reserved Traffic Rate

 bandwidth



 

Configuring Username Token Profile

Application managers require that usernames are specified from the Web Services Security: Username Token Profile 1,0, OASIS Standard.

You configure usernames in the dsa/WEB-INF/pcmm-users.properties file. To do so:

1. Extract the pcmm-users.properties file from the dsa.war file.

jar xvf dsa.war WEB-INF/pcmm-users.properties

2. Edit the pcmm-users.properties file. This file stores usernames in the format:

<userName>:<userPassword>[, <realm>...]

For example:

• Joe:secret, PCMMAuthorizedClient
• Fred:secret, PCMMAuthorizedClient

3. Replace the pcmm-users.properties file in the dsa.war file.

jar uvf dsa.war WEB-INF/pcmm-users.properties

4. Deploy the dsa.war file by following the procedure appropriate to the Web application server you are using.

Configuring Services That Are Available for PCMM Clients

To use SDX Configuration Editor to configure PCMM clients and the services that are available to the clients:

1. In the WebApplication folder in the navigation pane, select the DynamicServiceActivation.xml configuration file.
2. Select the PCMM Available Services tab.

The PCMM Available Services pane appears.

3. Edit or accept the values in the Global Available Services field.

See PCMM Available Services Fields.

4. Add clients to your configuration:

1. Expand the List of Clients and Their Allowed Services section.
2. Select Client from the drop-down list next to the Create a New Instance of button, and click the Create a New Instance of button.

The Create a New Instance dialog box appears.

1. Enter a name for the client instance, and click OK.

5. Configure the client ID and a list of allowed services for the client.

See PCMM Available Services Fields.

6. Select File > Save.
7. Right-click the configuration file, and select SDX System Configuration > Export to LDAP Directory.

PCMM Available Services Fields

In SDX Configuration Editor, you can modify the following fields in the PCMM Available Services pane in a DynamicServiceActivation.xml configuration file.

Global Available Services

• List of available services that are available to all clients that are defined under the /pcmm subtree in the directory.
• Value—Comma-separated list of services
• Default—News, Video-Silver
• Property name—globalServices

Client ID

• Subscriber name that Dynamic Service Activator uses to authenticate this client.
• Value—Text string that matches the name the Web application server uses to authenticate the gateway client
• Guidelines—If you disable the access control mechanism and you configure the Web application server to authenticate clients with any username and password, Dynamic Service Activator sends the text string "anonymous client" as the first argument to the SAE's Java scripts interface module.
• Property name—clientID

Allowed Services

• List of services that the client is allowed to activate.
• Value—Comma-separated list of services
• Default—No value
• Property name—allowedServices