1 Using Web Services

Learn how to use Oracle Communications Billing and Revenue Management (BRM) Web Services Manager, which enables BRM opcodes to be exposed through web services. Web Services Manager supports SOAP web services and is packaged as an integration pack.

Topics in this document:

• About WSDL Files and BRM Opcodes

• Example of Reading Account Fields in BRM Using Web Services

• Using Metrics and Tracing

About WSDL Files and BRM Opcodes

Web Services Manager exposes BRM opcodes as operations through different web services. The web services define the available opcodes and the attributes to include in each request.

The web service APIs are grouped by functional area. For example, the BRMBillService web service defines the billing web service APIs, and the BRMPymtService web service defines the payment web service APIs. Web Services Manager publishes a WSDL contract for each configured SOAP endpoint.

Web Services Manager contains two types of WSDL files: one for XML-string payloads and one for XML-element payloads. Both payload types are available in SOAP 1.1 and SOAP 1.2 variants.

The WSDL service name and endpoint path depend on the payload type and SOAP version:

• XML-string payloads

  • SOAP 1.1: The WSDL service name uses the standard Service suffix, for example, BRMBalService.

  • SOAP 1.2: Add 12 immediately before Service, for example, BRMBal12Service.

  • XML-string services use the /metro/jaxws_str/ endpoint path.

• XML-element payloads

  • SOAP 1.1: The WSDL service name ends in _v2, for example, BRMBalServices_v2.

  • SOAP 1.2: Add 12 immediately before _v2, for example, BRMBalServices12_v2.

  • XML-element services use the /metro/jaxws/ endpoint path.

For web services that use an XML-element payload, the WSDL describes the input in a well-defined structure. A standards-compliant SOAP development application can use the WSDL to generate a client stub.

Table 1-1 describes the SOAP 1.1 and SOAP 1.2 WSDL service names for web services that take payload as an XML string. Each row lists service names and endpoint paths in SOAP 1.1 followed by SOAP 1.2 order.

Table 1-1 Web Services Included in Web Services Manager that Take the Payload as an XML String

