3 Configuring Web Services Manager

Learn how to configure Oracle Communications Billing and Revenue Management (BRM) Web Services Manager by reviewing its configuration reference, validating XML payloads, connecting Web Services Manager to Connection Manager (CM), restricting stored searches, configuring Java logging, and enabling HTTPS for SOAP client connections.

Topics in this document:

• Web Services Manager Configuration Reference

• Validating Input and Output XML Data

• Connecting Web Services Manager to Connection Manager

• Restricting Stored Search Templates

• Configuring BI Publisher for Data Export

• Configuring Web Services Manager Logging

• Configuring HTTPS Between SOAP Clients and Web Services Manager

Web Services Manager Configuration Reference

Web Services Manager reads its application settings from BRM_home/apps/brm_wsm/config/Infranet.properties and its Java logging settings from BRM_home/apps/brm_wsm/config/logging.properties. The start script passes the installed Infranet.properties path to the application. When you start Web Services Manager directly, it first looks for an explicitly supplied path. If you do not supply a path, Web Services Manager looks for Infranet.properties in your home directory and then in the current directory.

Environment variables and Java system properties are also configuration sources. Restart Web Services Manager after changing these settings unless the referenced guidance states otherwise.

Table 3-1 lists the supported Web Services Manager configuration options. Java PCM settings are included where they are important to a Web Services Manager deployment, but their detailed semantics and tuning belong in the Java PCM and BRM administration documentation.

Note:

In the Applies to column, Both means the standard BRM opcode services in the jaxws_str and jaxws paths. The Data Export service is identified separately where applicable.

Table 3-1 Web Services Manager Configuration Options