Web Service Name	Endpoint Path	Description
BRMARService BRMAR12Service	/metro/jaxws_str/BRMARService /metro/jaxws_str/BRMARService12	Defines the accounts receivable web service, which includes the following opcodes: PCM_OP_AR_ACCOUNT_ADJUSTMENT PCM_OP_AR_BILL_ADJUSTMENT PCM_OP_AR_GET_ACCT_ACTION_ITEMS PCM_OP_AR_GET_ACCT_BAL_SUMMARY PCM_OP_AR_GET_ACCT_BILLS PCM_OP_AR_GET_BAL_SUMMARY PCM_OP_AR_GET_BILL_ITEMS PCM_OP_AR_ITEM_ADJUSTMENT PCM_OP_AR_EVENT_ADJUSTMENT PCM_OP_AR_GET_ACTION_ITEMS PCM_OP_AR_GET_BILLS PCM_OP_AR_RESOURCE_AGGREGATION See "Accounts Receivable FM Standard Opcodes" in BRM Opcode Guide for more information.
BRMBalService BRMBal12Service	/metro/jaxws_str/BRMBalService /metro/jaxws_str/BRMBalService12	Defines the balances web service, which includes the following opcodes: PCM_OP_BAL_GET_BALANCES PCM_OP_BAL_GET_BAL_GRP_AND_SVC PCM_OP_BAL_GET_ACCT_BAL_GRP_AND_SVC PCM_OP_BAL_GET_ACCT_BILLINFO PCM_OP_BAL_GET_ECE_BALANCES Note: You must complete the required configuration before calling PCM_OP_BAL_GET_ECE_BALANCES. See "Configuring BRM to Use PCM_OP_BAL_GET_ECE_BALANCES". See "Balance FM Standard Opcodes" in BRM Opcode Guide for more information.
BRMBillService BRMBill12Service	/metro/jaxws_str/BRMBillService /metro/jaxws_str/BRMBillService12	Defines the billing web service, which includes the following opcodes: PCM_OP_BILL_GET_ITEM_EVENT_CHARGE_DISCOUNT PCM_OP_BILL_GROUP_MOVE_MEMBER PCM_OP_BILL_MAKE_BILL_NOW PCM_OP_BILL_DEBIT PCM_OP_BILL_GROUP_GET_PARENT See "Billing FM Standard Opcodes" in BRM Opcode Guide for more information.
BRMCollectionsService BRMCollections12Service	/metro/jaxws_str/BRMCollectionsService /metro/jaxws_str/BRMCollectionsService12	Defines the collections web service, which includes the following opcode: PCM_OP_COLLECTIONS_SET_ACTION_STATUS See "Collections Manager FM Standard Opcodes" in BRM Opcode Guide for more information.
BRMCustcareService BRMCustcare12Service	/metro/jaxws_str/BRMCustcareService /metro/jaxws_str/BRMCustcareService12	Defines the customer care web service, which includes the following opcode: PCM_OP_CUSTCARE_MOVE_ACCT
BRMCustService BRMCust12Service	/metro/jaxws_str/BRMCustService /metro/jaxws_str/BRMCustService12	Defines the customer web service, which includes the following opcodes: PCM_OP_CUST_COMMIT_CUSTOMER PCM_OP_CUST_MODIFY_CUSTOMER PCM_OP_CUST_UPDATE_CUSTOMER PCM_OP_CUST_UPDATE_SERVICES PCM_OP_CUST_DELETE_ACCT PCM_OP_CUST_DELETE_PAYINFO PCM_OP_CUST_CREATE_PROFILE PCM_OP_CUST_MODIFY_PROFILE PCM_OP_CUST_DELETE_PROFILE See "Customer FM Standard Opcodes" in BRM Opcode Guide for more information.
BRMInvService BRMInv12Service	/metro/jaxws_str/BRMInvService /metro/jaxws_str/BRMInvService12	Defines the invoicing web service, which includes the following opcode: PCM_OP_INV_VIEW_INVOICE Note: Configure your client application to convert the invoice data received from PCM_OP_INV_VIEW_INVOICE into the appropriate format. See "About Invoicing Output XML Data" in BRM JCA Resource Adapter. See "Invoicing FM Standard Opcodes" in BRM Opcode Guide for more information.
BRMPricingService BRMPricing12Service	/metro/jaxws_str/BRMPricingService /metro/jaxws_str/BRMPricingService12	Defines the pricing web service, which includes the following opcodes: PCM_OP_PRICE_COMMIT_PRODUCT PCM_OP_PRICE_COMMIT_DISCOUNT PCM_OP_PRICE_SET_PRICE_LIST PCM_OP_PRICE_GET_PRICE_LIST
BRMPymtService BRMPymt12Service	/metro/jaxws_str/BRMPymtService /metro/jaxws_str/BRMPymtService12	Defines the payment web service, which includes the following opcode: PCM_OP_PYMT_COLLECT See "Payment FM Standard Opcodes" in BRM Opcode Guide for more information.
BRMReadService BRMRead12Service	/metro/jaxws_str/BRMReadService /metro/jaxws_str/BRMReadService12	Defines the read web service, which includes the following opcodes: PCM_OP_READ_FLDS PCM_OP_READ_OBJ PCM_OP_SEARCH See "LDAP Base Opcodes" in BRM Opcode Guide for more information.
BRMSubscriptionService BRMSubscription12Service	/metro/jaxws_str/BRMSubscriptionService /metro/jaxws_str/BRMSubscriptionService12	Defines the subscription web service, which includes the following opcodes: PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT PCM_OP_SUBSCRIPTION_CANCEL_DISCOUNT PCM_OP_SUBSCRIPTION_CANCEL_SUBSCRIPTION PCM_OP_SUBSCRIPTION_CHANGE_DEAL PCM_OP_SUBSCRIPTION_ORDERED_BALGRP PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY PCM_OP_SUBSCRIPTION_PURCHASE_DEAL PCM_OP_SUBSCRIPTION_SET_BUNDLE PCM_OP_SUBSCRIPTION_SET_DISCOUNT_STATUS PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO PCM_OP_SUBSCRIPTION_SET_PRODINFO PCM_OP_SUBSCRIPTION_SET_PRODUCT_STATUS PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION PCM_OP_SUBSCRIPTION_GET_PURCHASED_OFFERINGS See "Subscription Management FM Standard Opcodes" in BRM Opcode Guide for more information.
BRMBaseService BRMBase12Service	/metro/jaxws_str/BRMBaseService /metro/jaxws_str/BRMBaseService12	Defines a base web service that includes PCM_OP_READ_FLDS, PCM_OP_READ_OBJ, and PCM_OP_SEARCH, and exposes the generic opcode and opcodeWithFlags operations.

Table 1-2 describes the SOAP 1.1 and SOAP 1.2 WSDL service names for web services that take the payload as an XML element. Within each row, service names and endpoint paths are listed in SOAP 1.1 followed by SOAP 1.2 order. The Data Export service uses the same WSDL service name for both supplied WSDL versions.

Table 1-2 Web Services Included in Web Services Manager that Take the Payload as an XML Element

Web Service Name	Endpoint Path	Description
BRMActServices_v2 BRMActServices12_v2	/metro/jaxws/BRMActService /metro/jaxws/BRMActService12	Defines the activity web service, which includes the following opcodes: PCM_OP_ACT_ACTIVITY PCM_OP_ACT_CALC_MAX_USAGE PCM_OP_ACT_FIND PCM_OP_ACT_LOAD_SESSION See "Activity FM Standard Opcodes" in BRM Opcode Guide for more information.
BRMARServices_v2 BRMARServices12_v2	/metro/jaxws/BRMARService /metro/jaxws/BRMARService12	Defines the accounts receivable web service, which includes the following opcodes: PCM_OP_AR_ACCOUNT_ADJUSTMENT PCM_OP_AR_ACCOUNT_WRITEOFF PCM_OP_AR_BILL_ADJUSTMENT PCM_OP_AR_BILL_DISPUTE PCM_OP_AR_BILL_SETTLEMENT PCM_OP_AR_BILL_WRITEOFF PCM_OP_AR_BILLINFO_WRITEOFF PCM_OP_AR_EVENT_ADJUSTMENT PCM_OP_AR_EVENT_DISPUTE PCM_OP_AR_EVENT_SETTLEMENT PCM_OP_AR_GET_ACCT_ACTION_ITEMS PCM_OP_AR_GET_ACCT_BAL_SUMMARY PCM_OP_AR_GET_ACCT_BILLS PCM_OP_AR_GET_ACTION_ITEMS PCM_OP_AR_GET_BAL_SUMMARY PCM_OP_AR_GET_BILLS PCM_OP_AR_GET_BILL_ITEMS PCM_OP_AR_GET_DISPUTES PCM_OP_AR_GET_DISPUTE_DETAILS PCM_OP_AR_GET_ITEMS PCM_OP_AR_GET_ITEM_DETAIL PCM_OP_AR_ITEM_ADJUSTMENT PCM_OP_AR_ITEM_DISPUTE PCM_OP_AR_ITEM_SETTLEMENT PCM_OP_AR_ITEM_WRITEOFF PCM_OP_AR_RESOURCE_AGGREGATION See "Accounts Receivable FM Standard Opcodes" in BRM Opcode Guide for more information.
BRMBalServices_v2 BRMBalServices12_v2	/metro/jaxws/BRMBalService /metro/jaxws/BRMBalService12	Defines the balances web service, which includes the following opcodes: PCM_OP_BAL_CHANGE_VALIDITY PCM_OP_BAL_GET_BALANCES PCM_OP_BAL_GET_ECE_BALANCES PCM_OP_BAL_GET_BAL_GRP_AND_SVC PCM_OP_BAL_GET_ACCT_BAL_GRP_AND_SVC PCM_OP_BAL_GET_ACCT_BILLINFO Note: You must complete the required configuration before calling PCM_OP_BAL_GET_ECE_BALANCES. See "Configuring BRM to Use PCM_OP_BAL_GET_ECE_BALANCES". See "Balance FM Standard Opcodes" in BRM Opcode Guide for more information.
BRMBillServices_v2 BRMBillServices12_v2	/metro/jaxws/BRMBillService /metro/jaxws/BRMBillService12	Defines the billing web service, which includes the following opcodes: PCM_OP_BILL_DEBIT PCM_OP_BILL_FIND PCM_OP_BILL_GET_ITEM_EVENT_CHARGE_DISCOUNT PCM_OP_BILL_GROUP_GET_PARENT PCM_OP_BILL_GROUP_MOVE_MEMBER PCM_OP_BILL_ITEM_EVENT_SEARCH PCM_OP_BILL_ITEM_REFUND PCM_OP_BILL_MAKE_BILL_NOW PCM_OP_BILL_REVERSE PCM_OP_BILL_SET_LIMIT_AND_CR PCM_OP_BILL_VIEW_INVOICE See "Billing FM Standard Opcodes" in BRM Opcode Guide for more information.
BRMCollectionsServices_v2 BRMCollectionsServices12_v2	/metro/jaxws/BRMCollectionsService /metro/jaxws/BRMCollectionsService12	Defines the collections web service, which includes the following opcode: PCM_OP_COLLECTIONS_SET_ACTION_STATUS See "Collections Manager FM Standard Opcodes" in BRM Opcode Guide for more information.
BRMContractServices_v2 BRMContractServices12_v2	/metro/jaxws/BRMContractService /metro/jaxws/BRMContractService12	Defines the contract web service, which includes the following opcodes: PCM_OP_CONTRACT_CANCEL_CONTRACT PCM_OP_CONTRACT_MODIFY_CONTRACT PCM_OP_CONTRACT_PROCESS_MILESTONE PCM_OP_CONTRACT_GET_MILESTONES (SOAP 1.2 only) PCM_OP_CONTRACT_RENEW_CONTRACT
BRMCustcareServices_v2 BRMCustcareServices12_v2	/metro/jaxws/BRMCustcareService /metro/jaxws/BRMCustcareService12	Defines the customer care web service, which includes the following opcode: PCM_OP_CUSTCARE_MOVE_ACCT
BRMCustServices_v2 BRMCustServices12_v2	/metro/jaxws/BRMCustService /metro/jaxws/BRMCustService12	Defines the customer web service, which includes the following opcodes: PCM_OP_CUST_COMMIT_CUSTOMER PCM_OP_CUST_CREATE_PROFILE PCM_OP_CUST_DELETE_ACCT PCM_OP_CUST_DELETE_PAYINFO PCM_OP_CUST_DELETE_PROFILE PCM_OP_CUST_FIND PCM_OP_CUST_FIND_PAYINFO PCM_OP_CUST_FIND_PROFILE PCM_OP_CUST_GET_NOTE PCM_OP_CUST_MODIFY_CUSTOMER PCM_OP_CUST_MODIFY_PROFILE PCM_OP_CUST_SET_NOTE PCM_OP_CUST_SET_STATUS PCM_OP_CUST_SET_TAXINFO PCM_OP_CUST_UPDATE_CUSTOMER PCM_OP_CUST_UPDATE_SERVICES PCM_OP_CUST_SET_BAL_GRP PCM_OP_CUST_CHANGE_BUSINESS_PROFILE See "Customer FM Standard Opcodes" in BRM Opcode Guide for more information. PCM_OP_CUST_POL_GET_PLANS PCM_OP_CUST_POL_GET_DEALS PCM_OP_CUST_POL_GET_PRODUCTS PCM_OP_CUST_POL_READ_PLAN PCM_OP_CUST_POL_VALID_NAMEINFO See "Customer FM Policy Opcodes" in BRM Opcode Guide for more information.
BRMInvServices_v2 BRMInvServices12_v2	/metro/jaxws/BRMInvService /metro/jaxws/BRMInvService12	Defines the invoicing web service, which includes the following opcode: PCM_OP_INV_VIEW_INVOICE Note: Configure your client application to convert the invoice data received from PCM_OP_INV_VIEW_INVOICE into the appropriate format. See "About Invoicing Output XML Data" in BRM JCA Resource Adapter. See "Invoicing FM Standard Opcodes" in BRM Opcode Guide for more information.
BRMPricingServices_v2 BRMPricingServices12_v2	/metro/jaxws/BRMPricingService /metro/jaxws/BRMPricingService12	Defines the pricing web service, which includes the following opcodes: PCM_OP_PRICE_COMMIT_PRODUCT PCM_OP_PRICE_GET_DISCOUNT_INFO PCM_OP_PRICE_GET_PRODUCT_INFO PCM_OP_PRICE_COMMIT_DISCOUNT PCM_OP_PRICE_GET_PRICE_LIST
BRMPymtServices_v2 BRMPymtServices12_v2	/metro/jaxws/BRMPymtService /metro/jaxws/BRMPymtService12	Defines the payment web service, which includes the following opcode: PCM_OP_PYMT_COLLECT See "Payment FM Standard Opcodes" in BRM Opcode Guide for more information.
BRMReadServices_v2 BRMReadServices12_v2	/metro/jaxws/BRMReadService /metro/jaxws/BRMReadService12	Defines the read web service, which includes the following opcodes: PCM_OP_READ_FLDS PCM_OP_READ_OBJ PCM_OP_SEARCH PCM_OP_TEST_LOOPBACK See "LDAP Base Opcodes" in BRM Opcode Guide for more information.
BRMSubscriptionServices_v2 BRMSubscriptionServices12_v2	/metro/jaxws/BRMSubscriptionService /metro/jaxws/BRMSubscriptionService12	Defines the subscription web service, which includes the following opcodes: PCM_OP_SUBSCRIPTION_CANCEL_DEAL PCM_OP_SUBSCRIPTION_CANCEL_PRODUCT PCM_OP_SUBSCRIPTION_CANCEL_DISCOUNT PCM_OP_SUBSCRIPTION_CANCEL_SUBSCRIPTION PCM_OP_SUBSCRIPTION_CHANGE_DEAL PCM_OP_SUBSCRIPTION_GET_HISTORY PCM_OP_SUBSCRIPTION_PURCHASE_DEAL PCM_OP_SUBSCRIPTION_PURCHASE_FEES PCM_OP_SUBSCRIPTION_READ_ACCT_PRODUCTS PCM_OP_SUBSCRIPTION_SERVICE_BALGRP_TRANSFER PCM_OP_SUBSCRIPTION_SET_BUNDLE PCM_OP_SUBSCRIPTION_SET_DISCOUNT_STATUS PCM_OP_SUBSCRIPTION_SET_DISCOUNTINFO PCM_OP_SUBSCRIPTION_SET_PRODINFO PCM_OP_SUBSCRIPTION_SET_PRODUCT_STATUS PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION PCM_OP_SUBSCRIPTION_TRANSITION_DEAL PCM_OP_SUBSCRIPTION_TRANSITION_PLAN PCM_OP_SUBSCRIPTION_GET_PURCHASED_OFFERINGS PCM_OP_SUBSCRIPTION_ORDERED_BALGRP PCM_OP_SUBSCRIPTION_ORDERED_BALGRP_BULK_MODIFY PCM_OP_SUBSCRIPTION_CALC_QUOTE See "Subscription Management FM Standard Opcodes" in BRM Opcode Guide for more information.
BRMDataExportServices_v2	/metro/jaxws/BRMDataExportServices_v2	Defines a SOAP 1.1 proxy for the supported BI Publisher report-service operations. Configure bip.endpoint, bip.userId, and the wallet-supplied bip.passwd before using this service.