Configuration	Default	Purpose	Applies to	Detailed Guidance
Configuration-file argument, environment variables, and Java system properties	BRM_home/apps/brm_wsm/config/Infranet.properties	Selects the Web Services Manager application configuration and allows deployment-specific overrides.	Web Services Manager server-wide	See "Starting and Stopping Web Services Manager".
server.host server.port	0.0.0.0 8080	Configures the default HTTP listener.	Both: jaxws_str (XML-string) and jaxws (XML-element)	See "Configuring HTTPS Between SOAP Clients and Web Services Manager".
server.sockets.https.port server.sockets.https.host server.sockets.https.tls.enabled server.sockets.https.tls.endpoint-identification-algorithm server.sockets.https.tls.client-auth server.sockets.https.tls.private-key.keystore.passphrase server.sockets.https.tls.private-key.keystore.resource.path server.sockets.https.tls.trust.keystore.trust-store server.sockets.https.tls.trust.keystore.passphrase server.sockets.https.tls.trust.keystore.resource.path	Not applicable	Configures the named HTTPS listener, server identity, client-authentication mode, and optional trust store.	Both: jaxws_str (XML-string) and jaxws (XML-element)	See "Configuring HTTPS Between SOAP Clients and Web Services Manager".
tracing.service tracing.enabled tracing.protocol tracing.host tracing.port tracing.path tracing.api-version	brm-wsm true http localhost 9411 /api/v2/spans 2	Enables tracing and configures span export to the tracing collector.	Both: jaxws_str (XML-string) and jaxws (XML-element), excluding the Data Export proxy	See "Using Metrics and Tracing".
infranet.isOAuth infranet.certificatePath	true Empty string	Enables OAuth access-token validation and identifies the PEM X.509 certificate containing the RSA public key used to verify token signatures.	Both: jaxws_str (XML-string) and jaxws (XML-element) opcode services	See "Setting Up Web Services Manager with OAuth 2.0".
infranet.connectionpool.* For example: infranet.connectionpool.minsize, infranet.connectionpool.maxsize, and infranet.connectionpool.timeout	Not applicable	Controls the Java PCM connection pool used by Web Services Manager.	Both: jaxws_str (XML-string) and jaxws (XML-element)	See BRM PCM Java API Reference.
Other infranet.* settings For example: infranet.connection, infranet.wallet.location, infranet.login.type, infranet.PcmTimeoutInMsecs, and infranet.pcp.ssl.*	Not applicable	Configures the shared Java PCM connection, wallet, call timeout, PCP TLS, authentication, and customization settings used by Web Services Manager.	Both: jaxws_str (XML-string) and jaxws (XML-element)	See "Connecting Web Services Manager to Connection Manager".
webservices.input.validation.enabled webservices.soap.input.validation.reportonly webservices.output.validation.enabled webservices.soap.output.validation.reportonly	true false true false	Controls opcode-XSD validation and whether validation errors are reported without failing processing.	jaxws (XML-element) only	See "Validating Input and Output XML Data".
webservices.schema.location	${PIN_HOME}/apps/brm_wsm/schemas	Locates opcode schemas used for XML-element validation and schema retrieval.	jaxws (XML-element) validation and schema retrieval	See "Validating Input and Output XML Data".
webservices.extensions.location	${PIN_HOME}/apps/brm_wsm/brm_extensions.xml	Locates the BRM XML conversion extension definitions.	Both: jaxws_str (XML-string) and jaxws (XML-element)	See "Customizing Web Services Manager.".
webservices.output.namespace.prefix.soap	S	Sets the SOAP envelope prefix generated for XML-element and Data Export responses.	jaxws (XML-element) and Data Export responses	Not applicable
webservices.output.namespace.prefix.payload	brm	Sets the namespace prefix used by the BRM XML payload converter.	Both: jaxws_str (XML-string) and jaxws (XML-element)	Not applicable
webservices.input.date.format webservices.output.date.format	yyyy-MM-dd'T'HH:mm:ss for both	Sets the Java SimpleDateFormat patterns used to parse input timestamps and format output timestamps.	Both: jaxws_str (XML-string) and jaxws (XML-element)	See "SimpleDateFormat".
webservices.input.date.prefixunixtstamp	false	In the current implementation, controls whether an epoch-seconds prefix is added to an output timestamp.	Both: jaxws_str (XML-string) and jaxws (XML-element)	Not applicable
webservices.output.date.prefixunixtstamp	false	In the current implementation, controls whether an epoch-seconds prefix is removed while parsing an input timestamp.	Both: jaxws_str (XML-string) and jaxws (XML-element)	Not applicable
webservices.loadcustomschema	false	Controls whether Metro searches all matching class-path resources while resolving customized schemas.	Web Services Manager customization	See "Customizing Web Services Manager".
webservices.descriptor	sun-jaxws.xml	Selects the Metro endpoint deployment descriptor loaded by Web Services Manager.	Both: jaxws_str (XML-string) and jaxws (XML-element)	See "Customizing Web Services Manager".
bip.endpoint bip.userId Wallet entry bip.passwd	Not applicable	Supplies the BI Publisher endpoint and credentials required by the Data Export service.	XML-element Data Export service only	See "Configuring BI Publisher for Data Export".
allowed.search.template.ids	Not applicable	Restricts stored-search template object IDs accepted for PCM_OP_SEARCH. None rejects all such requests.	jaxws (XML-element) only in the current implementation	See "Restricting Stored Search Templates".
handlers .level com.oracle.communications.brm.wsm.level java.util.logging.FileHandler.level java.util.logging.FileHandler.append java.util.logging.FileHandler.pattern java.util.logging.FileHandler.formatter	java.util.logging.FileHandler WARNING FINEST INFO true brm_wsm.log com.oracle.communications.brm.wsm.BRMLogFormatter	Configures Java logging output, levels, file handling, and Web Services Manager log formatting.	Web Services Manager server-wide	See "Configuring Web Services Manager Logging".
BRM_WSM_CLASSPATH_EXT	Not applicable	Adds customer-provided customization JARs to the Web Services Manager class path.	Web Services Manager startup and customization	See "Customizing Web Services Manager".
BRM_WSM_JAVA_OPTIONS	Not applicable	Supplies additional JVM options to the Web Services Manager launcher.	Web Services Manager startup	See "Starting and Stopping Web Services Manager" and the applicable Java documentation.