Configuring BRM to Use PCM_OP_BAL_GET_ECE_BALANCES

Before you can call the PCM_OP_BAL_GET_ECE_BALANCES opcode, you must configure BRM to support the opcode. To do so, add the following entries to your Connection Manager (CM) configuration file (BRM_home/sys/cm/pin.conf):

- cm em_group ece PCM_OP_BAL_GET_ECE_BALANCES
- cm em_pointer ece_bal ip emGateway_host emGateway_port

where:

• emGateway_host is the name or IP address of the server on which External Manager (EM) Gateway is running.

• emGateway_port is the number of the port through which EM Gateway connects to the host.

Stop and restart the CM for the changes to take effect.

Example of Reading Account Fields in BRM Using Web Services

This section provides an example of reading selected fields from an account object using web services when OAuth 2.0 is not configured.

See "Sending SOAP Requests to BRM Web Services" for information about sending requests to Web Services Manager if OAuth 2.0 is enabled.

To read selected fields from an account object in BRM using web services, call the pcmOpReadFlds web service API, which maps to the PCM_OP_READ_FLDS opcode. The pcmOpReadFlds web service API is included in the BRMReadServices_v2 web service, which contains web service APIs for read operations. See "About WSDL Files and BRM Opcodes" for more information about the web services included in the Web Services Manager package.

You use URLs to create SOAP clients for web services. The URL is generated by JAX-WS. See "Determining the WSDL URLs for Web Services Manager" for information about generating the WSDL URLs.

A sample URL for the BRMReadServices_v2 web service is:

http://hostname:port/metro/jaxws/BRMReadService

Note:

When OAuth 2.0 is enabled, clients must include a valid access token in each SOAP request. When OAuth 2.0 is disabled, Web Services Manager does not perform HTTP username and password authentication.

Determining the WSDL URLs for Web Services Manager

To find the WSDL URLs in Web Services Manager, go to the following URL:

https://hostname:port/metro

where:

• hostname is the name or IP address for Web Services Manager.

• port is the port number for Web Services Manager.

Web Services Manager displays the WSDL URLs for each available service.

Sample SOAP Request and Response XML Files

The following samples pair each SOAP request for the pcmOpReadFlds web service API with its corresponding response. Replace hostname:port and the account POID with values for your BRM deployment. An empty ACCOUNT_NO element selects that field for reading. Response values vary by account and request; each response includes a generated CONTEXT_INFO/CORRELATION_ID.

XML-string Payload, SOAP 1.1 (jaxws_str)

Endpoint

https://hostname:port/metro/jaxws_str/BRMReadService

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:bus="http://xmlns.oracle.com/BRM/schemas/BusinessOpcodes/">
  <soapenv:Header/>
  <soapenv:Body>
    <bus:pcmOpReadFlds>
      <flags>0</flags>
      <PCM_OP_READ_FLDS_request><![CDATA[
        <PCM_OP_READ_FLDS_inputFlist>
          <POID>0.0.0.1 /account 1 0</POID>
          <ACCOUNT_NO/>
        </PCM_OP_READ_FLDS_inputFlist>
      ]]></PCM_OP_READ_FLDS_request>
    </bus:pcmOpReadFlds>
  </soapenv:Body>