Validating Input and Output XML Data

For XML-element web service invocations, Web Services Manager can validate the input and output XML structure, elements, data types, and schema constraints against the target opcode XML schema.

The opcode specifications, schemas, and WSDL files are packaged with Web Services Manager. The package also includes the following items:

• The opspec.xsd file. Use the XSD to write opcode specifications for custom opcodes that you expose as XML-element web services.

• The pin_opspec_to_schema_v2 utility. Use this utility to generate XML-element schema files from opcode specification files. See "Creating Opcode Specification Schema Files" for the complete procedure.

Use these steps to configure Web Services Manager to validate the input and output XML against the target opcode XML schema:

Note:

This procedure includes only schema-validation settings.

1. Open the BRM_home/apps/brm_wsm/config/Infranet.properties file.

2. Set the following entries to true.

   webservices.input.validation.enabled=true
   webservices.output.validation.enabled=true

   By default, the entries are set to true.

3. To log a validation error without returning a SOAP fault, set the corresponding report-only entry to true. Web Services Manager continues processing the request.

   webservices.soap.input.validation.reportonly=true
   webservices.soap.output.validation.reportonly=true

   By default, the entries are set to false.

4. Set the following entry to the directory containing the opcode XSD files:

   webservices.schema.location=schemaDirectory

   where schemaDirectory must be accessible to the Web Services Manager process. The default is BRM_home/apps/brm_wsm/schemas.

5. Store each target opcode schema as opcodeName.xsd in schemaDirectory.

6. Save and close the file.

7. Stop and restart Web Services Manager. See "Starting and Stopping Web Services Manager".

Connecting Web Services Manager to Connection Manager

Web Services Manager acts as a Java PCM client and connects to BRM Connection Manager (CM) over PCP. Use the Java PCM documentation for the complete connection, wallet, connection-pool, and PCP TLS configuration.

Before using Web Services Manager APIs, verify the following:

• infranet.wallet.location points to an Oracle wallet that contains the infranet.connection entry.

• The BRM user identified by infranet.connection is authorized to execute every opcode that clients will invoke through Web Services Manager.

• If CM requires TLS, the infranet.pcp.ssl.* settings match the CM listener configuration and the configured PCP TLS wallet contains the certificates required to trust CM’s identity. For mutual TLS, the wallet must also contain Web Services Manager’s client certificate and private key, and CM must trust that client certificate.

For more information, see the following:

• "Creating Client Applications by Using Java PCM" in BRM Developer's Guide

• "Using Configuration Files" in BRM System Administrator's Guide

• ConnectionPool in BRM PCM Java API Reference.

Restricting Stored Search Templates

For XML-element invocations of PCM_OP_SEARCH, Web Services Manager can restrict requests to specific stored /search template object IDs. This setting does not select or connect to a BRM instance. Stored-search template IDs belong to the connected BRM database, so verify that every configured ID identifies the intended /search object in that database.

To restrict stored searches:

1. Open the BRM_home/apps/brm_wsm/config/Infranet.properties file.

2. Set the following entry to a comma-separated list of permitted stored-search template object IDs:

   allowed.search.template.ids=TEMPLATE_ID_1,TEMPLATE_ID_2

   When the entry is absent, Web Services Manager does not apply the allowlist restriction. Setting the value to None rejects all XML-element PCM_OP_SEARCH requests. For information about stored search templates, see "Searching for Objects in the BRM Database" in BRM Developer’s Guide.

3. Save and close the file.

4. Stop and restart Web Services Manager. See "Starting and Stopping Web Services Manager".

Configuring BI Publisher for Data Export

The BRMDataExportServices_v2 service forwards supported report operations to Oracle BI Publisher. Before using this service, configure the BI Publisher web service base URL and the credentials that Web Services Manager adds to each outbound request.

Use the following steps to configure BI Publisher for data export:

1. Ensure that the BI Publisher user is authorized to perform every report-execution, report-scheduling, report-output and job-history, and catalog-read operation that clients start through Web Services Manager.

2. Open the BRM_home/apps/brm_wsm/config/Infranet.properties file.

3. Set the following entries:

   bip.endpoint=https://BIP_host:BIP_port/xmlpserver/services/
   bip.userId=BIP_user

   bip.endpoint is the BI Publisher web service base URL. Web Services Manager appends v2/ScheduleService, v2/ReportService, or PublicReportService, depending on the operation being invoked.

4. Store the BI Publisher user’s password as bip.passwd in the Oracle wallet identified by infranet.wallet.location:

   cd BRM_home/bin
   pin_config_editor -setconf -wallet wallet_directory -parameter bip.passwd -pwd

   where wallet_directory is the value configured for infranet.wallet.location. The utility prompts for the wallet password and then for the BI Publisher password.

5. Save and close Infranet.properties.

6. Stop and restart Web Services Manager. See "Starting and Stopping Web Services Manager".

See the Oracle Analytics Publisher documentation for information about accessing WSDLs and default application roles and permissions. See "Using Configuration Files" in BRM System Administrator's Guide for more information about storing Java PCM application passwords in an Oracle wallet.

Configuring Web Services Manager Logging

Web Services Manager uses Java Util Logging (JUL) and loads its logging configuration from BRM_home/apps/brm_wsm/config/logging.properties.

The delivered configuration sets the global logging level to WARNING, the Web Services Manager package logging level to FINEST, and the file-handler level to INFO. It appends messages to brm_wsm.log in the Web Services Manager log directory and formats them with com.oracle.communications.brm.wsm.BRMLogFormatter.

For information about changing JUL handlers, levels, formatters, and other logging configuration, see "Java Logging Overview" in Java Platform, Standard Edition Core Libraries.

Configuring HTTPS Between SOAP Clients and Web Services Manager

To protect SOAP requests and responses between clients and Web Services Manager, configure TLS on a Web Services Manager HTTPS listener. This is the inbound client-to-Web Services Manager connection; PCP TLS between Web Services Manager and CM is configured separately through Java PCM.

To configure HTTPS for Web Services Manager:

1. Obtain an SSL certificate and private key and store them in a PKCS12 (.p12) or JKS (.jks) keystore.

2. Open the BRM_home/apps/brm_wsm/config/Infranet.properties file.

3. Configure the HTTPS listener and server keystore:

   server.sockets.https.port=httpsPort
   server.sockets.https.host=listenAddress
   server.sockets.https.tls.enabled=true
   server.sockets.https.tls.client-auth=NONE
   server.sockets.https.tls.private-key.keystore.passphrase=keystorePassphrase
   server.sockets.https.tls.private-key.keystore.resource.path=keystorePath

   where:

   • httpsPort: The TCP port number for the Web Services Manager HTTPS listener.

   • listenAddress: The host name or IP address to which the Web Services Manager HTTPS listener binds.

   • keystorePassphrase: The password required to access the server keystore containing the SSL certificate and private key.

   • keystorePath: The file-system path to the server keystore containing the SSL certificate and private key.

4. If mutual TLS is required, set the client-authentication mode and configure the trust keystore used to validate client certificates:

   server.sockets.https.tls.client-auth=REQUIRED
   server.sockets.https.tls.trust.keystore.trust-store=true
   server.sockets.https.tls.trust.keystore.passphrase=truststorePassphrase
   server.sockets.https.tls.trust.keystore.resource.path=truststorePath

   where:

   • truststorePassphrase: The password required to access the trust keystore used to validate client certificates for mutual TLS.

   • truststorePath: The file-system path to the trust keystore used to validate client certificates for mutual TLS.

5. Save and close the file.

6. Stop and restart Web Services Manager. See "Starting and Stopping Web Services Manager".

7. Call web services through the HTTPS listener by using URLs beginning with https://hostname:port/metro/.