</soapenv:Envelope>

Response

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:pcmOpReadFldsResponse xmlns:ns2="http://xmlns.oracle.com/BRM/schemas/BusinessOpcodes/">
      <PCM_OP_READ_FLDS_response><![CDATA[<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<brm:PCM_OP_READ_FLDS_outputFlist xmlns:brm="http://xmlns.oracle.com/BRM/schemas/BusinessOpcodes">
  <brm:ACCOUNT_NO>ROOT</brm:ACCOUNT_NO>
  <brm:CONTEXT_INFO>
    <brm:CORRELATION_ID>generated-per-request</brm:CORRELATION_ID>
  </brm:CONTEXT_INFO>
  <brm:POID>0.0.0.1 /account 1 13</brm:POID>
</brm:PCM_OP_READ_FLDS_outputFlist>]]></PCM_OP_READ_FLDS_response>
    </ns2:pcmOpReadFldsResponse>
  </S:Body>
</S:Envelope>

XML-string Payload, SOAP 1.2 (jaxws_str)

Endpoint

https://hostname:port/metro/jaxws_str/BRMReadService12

Request

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
               xmlns:bus="http://xmlns.oracle.com/BRM/schemas/BusinessOpcodes/">
  <soap:Header/>
  <soap:Body>
    <bus:pcmOpReadFlds>
      <flags>0</flags>
      <PCM_OP_READ_FLDS_request><![CDATA[
        <PCM_OP_READ_FLDS_inputFlist>
          <POID>0.0.0.1 /account 1 0</POID>
          <ACCOUNT_NO/>
        </PCM_OP_READ_FLDS_inputFlist>
      ]]></PCM_OP_READ_FLDS_request>
    </bus:pcmOpReadFlds>
  </soap:Body>
</soap:Envelope>

Response

<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
  <S:Body>
    <ns2:pcmOpReadFldsResponse xmlns:ns2="http://xmlns.oracle.com/BRM/schemas/BusinessOpcodes/">
      <PCM_OP_READ_FLDS_response><![CDATA[<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<brm:PCM_OP_READ_FLDS_outputFlist xmlns:brm="http://xmlns.oracle.com/BRM/schemas/BusinessOpcodes">
  <brm:ACCOUNT_NO>ROOT</brm:ACCOUNT_NO>
  <brm:CONTEXT_INFO>
    <brm:CORRELATION_ID>generated-per-request</brm:CORRELATION_ID>
  </brm:CONTEXT_INFO>
  <brm:POID>0.0.0.1 /account 1 13</brm:POID>
</brm:PCM_OP_READ_FLDS_outputFlist>]]></PCM_OP_READ_FLDS_response>
    </ns2:pcmOpReadFldsResponse>
  </S:Body>
</S:Envelope>

XML-element Payload, SOAP 1.1 (_v2)

Endpoint

https://hostname:port/metro/jaxws/BRMReadService

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:bus="http://xmlns.oracle.com/BRM/schemas/BusinessOpcodes">
  <soapenv:Header/>
  <soapenv:Body>
    <bus:pcmOpReadFldsRequest>
      <bus:PCM_OP_READ_FLDS_Request>
        <bus:flags>0</bus:flags>
        <bus:PCM_OP_READ_FLDS_inputFlist>
          <bus:POID>0.0.0.1 /account 1 0</bus:POID>
          <bus:ACCOUNT_NO/>
        </bus:PCM_OP_READ_FLDS_inputFlist>
      </bus:PCM_OP_READ_FLDS_Request>
    </bus:pcmOpReadFldsRequest>
  </soapenv:Body>
</soapenv:Envelope>

Response

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Header/>
  <S:Body>
    <brm:pcmOpReadFldsResponse xmlns:brm="http://xmlns.oracle.com/BRM/schemas/BusinessOpcodes">
      <brm:ACCOUNT_NO>ROOT</brm:ACCOUNT_NO>
      <brm:CONTEXT_INFO>
        <brm:CORRELATION_ID>generated-per-request</brm:CORRELATION_ID>
      </brm:CONTEXT_INFO>
      <brm:POID>0.0.0.1 /account 1 13</brm:POID>
    </brm:pcmOpReadFldsResponse>
  </S:Body>
</S:Envelope>

XML-element Payload, SOAP 1.2

Endpoint

https://hostname:port/metro/jaxws/BRMReadService12

Request

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
               xmlns:bus="http://xmlns.oracle.com/BRM/schemas/BusinessOpcodes">
  <soap:Header/>
  <soap:Body>
    <bus:pcmOpReadFldsRequest>
      <bus:PCM_OP_READ_FLDS_Request>
        <bus:flags>0</bus:flags>
        <bus:PCM_OP_READ_FLDS_inputFlist>
          <bus:POID>0.0.0.1 /account 1 0</bus:POID>
          <bus:ACCOUNT_NO/>
        </bus:PCM_OP_READ_FLDS_inputFlist>
      </bus:PCM_OP_READ_FLDS_Request>
    </bus:pcmOpReadFldsRequest>
  </soap:Body>
</soap:Envelope>

Response

<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
  <S:Header/>
  <S:Body>
    <brm:pcmOpReadFldsResponse xmlns:brm="http://xmlns.oracle.com/BRM/schemas/BusinessOpcodes">
      <brm:ACCOUNT_NO>ROOT</brm:ACCOUNT_NO>
      <brm:CONTEXT_INFO>
        <brm:CORRELATION_ID>generated-per-request</brm:CORRELATION_ID>
      </brm:CONTEXT_INFO>
      <brm:POID>0.0.0.1 /account 1 13</brm:POID>
    </brm:pcmOpReadFldsResponse>
  </S:Body>
</S:Envelope>

Using Metrics and Tracing

Web Services Manager includes additional tracing and metric reporting capabilities.

More information is contained in the following topics:

• Working with Metrics in Web Services Manager

• Enabling Tracing

Working with Metrics in Web Services Manager

Web Services Manager provides tracing and metric reporting capabilities. Metric reporting is enabled by default.

Web Services Manager exposes metric data in Prometheus format. Prometheus can scrape this data, and you can use compatible dashboard software to visualize the collected metrics.

The following metric scopes are available:

• base: Operating system or Java runtime measurements

• vendor: HTTP request and key performance indicator measurements provided by the underlying web server

• application: Metrics registered in the application code. Web Services Manager supports application metrics that track requests for XML-element-based invocations. Web Services Manager records successful and failed calls separately with the status label values success and fail. The following metrics are available:

  • http_request_duration_seconds_count: Contains the number of recorded calls for the specified API and status.

  • http_request_duration_seconds: Contains estimated response-duration quantiles, in seconds, for 0.5, 0.75, 0.95, 0.98, 0.99, and 0.999.

  • http_request_duration_seconds_max: Contains the maximum response duration, in seconds, in the current rolling metrics window.

  • http_request_duration_seconds_sum: Contains the sum of the recorded response durations, in seconds, for the specified API and status.

Application metrics for an individual API are included when the API is invoked through an XML-element-based web service. The api label identifies the API. For example:

http_request_duration_seconds{api="PCM_OP_READ_FLDS",status="success",quantile="0.5",scope="application"} 0.125

This illustrative metric indicates that, for successful PCM_OP_READ_FLDS calls in the application scope, the estimated median (0.5 quantile) response duration is 0.125 seconds.

The illustrative sample shows the minimum set of labels for this application metric. Depending on the deployment and metrics collection pipeline, additional labels can be attached to the scraped time series during service discovery, relabeling, or ingestion.

To access the metrics, use the Web Services Manager metrics URL:

https://hostname:port/observe/metrics

To filter the metrics by scope, use the Web Services Manager metrics URL with the scope query parameter:

https://hostname:port/observe/metrics?scope=scope

where scope is one of the following: base, vendor, or application.

Enabling Tracing

Tracing provides visibility into Web Services Manager request processing and internal operations. This information helps you identify the source of performance issues. You can view tracing information using Zipkin, which is an open source tracing system. For more information about Zipkin and its user interface, see the Zipkin website. For more tracing configuration options, see the Tracing Guide in the Helidon documentation: https://helidon.io/docs/v4/se/tracing.

When tracing is enabled, the logs generated by Web Services Manager for each request contain the associated trace identifier in the trace-id[...] field. You can use the trace identifier to troubleshoot request-processing issues.

To enable and configure tracing:

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

2. Ensure that the tracing.enabled entry is set to true, which is the default:

   tracing.enabled=true

3. Set the following entries to the tracing collector's host name or IP address and listening port, respectively. Web Services Manager exports spans to the tracing collector, such as Zipkin:

   tracing.host=hostname
   tracing.port=port

4. Save and close the file.

5. Stop and restart the Web Services Manager. See "Starting and Stopping Web Services Manager".