pdc rest services manager integration guide · 2020. 12. 18. · oracle® communications billing...

Oracle® Communications Billing andRevenue ManagementPDC REST Services Manager IntegrationGuide

Release 12.0F36879-01December 2020

Oracle Communications Billing and Revenue Management PDC REST Services Manager Integration Guide,Release 12.0

F36879-01

Copyright © 2020, Oracle and/or its affiliates.

This software and related documentation are provided under a license agreement containing restrictions onuse and disclosure and are protected by intellectual property laws. Except as expressly permitted in yourlicense agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverseengineering, disassembly, or decompilation of this software, unless required by law for interoperability, isprohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. Ifyou find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it onbehalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs (including any operating system, integrated software,any programs embedded, installed or activated on delivered hardware, and modifications of such programs)and Oracle computer documentation or other Oracle data delivered to or accessed by U.S. Governmentend users are "commercial computer software" or "commercial computer software documentation" pursuantto the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such,the use, reproduction, duplication, release, display, disclosure, modification, preparation of derivative works,and/or adaptation of i) Oracle programs (including any operating system, integrated software, any programsembedded, installed or activated on delivered hardware, and modifications of such programs), ii) Oraclecomputer documentation and/or iii) other Oracle data, is subject to the rights and limitations specified in thelicense contained in the applicable contract. The terms governing the U.S. Government’s use of Oracle cloudservices are defined by the applicable contract for such services. No other rights are granted to the U.S.Government.

This software or hardware is developed for general use in a variety of information management applications.It is not developed or intended for use in any inherently dangerous applications, including applications thatmay create a risk of personal injury. If you use this software or hardware in dangerous applications, then youshall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure itssafe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of thissoftware or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks oftheir respective owners.

Intel and Intel Inside are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks areused under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Epyc,and the AMD logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registeredtrademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products,and services from third parties. Oracle Corporation and its affiliates are not responsible for and expresslydisclaim all warranties of any kind with respect to third-party content, products, and services unless otherwiseset forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will notbe responsible for any loss, costs, or damages incurred due to your access to or use of third-party content,products, or services, except as set forth in an applicable agreement between you and Oracle.

Contents

Preface

Audience v

Documentation Accessibility v

1 PDC REST Services Manager Overview

About PDC REST Services Manager 1-1

About Setting Up PDC REST Services Manager 1-3

About Monitoring PDC REST Services Manager 1-3

2 Setting Up OAuth Authentication for PDC REST Services Manager

About Authentication and Authorization 2-1

Creating Confidential OAuth Applications 2-1

Requesting an OAuth Access Token 2-2

3 Configuring Inbound Communications to PDC REST ServicesManager

Authenticating Inbound PDC REST Services Manager Requests 3-1

Securing Inbound Communications 3-3

Encrypting Sensitive Data 3-4

4 Configuring Outbound Communications from PDC REST ServicesManager

Configuring Outbound Requests to the Enterprise Product Catalog 4-1

Securing Outbound Requests to PDC 4-3

5 Mapping Product Offerings

About Mapping Product Offerings 5-1

Mapping Setup Components 5-1

iii

Mapping Charge Offers from TMF620 to PDC 5-4

PDC Charge Offer Default Values 5-7

Mapping Discount Offers from TMF620 to PDC 5-9

PDC Discount Offer Default Values 5-11

Mapping Bundles from TMF620 to PDC 5-13

PDC Bundle Default Values 5-13

Mapping Packages from TMF620 to PDC 5-14

PDC Package Default Values 5-15

6 Monitoring PDC REST Services Manager

About Logging 6-1

Accessing the Logs 6-2

Changing the Log Levels 6-3

Configuring the Log Format 6-4

About Tracing 6-5

Enabling Tracing 6-6

Using Trace Tags to Troubleshoot Issues 6-6

About Metrics 6-12

Checking Access to Metrics 6-13

About Monitoring System Health 6-14

iv

Preface

This guide describes how to use Pricing Design Center (PDC) REST ServicesManager to integrate PDC with product catalog software.

AudienceThis guide is intended for system administrators and those involved in systemintegration.

Documentation AccessibilityFor information about Oracle's commitment to accessibility, visit theOracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic supportthrough My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trsif you are hearing impaired.

v

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs

1PDC REST Services Manager Overview

This document describes how to integrate Oracle Communications Pricing DesignCenter (PDC) with an enterprise product catalog by using PDC REST ServicesManager.

Topics in this document:

• About PDC REST Services Manager

• About Setting Up PDC REST Services Manager

• About Monitoring PDC REST Services Manager

About PDC REST Services ManagerPDC REST Services Manager integrates an enterprise product catalog, such asOracle Digital Experience for Communications Launch Experience, with PDC. Thisenables you to create a variety of product offerings in your enterprise product catalogand then have all the rating and billing performed by PDC and Oracle CommunicationsBilling and Revenue Management (BRM).

You can synchronize the following elements from an enterprise product catalog toPDC:

• One-time, recurring, and usage charges, with or without discounts

• Quantity and tier-based pricing and discounting

• Effective dates for charges and discounts

• Validity periods for discounts and noncurrency balance credits

• Shared discounts

• Noncurrency balance credits

• Discounts used as counters for noncurrency balance credits to charge overagefees

• Charges based on event and service attributes

• Bundles and packages

Note:

Quantity-based pricing is supported in PDC for usage charges only, and notfor one-time or recurring charges.

The enterprise product catalog publishes the product offering objects to registeredbilling-spoke systems using TMF620 APIs. PDC REST Services Managersynchronizes this data and then transforms it to charge offers, discount offers,bundles, and packages in the PDC-BRM system.

1-1

Figure 1-1 shows the PDC REST Services Manager architecture and its integrationpoints with the enterprise product catalog and PDC.

Figure 1-1 PDC REST Services Manager Architecture

In this figure, PDC REST Services Manager, the enterprise product catalog, and PDCinteract as follows:

1. The enterprise product catalog sends a notification to PDC REST ServicesManager about new or updated product offerings. This communication can beencrypted using TLS.

2. PDC REST Services Manager uses OAuth 2.0 to authenticate the notification fromthe enterprise product catalog.

3. The PDC REST Services Manager event listener sends the authenticatedmessage to the PDC REST Services Manager product offering integration service.

4. PDC REST Services Manager requests an OAuth token to use with a call to theenterprise product catalog.

5. PDC REST Services Manager calls the enterprise product catalog TMF620 API toquery for data about the new or updated product offerings.

6. PDC REST Services Manager transforms the product offering data and submits itto PDC and BRM. This communication can be encrypted using T3S.

7. The PDC REST Services Manager product offering integration service sends amessage to the PDC REST Services Manager acknowledgment service.

8. PDC REST Services Manager requests an OAuth token to use with a call to theenterprise product catalog.

Chapter 1About PDC REST Services Manager

1-2

9. PDC REST Services Manager publishes an acknowledgment notification to theenterprise product catalog.

Throughout all interactions, you can log, trace, and collect metrics for messagespassing through the system. You can use this data to troubleshoot errors and monitorthe overall health of the system. See "Monitoring PDC REST Services Manager".

About Setting Up PDC REST Services ManagerYou set up PDC REST Services Manager by performing the following high-level tasks:

1. Install PDC REST Services Manager. See "Installing PDC REST ServicesManager" in PDC Installation Guide.

2. Set up PDC REST Services Manager to authenticate requests from yourenterprise product catalog. See "Setting Up OAuth Authentication for PDC RESTServices Manager".

3. Configure all communication from your enterprise product catalog to PDC RESTServices Manager. See "Configuring Inbound Communications to PDC RESTServices Manager".

4. Configure communication from PDC REST Services Manager to both PDC andyour enterprise product catalog. See "Configuring Outbound Communications fromPDC REST Services Manager".

5. Create setup components in all applications, then map the product offerings fromthe TMF620 API fields in your enterprise product catalog to equivalent fields inPDC and BRM. See "Mapping Product Offerings".

About Monitoring PDC REST Services ManagerYou can monitor PDC REST Services Manager to confirm successful integration, trackoverall system health, and troubleshoot issues.

Monitoring PDC REST Services Manager involves the following tasks:

• Monitoring system logs. See "About Logging."

• Tracing events with tools like Jaeger. See "About Tracing."

• Monitoring metrics with tools like Prometheus. See "About Metrics."

• Monitoring system status. See "About Monitoring System Health."

Chapter 1About Setting Up PDC REST Services Manager

1-3

2Setting Up OAuth Authentication for PDCREST Services Manager

This document describes how to set up the OAuth 2.0 protocol to authenticate anenterprise product catalog's identity and to authorize the enterprise product catalogto access Oracle Communications Pricing Design Center (PDC) using PDC RESTServices Manager.


• About Authentication and Authorization

• Creating Confidential OAuth Applications

• Requesting an OAuth Access Token

About Authentication and AuthorizationPDC REST Services Manager uses the OAuth 2.0 protocol to authenticate theenterprise product catalog's identity and to authorize the enterprise product catalogto access the PDC REST Services Manager API. It does this by validating an OAuthaccess token that is passed in the header of every HTTP/HTTPS request to the PDCREST Services Manager API.

To set up authentication and authorization for your enterprise product catalog, youperform these high-level tasks:

1. Add your enterprise product catalog as a confidential application to Oracle IdentityCloud Service (IDCS).

2. Request an OAuth access token from IDCS.

3. Verify that your connection works by sending a request to the PDC REST ServicesManager API.

For example, you could send a request to the metrics endpoint at this URL:https://hostname:port/metrics, where hostname is the URL for the PDC RESTServices Manager server and port is the TLS port for the PDC REST ServicesManager server.

4. Pass the OAuth access token in the header of every HTTP/HTTPS request sent tothe PDC REST Services Manager APIs.

Creating Confidential OAuth ApplicationsAdd your enterprise product catalog as a confidential application to IDCS by followingthe instructions in "Add a Confidential Application" in Administering Oracle IdentityCloud Service. When adding the confidential application, ensure that you:

• Select a client type of confidential application.

2-1

https://docs.oracle.com/en/cloud/paas/identity-cloud/uaids/add-confidential-application.html

• Add a scope named pubevent for accessing the Publish Event endpoint in PDCREST Services Manager.

• Add a scope named metrics for accessing the Metrics endpoint in PDC RESTServices Manager.

After you add the confidential application, IDCS provides you with the followinginformation. Note it down, because you will need it when requesting an OAuth accesstoken and when configuring inbound communication to PDC REST Services Manager.

• The IDCS URL for requesting OAuth access tokens. For example:

https://idcs_hostname/oauth2/v1/token

where idcs_hostname is the hostname of the server of your IDCS instance

• The primary audience URL

• The client ID and client secret

Requesting an OAuth Access TokenRequest an OAuth access token from IDCS to include in requests to the PDC RESTServices Manager APIs. For more information, see "Generate Access Token andOther OAuth Runtime Tokens to Access the Resource" in REST API for Oracle IdentityCloud Service.

For example, to request an OAuth access token using cURL, you could send thisHTTP/HTTPS request to the IDCS URL:

curl -i-H "Authorization: Basic encoded_credentials" \-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \--request POST https://idcs_hostname/oauth2/v1/token \-d 'grant_type=client_credentials&scope=scope'

where:

• encoded_credentials is either the client ID and client secret (clientID:clientSecret)or user name and password (username:password) in Base64-encoded format.

• idcs_hostname is the hostname of your IDCS instance.

• scope is one of the following, where primaryAudience is the hostname and port ofyour confidential application.

– https://primaryAudience/pubevent: Authorizes access to the Publish Eventendpoint.

– https://primaryAudience/metrics: Authorizes access to the Metrics endpoint.

After you submit the request, IDCS returns an OAuth access token. This shows anexample OAuth access token from a request:

{"access_token":"eyJ4NXQjUzI1NiI6InRtMjNSeVo0WGpHZmo4NDdzaEg2ZVJELVlkQlNSd 21pWnZSY2M4QUoteEkiLCJ4NXQiOiI0X0ZBa3ZuN3RhaUIxTHdaZUJpaE95ZFpRV0EiLCJ..

Chapter 2Requesting an OAuth Access Token

2-2

https://docs.oracle.com/en/cloud/paas/identity-cloud/rest-api/op-oauth2-v1-token-post.html

https://docs.oracle.com/en/cloud/paas/identity-cloud/rest-api/op-oauth2-v1-token-post.html

.", "token_type":"Bearer","expires_in":3600,

Chapter 2Requesting an OAuth Access Token

2-3

3Configuring Inbound Communications toPDC REST Services Manager

This document describes how to configure Oracle Communications Pricing DesignCenter (PDC) REST Services Manager to receive inbound communication from anenterprise product catalog.


• Authenticating Inbound PDC REST Services Manager Requests

• Securing Inbound Communications

• Encrypting Sensitive Data

Authenticating Inbound PDC REST Services ManagerRequests

To configure PDC REST Services Manager to authenticate inbound requests fromyour enterprise product catalog:

1. Open the PDC_RSM_home/apps/conf/application.yaml file in a text editor,where PDC_RSM_home is the directory in which you installed PDC RESTServices Manager.

2. Edit the keys shown in Table 3-1.

Table 3-1 Keys in the application.yaml File

Key Description

security.enabled Specifies whether to enable or disable inbound security:

• true: Enable security• false: Disable securitySet this to true for production systems.

security.properties.idcs-uri The base URL of your Oracle Identity Cloud Service(IDCS) instance in this format:

https://idcs-TenantID.identity.oraclecloud.com

security.properties.idcs-client-id

The client ID for your confidential application.

security.properties.idcs-client-secret

The Base64-encrypted client secret obtained from yourIDCS application.

For security purposes, do not store the client secret inplain-text. To encrypt the client secret, see "EncryptingSensitive Data".

3-1

Table 3-1 (Cont.) Keys in the application.yaml File

Key Description

security.properties.frontend-uri

The base URL of your confidential application when run.For example:

http://localhost:8080

security.properties.audience The primary audience as provisioned for the PDC RESTServices Manager application in IDCS. For example:

http://localhost:8080/

Note: Ensure that you include the trailing slash in theURL.

security.properties.proxy-host

The hostname of the proxy server, if required.

security.web-server.paths.<0>.abac.scopes

The scope defined in IDCS for protecting the TMF620publishEvent endpoint.

security.web-server.paths.<1>.abac.scopes

The scope defined in IDCS for protecting the metricsendpoint.

3. Save and close your application.yaml file.

4. Restart PDC REST Services Manager by running the following command from thePDC_RSM_home/apps/bin directory:

./RestServicesManager.sh restart

The following shows sample entries in the application.yaml file:

security: config.require-encryption: true enabled: true properties: idcs-uri: "https://idcs-216d960ac5894f81a5985b39f6b0c6c6.identity.c9dev2.oc9qadev.com" idcs-client-id: "498e7032bdf046798bec10cd165d025a" idcs-client-secret: ${GCM=5pPUsDKbtvoxL/uS3TUwZEeGmEMtEjdjURMmHaTFukUlD4t//h7LEsU9jPydN2zqpiOKlRRT6a0S6OS/cGHfHdk8zOal4M6M5vrj7031TlU=} frontend-uri: "http://localhost:8080" audience: "http://localhost:8080/" proxy-host: "" providers: - abac: # Adds ABAC Provider - it does not require any configuration - oidc: validate-with-jwk: false client-id: "${ALIAS=security.properties.idcs-client-id}" client-secret: "${ALIAS=security.properties.idcs-client-secret}" identity-uri: "${ALIAS=security.properties.idcs-uri}" realm: "pdcrsm" audience: "${ALIAS=security.properties.audience}" proxy-host: "${ALIAS=security.properties.proxy-host}" redirect: false cookie-use: false

Chapter 3Authenticating Inbound PDC REST Services Manager Requests

3-2

header-use: true # Comment/Uncomment/Override for protection of resources web-server: paths: - path: "/productCatalogManagement/v1/projectPublishEvent[/{*}]" methods: ["get", "post"] authenticate: true authorize: true abac: scopes: ["pubevent"] - path: "/metrics[/{*}]" methods: ["get"] authenticate: true authorize: true abac: scopes: ["metrics"]

Securing Inbound CommunicationsYou secure communications sent from your enterprise product catalog to the PDCREST Services Manager APIs by enabling TLS in PDC REST Services Manager.

To secure inbound communications to PDC REST Services Manager:

1. Create a PKCS12 certificate file.

2. Copy the PKCS12 certificate file to a location that is accessible by PDC RESTServices Manager, such as ~/certs.

3. Edit the following entries in the PDC_RSM_home/apps/conf/application.yamlfile:

• server.ssl.private-key.keystore-path: Set this to the file system path of thePKCS12 file containing the X.509 certificate and private key.

• server.ssl.private-key.keystore-passphrase: Set this to the password forthe PKCS12 file. For example, if you used OpenSSL to create the PKCS12certificate file, set it to the export password. For security, encrypt the passwordso it is not stored in clear text. See "Encrypting Sensitive Data" for moreinformation.

Note:

Set the server.ssl.private-key.keystore-passphrase key only if thePKCS file was created using a password.

For example:

server: ... ssl: private-key: keystore-path: "/scratch/ri-user-1/certs/certificate.p12" keystore-

Chapter 3Securing Inbound Communications

3-3

passphrase: "${GCM=/YAL6hA0iSmxW8Z8X6PX6KasUTuYuGRvjRyg21/Dl8oymJya0RZ3Ar8ViZvrmzVxqSrJgHskPZUzsq7GhzLUWWHE}"



Encrypting Sensitive DataYou can encrypt sensitive data, such as passwords, by using theRestServicesManager.sh script.

To encrypt sensitive data:

1. Go to the PDC_RSM_home/apps/bin directory, where PDC_RSM_home is thedirectory in which you installed PDC REST Services Manager.

2. Run the following command:

./RestServicesManager.sh hash

The Enter value to hash prompt appears.

3. Enter the sensitive information that you want to encrypt.

The encrypted password is displayed.

For example:

$ ./RestServicesManager.sh hash

Enter value to hash: ************************************

${GCM=TUuP9coMwC66B28FFufhfbeMLcxollF4eOLqDhs88mOnuwcHGyBap+ORPjOB5N3UnT5/ESkriICXOfPZUHCvwvs54KP9SyzJZJLFaGIv3Yo=}

Chapter 3Encrypting Sensitive Data

3-4

4Configuring Outbound Communicationsfrom PDC REST Services Manager

This document describes how to configure Oracle Communications Pricing DesignCenter (PDC) REST Services Manager to send requests to an enterprise productcatalog and to PDC.


• Configuring Outbound Requests to the Enterprise Product Catalog

• Securing Outbound Requests to PDC

Configuring Outbound Requests to the Enterprise ProductCatalog

PDC REST Services Manager sends requests to the enterprise product catalog when:

• Calling the enterprise product catalog API

• Publishing acknowledgment notifications

To configure PDC REST Services Manager to send requests to the enterprise productcatalog:


2. Edit the keys in the file based on the type of authentication required by yourenterprise product catalog:

• For OAuth 2.0 authentication, edit the keys underapp.httpClients.security.oauth2. See "OAuth 2.0 Authentication".

• For basic authentication, edit the keys underapp.httpClients.security.basicAuth. See "Basic Authentication".

Note:

All urlRegex values in the file must be properly escaped with \\. Thecharacters that must be escaped are: \.[]{}()<>*+-=!? ^$|.

3. Save and close your application.yaml file.



4-1

OAuth 2.0 Authentication

Table 4-1 describes the keys to configure when your enterprise productcatalog uses an OAuth 2.0 authentication type. All keys are nested underapp.httpClients.security.oauth2.

Table 4-1 OAuth 2.0 Keys

Key Description

tokenEndpoint The endpoint used to retrieve a token from.

clientId The client ID used to authenticate the request from PDC REST ServicesManager.

clientSecret The encrypted client secret used to authenticate the request from PDCREST Services Manager.

To encrypt the client secret, see "Encrypting Sensitive Data".

scope The scopes required by the enterprise product catalog.

grantType The grant type to be used for the OAuth flow: client_credentials orpassword.

username The user name required for accessing the enterprise product catalog.

Set this only when grantType is password.

password The encrypted password required for accessing the enterprise productcatalog.

To encrypt the password, see "Encrypting Sensitive Data".

Set this only when grantType is password.

The following shows an example configuration when grantType is client_credentials.

app: httpClients: - urlRegex: "local.*:8889" security: oauth2: tokenEndpoint: "http://hostname/oauth2/v1/token" clientId: "ClientID" clientSecret: "EncryptedClientSecret" scope: "https://hostnameurn:opc:resource:consumer::all" grantType: "client_credentials"

The following shows an example configuration when grantType is password:

app: httpClients: - urlRegex: "local.*:8889" security: oauth2: tokenEndpoint: "http://hostname:8889/oauth2/v1/token" clientId: "ClientID" clientSecret: "EncryptedClientSecret" scope: "https://hostnameurn:opc:resource:consumer::all" grantType: "password"

Chapter 4Configuring Outbound Requests to the Enterprise Product Catalog

4-2

username: "ApplicationUsername" password: "EncryptedApplicationPassword"

Basic Authentication

Table 4-2 describes the keys to configure when your enterprise productcatalog uses a Basic authentication type. All keys are nested underapp.httpClients.security.basicAuth.

Table 4-2 basicAuth Parameters

Key Description

username The user name required for accessing the enterpriseproduct catalog.

password The password required for accessing the enterprise productcatalog.

The following shows an example configuration for Basic authentication:

app: httpClients: - urlRegex: "local.*:8889" security: basicAuth: username: "ApplicationUsername" password: "ApplicationPassword"

Securing Outbound Requests to PDCDuring installation, the PDC REST Services Manager installer prompts you for theinformation required to connect PDC REST Services Manager to PDC. To secure thecommunications from PDC REST Services Manager to PDC, enable the T3S protocolin PDC REST Services Manager.

To enable T3S in PDC REST Services Manager:

1. Go to the PDC_RSM_home/apps/conf directory.

2. In the application.yaml file, set the app.pdc.url key to the T3S protocol and asecure PDC port.

For example:

app: pdc: url: "t3s://pdc.example.com:8002"



Chapter 4Securing Outbound Requests to PDC

4-3

If you want to change it to use the insecure T3 protocol, set the app.pdc.url key to theT3 protocol and an insecure PDC port. For example:

app: pdc: url: "t3://pdc.example.com:8001"

Chapter 4Securing Outbound Requests to PDC

4-4

5Mapping Product Offerings

This document describes how to map product offering data in Oracle CommunicationsPricing Design Center (PDC) REST Services Manager so it can transform the TMF620data to PDC and Oracle Communications Billing and Revenue Management (BRM)data.


• About Mapping Product Offerings

• Mapping Charge Offers from TMF620 to PDC

• Mapping Discount Offers from TMF620 to PDC

• PDC Charge Offer Default Values

• PDC Discount Offer Default Values

• Mapping Setup Components

About Mapping Product OfferingsTo enable PDC REST Services Manager to transform your product offering data, youmust first create setup components in BRM, PDC, and the enterprise product catalog,then map the TMF620 data from your enterprise product catalog to PDC.

Note:

PDC REST Services Manager supports only the base TMF620 specificationsalong with select vendors' extensions based on business drivers.Your enterprise product catalog vendor is responsible for defining andpublishing any TMF620 vendor-specific API extensions. Your vendor'spublished TMF620 API will include the TMF620 ProductOffering payload,ProductOfferingPrice payload, and other payloads as well as the notificationevent payloads that PDC REST Services Manager or any other consumer ofthe enterprise product catalog must support.

The following sections show the mappings between TMF620 data and the PDC andBRM data schema. They also list the default values for PDC and BRM data fieldswhen TMF620 has no corresponding field.

Mapping Setup ComponentsIn BRM, setup components are the prerequisite data that you configure before creatingproduct offerings. You create some in BRM and synchronize them to PDC, and youcreate others in PDC. There is currently no synchronization flow between PDC orBRM and the enterprise product catalog for setup components. You must create

5-1

them independently in PDC and the enterprise product catalog, and configure yourenterprise product catalog to send data in the TMF620 payload that matches what youhave created in PDC.

Table 5-1 lists the setup components that you configure in BRM and PDC beforecreating your product offerings. It provides details about how PDC REST ServicesManager maps data in the TMF620 payload to the setup components.

Table 5-1 Setup Component Mapping

Setup Component Mapping Details

Services BRM includes preconfigured services, and you cancreate custom services. You synchronize services fromBRM to PDC with the syncPDC utility. See "Setting upService and Event Definitions" in PDC Creating ProductOfferings for more information.

In the TMF620 payload, your enterprise product catalogmust send case-sensitive values in the name propertyof the ServiceSpecification object that are identical tothe BRM services names.

Ratable Usage Metrics (RUMs) In BRM, a RUM specifies the units for measuring eventsand how to calculate the measurement. You can basea measurement on any data captured in an event, suchas how long a session lasted or the number of bytesdownloaded during a session.

You create RUMs in PDC. See "Configuring RatableUsage Metrics (RUMs)" in PDC Creating ProductOfferings.

In the TMF620 payload, for usage charges, yourenterprise product catalog must send case-sensitivevalues in the units property of the Quantity object thatare identical to RUM names.

For one-time or recurring charges, PDC REST ServicesManager automatically selects the Occurence RUM.

Chapter 5Mapping Setup Components

5-2

Table 5-1 (Cont.) Setup Component Mapping


Service-event map In BRM, the service-event map lets you configure whichcharge events can be used for a service and whichRUMs can be used for each service-event combination.The service-event map links each supported service tothe events that can have charges configured for thatservice.

You create the service-event map in PDC. See "SettingUp the Service-Event Map" in PDC Creating ProductOfferings.

PDC REST Services Manager uses the name propertyof the ServiceSpecification object and the priceTypeproperty of the ProductOfferingPrice to look up eventsin the service-event map. PDC REST Services Managerexpects the following values for priceType in theTMF620 payload to match BRM service-event mapping:

• ONE_TIME to map toEventBillingProductFeePurchase

• RECURRING, with recurringChargePeriodTypeparameter value of:– DAILY to map to

EventBillingProductFeeCycleCycle_forward_daily

– MONTHLY to map toEventBillingProductFeeCycleCycle_forward_monthly

– BI_MONTHLY to map toEventBillingProductFeeCycleCycle_forward_bimonthly

– QUARTERLY to map toEventBillingProductFeeCycleCycle_forward_quarterly

– SEMI_ANNUAL to map toEventBillingProductFeeCycleCycle_forward_semiannual

– ANNUAL to map toEventBillingProductFeeCycleCycle_forward_yearly

• USAGE to map to EventSessionServiceNamewhere ServiceName is the name of theServiceSpecification object, which is identicalto a BRM service name, such asEventSessionTelcoGSM.

For the events mapped to the ONE_TIME andRECURRING values, PDC REST Services Managerautomatically maps the Occurrence RUM.

Chapter 5Mapping Setup Components

5-3

Table 5-1 (Cont.) Setup Component Mapping


Balance elements In BRM, a balance element represents one of thefollowing:

• A currency or non-currency asset of economicvalue, such as US dollars or included minutes

• A counter that tracks items such as dollars spent orminutes talked

You configure balance elements in PDC. See"Configuring Balance Elements" in PDC CreatingProduct Offerings.

In the TMF620 payload:

• For currency balance elements, your enterpriseproduct catalog must send case-sensitive ISO 4217standard 3-character currency codes in the unitproperty of the Money object that are identical tothe PDC balance element IDs.

• For non-currency balance elements, your enterpriseproduct catalog must send case-sensitive valuesin the units property of the unitOfMeasure objectthat are identical to PDC non-currency balanceelement names.

Tax codes In BRM, a tax code indicates which tax to apply on theprice of the product offering.

You create tax codes in BRM and synchronize themto PDC with the SyncPDC utility. See "Creating TaxCodes" in BRM Calculating Taxes.

In the TMF620 payload, your enterprise productcatalog must send case-sensitive values in thetaxCode property of the Tax object in the extendedProductOfferingPriceOracle object that are identical tothe BRM tax code names.

General ledger (G/L) IDs In BRM, G/L IDs ensure that charges are reported tothe correct account in your company's general ledger.

You create G/L IDs in BRM and synchronize them toPDC with the SyncPDC utility. See "About G/L IDs" inBRM Collecting General Ledger Data.

In the TMF620 payload, your enterprise product catalogmust send case-sensitive values in the glid property ofthe extended ProductOfferingPriceOracle object thatare identical to the BRM G/L ID description.

For more information about these setup components, and others, see "About SetupComponents" in PDC Creating Product Offerings.

Mapping Charge Offers from TMF620 to PDCTable 5-2 shows how to map charge offer data from TMF620 fields to PDC fields.

Chapter 5Mapping Charge Offers from TMF620 to PDC

5-4

Table 5-2 TMF620 Charge Offer Mappings for PDC REST Services Manager

TMF Base Object TMF ExtendedObject

TMF620 Field PDC Field PDC FieldDescription

ProductOffering NA ProductOffering.name

chargeOffering.name Charge OfferingName

ProductOffering NA ProductOffering.description

chargeOffering.description

Charge OfferingDescription

ProductOffering NA ProductOffering.id chargeOffering.externalID

Charge OfferingExternal ID

ProductOffering NA ProductOffering.id chargeRatePlan.externalID

Charge Rate PlanExternal ID

ProductOffering NA ProductOffering.ServiceCandidate.name

chargeOffering.productSpecName

Charge OfferingProduct Spec Name


chargeRatePlan.permittedName

Charge Rate PlanPermitted Name

ProductOfferingPrice ProductOfferingPriceOracle

ProductOffering.productOfferingPrice[n].name

chargeOffering.chargeEventMap.chargeRatePlanName

Charge Rate PlanName



chargeRatePlan.name

Charge Rate PlanName


ProductOffering.productOfferingPrice[n].description

chargeRatePlan.description

Charge Rate PlanDescription

ProductOfferingPrice ProductOfferingPriceOracle.TaxItemOracle

ProductOffering.productOfferingPrice[n].tax[n].taxTime

chargeRatePlan.taxTime

Tax TimeIf a valueis provided fortaxCode, PDC RESTServices Managerautomatically setsthe value fortaxTime to BILLING.Otherwise, taxTimeis set to NONE.

ProductOfferingPrice ProductOfferingPriceOracle.TaxItemOracle

ProductOffering.productOfferingPrice[n].tax[n].taxCode

chargeRatePlan.taxCode

Tax Code

ProductOfferingPrice ProductOfferingPriceOracle.Money

ProductOffering.productOfferingPrice[n].price.unit

chargeRatePlan.subscriberCurrency.currencyCode

Currency Code

ProductOfferingPrice ProductOfferingPriceOracle.TimePeriodOracle

• For non-tieredrates:ProductOffering.productOfferingPrice[n].validFor

• For tiered rates:ProductOffering.productOfferingPrice[n].pricingLogicAlgorithmOracle.TierRange.productOfferingPrice[x].validFor

chargeRatePlan.subscriberCurrency.crpRelDateRange.absoluteDateRange.startDateNote: All tieredProductOfferingPriceobjects contained inthe same TierRangemust have the samestart date. If thedates don't match,the ProductOfferingis rejected.

Start Date


5-5

Table 5-2 (Cont.) TMF620 Charge Offer Mappings for PDC REST Services Manager




• For non-tieredrates:ProductOffering.productOfferingPrice[n].validFor


chargeRatePlan.subscriberCurrency.crpRelDateRange.absoluteDateRange.endDateNote: All tieredProductOfferingPriceobjects contained inthe same TierRangemust have the sameend date. If thedates don't match,the ProductOfferingis rejected.

End Date

ProductOfferingPrice ProductOfferingPriceOracle.PricingLogicAlgorithmOracle.TierRangeOracle

ProductOffering.productOfferingPrice[n].pricingLogicAlgorithmOracle.TierRange.minQuantity

chargeRatePlan.subscriberCurrency.crpRelDateRange...lowerBound

Lower Bound

ProductOfferingPrice ProductOfferingPriceOracle.PricingLogicAlgorithmOracle.TierRangeOracle

ProductOffering.productOfferingPrice[n].pricingLogicAlgorithmOracle.TierRange.maxQuantity

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange.upperBound

Upper Bound


ProductOffering.productOfferingPrice[n].price.value

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...price

Price

ProductOfferingPrice ProductOfferingPriceOracle.Quantity

ProductOffering.productOfferingPrice[n].unitOfMeasure

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...unitOfMeasure

UnitOfMeasure



chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...balanceElementNumCode

Balance ElementNum Code


ProductOffering.productOfferingPrice[n].unitOfMeasure.amount

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...incrementStep

Increment Step


ProductOffering.productOfferingPrice[n].glid

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...glid

GLID

ProductOfferingPrice ProductOfferingPriceAllowanceOracle.UnitOfMeasure

ProductOffering.productOfferingPrice[n].unitOfMeasure.units

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...balanceElementNumCode



5-6

Table 5-2 (Cont.) TMF620 Charge Offer Mappings for PDC REST Services Manager




The negative value ofProductOffering.productOfferingPrice[n].unitOfMeasure.amountThe negative valueis used because inBRM, non-currencybalance elements aretreated as credits, notdebits.

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...price

Price


ProductOffering.productOfferingPrice[n].unitOfMeasure.amountApplicable whenProductOfferingPrice[n].priceType is setto usage.

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...incrementStep

Increment Step


ProductOffering.productOfferingPrice[n].unitOfMeasureIf this is specified, theImpactType value isset to SCALED. Ifnot, ImpactType isset to FIXED.

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...ImpactType

Impact Type



chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...glid

GLIDThe GLID value isbased on the chargeoffer'sProductOfferingPriceobject associatedwith theProductOfferingPriceAllowanceOracleobject.

ProductOfferingPrice ProductOfferingPriceAllowanceOracle.AllowanceValidity

ProductOffering.productOfferingPrice[n].allowanceValidity

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...PriceValidity

Price Validity

PDC Charge Offer Default ValuesTable 5-3 lists the default values for PDC charge offer fields when TMF620 has nocorresponding field.

Chapter 5PDC Charge Offer Default Values

5-7

Table 5-3 PDC Charge Offer Default Values

PDC Field Default Value

chargeOffering.applicableQtyTreatment ApplicableQuantityTreatmentJXB.CONTINUOUS

chargeOffering.applicableQuantity ApplicableQuantityJXB.REMAINING

chargeOffering.chargeEventMap.incrementQuantity

BigDecimal.valueOf(1)

chargeOffering.chargeEventMap.incrementQuantityUnit

NONE

chargeOffering.chargeEventMap.minQuantity BigDecimal.valueOf(0)

chargeOffering.chargeEventMap.minQuantityUnit

NONE

chargeOffering.chargeEventMap.prorateFirst ProrationValueJXB.PRORATE_CHARGE

chargeOffering.chargeEventMap.prorateLast ProrationValueJXB.PRORATE_CHARGE

chargeOffering.chargeEventMap.roundingMode

RoundingModeJXB.NEAREST

chargeOffering.chargeEventMap.timezoneMode

TimeZoneModeJXB.EVENT

chargeOffering.chargeEventMap.validIfCancelled

false

chargeOffering.chargeEventMap.validIfInactive false

chargeOffering.pricingProfileName Product Offering

chargeOffering.TimeRange 0/inf

chargeRatePlan.applicableQtyTreatment ApplicableQuantityTreatmentJXB.CONTINUOUS

chargeRatePlan.applicableQuantity ApplicableQuantityJXB.ORIGINAL

chargeRatePlan.billOffset BigInteger.valueOf(0)

chargeRatePlan.cycleFeeFlag BigInteger.valueOf(0)

chargeRatePlan.permittedType PermittedTypeJXB.PRODUCT

chargeRatePlan.pricingProfileName ONE TIME/ RECURRING - Subscription

USAGE - Convergent Usage

chargeRatePlan.subscriberCurrency.crpRelDateRange...priceTier.distributionMethod

pricingType - TIERED -DistributionMethodJXB.FROM_BAL_IMPACT

pricingType - SIMPLE -DistributionMethodJXB.NONE

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...discountable

ONE TIME/ RECURRING - true

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...impactType

ONE TIME/ RECURRING - SCALED

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...incrementRounding

USAGE - IncrementRoundingJXB.NONE

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...priceType

PriceTypeJXB.CONSUMPTION

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...proratable

RECURRING - true

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange.enforceCreditLimit

ONE TIME/ RECURRING - true

USAGE - false

Chapter 5PDC Charge Offer Default Values

5-8

Table 5-3 (Cont.) PDC Charge Offer Default Values


chargeRatePlan.todMode TODModeJXB.START_TIME

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...unitOfMeasure

UnitOfMeasureJXB.NONE

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...isDiscountable

false

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...priceType

PriceTypeJXB.GRANT

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...relativeStartOffset

-1

chargeOffering.chargeEventMap.validIfCancelled

false

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...proratableUsed when priceType is set to recurring.

true

chargeRatePlan.subscriberCurrency.crpRelDateRange...tierRange...incrementRoundingUsed when priceType is set to usage.

IncrementRoundingJXB.NONE

Mapping Discount Offers from TMF620 to PDCTable 5-4 shows how to map discount offer data from TMF620 fields to PDC fields.

Table 5-4 TMF620 Discount Offer Mappings for PDC REST Services Manager




alterationOffering.nameNote: To distinguishbetween analterationOffering anda chargeOffering in aProductOffering, thealterationOffering.name consists of theProductOffering.name with the string"_DISCOUNT"appended.

Alteration OfferingName


alterationOffering.description

Alteration OfferingDescription

ProductOffering NA ProductOffering.id alterationOffering.externalId

Alteration OfferingExternal ID

ProductOffering NA ProductOffering.id alterationRatePlan[n].externalId

Alteration RateExternal ID


alterationOffering.productSpecName

Alteration OfferingProduct Spec Name

Chapter 5Mapping Discount Offers from TMF620 to PDC

5-9

Table 5-4 (Cont.) TMF620 Discount Offer Mappings for PDC REST Services Manager





alterationRatePlan[n].name

Alteration Rate PlanName



alterationOffering.alterationEventMap.alterationRatePlanName



ProductOffering.productOfferingPrice[n].description

alterationRatePlan[n].description

Alteration Rate PlanDescription


• For non-tieredrates:ProductOffering.productOfferingPrice[n].validFor.startDateTime


alterationRatePlan[n].arpDateRange.startDateNote: All tieredProductOfferingPriceobjects contained inthe same TierRangemust have the samestart date. If thedates don't match,the ProductOfferingis rejected.

Start Date


• For non-tieredrates:ProductOffering.productOfferingPrice[n].validFor.endDateTime


alterationRatePlan[n].arpDateRange.endDateNote: All tieredProductOfferingPriceobjects contained inthe same TierRangemust have the sameend date. If thedates don't match,the ProductOfferingis rejected.

End Date



alterationRatePlan[n].arpDateRange...balanceElementNumCode




alterationRatePlan[n].arpDateRange...currencyCode

Currency Code



alterationRatePlan[n].arpDateRange...glid



ProductOffering.productOfferingPrice[n].price.value

alterationRatePlan[n].arpDateRange...fixedAlteration.price

Price

Chapter 5Mapping Discount Offers from TMF620 to PDC

5-10

Table 5-4 (Cont.) TMF620 Discount Offer Mappings for PDC REST Services Manager




ProductOffering.productOfferingPrice[n].percentage

alterationRatePlan[n].arpDateRange...percentAlteration.price

Percentage

ProductSpecification ProductSpecificationOracle.ServiceSpecification

ProductOffering.ProductSpecification.ServiceSpecification.name

alterationOffering.productSpecName

Alteration OfferingProduct Spec Name

ProductOffering ProductOfferingPriceOverageOracle.unitOfMeasure.units


alterationRatePlan[n].arpCompositePopModel.alterationPopModel.priceTier.tierRange.upperBound.balanceTBExpression.balanceElementNumCode

Balance ElementNumeric Code

ProductOffering ProductOfferingPriceOverageOracle.unitOfMeasure.units


alterationRatePlan[n].arpDateRange.alterationConfiguration.arpCompositePopModel.alterationPopModel.priceTier.tierRange.fixedAlteration.balanceElementNumCode

Balance ElementNumeric Code

ProductOffering ProductOfferingPriceOracle


alterationRatePlan[n].arpDateRange.alterationConfiguration.arpCompositePopModel.alterationPopModel.priceTier.tierRange.fixedAlteration.glid2

GLIDNote: The GLIDvalue is based on thediscount offer'sProductOfferingPriceobject associatedwith theProductOfferingPriceOverageOracleobject.

PDC Discount Offer Default ValuesTable 5-5 lists the default values for PDC discount offer fields when TMF620 has nocorresponding field.

Table 5-5 PDC Discount Offer Default Values for PDC REST Services Manager


alterationOffering.pricingProfileName Product Offering

alterationOffering.TimeRange 0/inf

alterationOffering.OfferType OfferTypeJXB.SUBSCRIPTION

alterationOffering.applicableQuantity ApplicableChargeAndQuantityJXB.REMAINING_CHARGE

alterationOffering.Priority 0

alterationOffering.OwnMin -1

alterationOffering.OwnMax -1

Chapter 5PDC Discount Offer Default Values

5-11

Table 5-5 (Cont.) PDC Discount Offer Default Values for PDC REST ServicesManager


alterationOffering.PurchaseMin -1

alterationOffering.PurchaseMax -1

alterationOffering.alterationEventMap.ValidIfCancelled

false

alterationOffering.alterationEventMap.ValidIfInactive

false

alterationOffering.alterationEventMap.Snowball

false

alterationOffering.alterationEventMap.ValidAtStartNotValidAtEnd

AlterationProrationValueJXB.PRORATE_DISCOUNT

alterationOffering.alterationEventMap.NotValidAtStartValidAtEnd


alterationOffering.alterationEventMap.NotValidAtStartNotValidAtEnd


alterationRatePlan[n].arpDateRange.alterationConfiguration.arpCompositePopModel.alterationPopModel.priceTier.tierRange.fixedAlteration.price

1.0

alterationRatePlan[n].arpDateRange.alterationConfiguration.arpCompositePopModel.alterationPopModel.priceTier.tierRange.fixedAlteration.unitOfMeasure

UnitOfMeasureJXB.NONE

alterationRatePlan[n].arpDateRange.alterationConfiguration.arpCompositePopModel.alterationPopModel.priceTier.tierRange.fixedAlteration.alterationAppliesTo

AlterationRecipientTypeJXB.USER

alterationRatePlan[n].arpDateRange.alterationConfiguration.arpCompositePopModel.alterationPopModel.priceTier.tierRange.fixedAlteration.alterationBasedOn.useTierComponent

true

alterationRatePlan[n].arpDateRange.alterationConfiguration.arpCompositePopModel.alterationPopModel.priceTier.tierRange.fixedAlteration.priceType

PriceTypeJXB.CONSUMPTION

alterationRatePlan[n].arpDateRange.alterationConfiguration.arpCompositePopModel.alterationPopModel.priceTier.tierRange.fixedAlteration.incrementStep

1

alterationRatePlan[n].arpDateRange.alterationConfiguration.arpCompositePopModel.alterationPopModel.priceTier.tierRange.fixedAlteration.prorateLastIncrementStep

true

alterationRatePlan[n].arpDateRange.alterationConfiguration.arpCompositePopModel.alterationPopModel.priceTier.tierRange.fixedAlteration.priceValidity.startValidityMode

StartValidityModeJXB.IMMEDIATE

Chapter 5PDC Discount Offer Default Values

5-12

Table 5-5 (Cont.) PDC Discount Offer Default Values for PDC REST ServicesManager


alterationRatePlan[n].arpDateRange.alterationConfiguration.arpCompositePopModel.alterationPopModel.priceTier.tierRange.fixedAlteration.priceValidity.endValidityMode

EndValidityModeJXB.NEVER

alterationRatePlan[n].arpDateRange.alterationConfiguration.arpCompositePopModel.alterationPopModel.priceTier.tierRange.fixedAlteration.priceValidity.validityRange

"0/inf"

alterationRatePlan[n].arpDateRange.alterationConfiguration.arpCompositePopModel.alterationPopModel.priceTier.tierRange.fixedAlteration.priceValidity.relativeStartOffst

-1

alterationRatePlan[n].arpDateRange.alterationConfiguration.arpCompositePopModel.alterationPopModel.priceTier.tierRange.fixedAlteration.priceValidity.relativeEndOffset

-1

Mapping Bundles from TMF620 to PDCTable 5-6 shows how to map bundle data from TMF620 fields to PDC fields.

Table 5-6 TMF620 Bundle Mappings for PDC REST Services Manager




BundledProductOffering.name

BundledProductOffering Name


BundledProductOffering.description

BundledProductOffering Description


BundledProductOfferingItem.alterationOfferingName

BundledProductOfferingItem AlterationOffering Name


BundledProductOfferingItem.chargeOfferingName

BundledProductOfferingItem ChargeOffering Name


ProductOffering.productOfferingPrice[n].unitOfMeasure.amount

BundledProductOfferingItem.quantity

BundledProductOfferingItem Quantity

PDC Bundle Default ValuesTable 5-6 lists the default values for PDC bundle fields when TMF620 has nocorresponding field.

Chapter 5Mapping Bundles from TMF620 to PDC

5-13

Table 5-7 PDC Bundle Default Values


BundledProductOffering.pricingProfileName Product Offering

BundledProductOffering.TimeRange 0/inf

BundledProductOffering.priceListName Default

BundledProductOffering.obsolete false

BundledProductOffering.billOnPurchase true

BundledProductOffering.customize CustomizeTypeJXB.OPTIONAL

BundledProductOffering.groupBalanceElements

true

BundledProductOffering.statusCode 0L

BundledProductOffering.status 1L

Validity.mode ValidityModeJXB.NOW_TO_NEVER

Validity.offset 0L

BundledProductOfferingItem.cycleStart Validity

BundledProductOfferingItem.cycleEnd Validity

BundledProductOfferingItem.purchaseStart Validity

BundledProductOfferingItem.purchaseEnd Validity

BundledProductOfferingItem.usageStart Validity

BundledProductOfferingItem.usageEnd Validity

BundledProductOfferingItem.purchaseChargeAdjustment

0.0

BundledProductOfferingItem.cycleChargeAdjustment

0.0

BundledProductOfferingItem.usageChargeAdjustment

0.0

Mapping Packages from TMF620 to PDCTable 5-8 shows how to map package data from TMF620 fields to PDC fields.

Table 5-8 TMF620 Package Mappings for PDC REST Services Manager




Package.name Package Name


Package.description Package Description


Package.productSpecPackageItem.productSpecName.bundledProductOfferingAssociation.bundledProductOfferingName

Bundle Name

Chapter 5Mapping Packages from TMF620 to PDC

5-14

Table 5-8 (Cont.) TMF620 Package Mappings for PDC REST Services Manager



ProductSpecification ProductSpecificationOracle.ServiceSpecification

ProductSpecification.ServiceSpecification.name

Package.productSpecPackageItem.name

BundledProductOfferingItem AlterationOffering Name

ProductSpecification ProductSpecificationOracle.SerivceSpecification

ProductSpecification.ServiceSpecification.name

Package.productSpecPackageItem.productSpecName

Package ProductSpec Name

PDC Package Default ValuesTable 5-6 lists the default values for PDC package fields when TMF620 has nocorresponding field.

Table 5-9 PDC Package Default Values


Package.pricingProfileName subscription

Package.priceListName Default

Package.obselete false

Package.billOnPurchase false

Package.productSpecPackageItem.balanceSpecificationName

Account Balance Group

Package.productSpecPackageItem.bundledProductOfferingAssociation.optional

false

Package.productSpecPackageItem.bundledProductOfferingAssociation.cancelWithService

false

Package.balanceSpecification.name Account Balance Group

Chapter 5PDC Package Default Values

5-15

6Monitoring PDC REST Services Manager

This document describes how to monitor Oracle Communications Pricing DesignCenter (PDC) REST Services Manager using logging, tracing, metrics, and systemhealth data.


• About Logging

• About Tracing

• About Metrics

• About Monitoring System Health

About LoggingYou can review the PDC REST Services Manager logs to troubleshoot errors andmonitor system activity.

PDC REST Services Manager uses the Apache Log4j Java logging utility to loginformation and errors about the following:

• Start up and shut down activity

• Interaction with other applications at integration points while processing publicationevents. This includes interactions with PDC, Oracle Identity Cloud Service, andyour enterprise product catalog.

• Authorization requests

• Authentication requests

• Tracing (see "About Tracing")

You access the logs as the user who installed PDC REST Services Manager. See"Accessing the Logs".

The logs support the standard Log4j logging levels. By default, the framework loglevels are set to INFO and the application log levels are set to DEBUG. You canchange the levels after installation. See "Changing the Log Levels."

You can configure the format of the logs. See "Configuring the Log Format."

For information about Java logging, see "Java Logging Overview" in Java Platform,Standard Edition Core Libraries. For information about Log4j, see:

https://logging.apache.org/log4j/2.x/manual/index.html

Oracle recommends using automated log file rotation for PDC REST ServicesManager logs. For information about configuring log file rotation, see My OracleSupport article 2087525.1 at:

https://support.oracle.com/knowledge/Oracle%20Linux%20and%20Virtualization/2087525_1.html

6-1

https://logging.apache.org/log4j/2.x/manual/index.html

https://support.oracle.com/knowledge/Oracle%20Linux%20and%20Virtualization/2087525_1.html

Accessing the LogsYou access the logs to monitor and troubleshoot your system.

To access the logs:

1. Log in to the system where PDC REST Services Manager was installed as theinstallation user.

2. Run the following command:

tail -f PDC_RSM_home/log/rsm.log

where PDC_RSM_home is the directory in which you installed PDC RESTServices Manager.

500FreeMinutes

2020-09-05T20:19:28.399-0700 START RestServicesManager.shpdcrsm-6f88869785-vtbw2 pdcrsm 2020-11-13T15:58:06.702Z | INFO | 9fcdb109-8682-4368-b4d5-b5b720a1af77 | 548aee87-5ef0-4c1a-b8c8-d2b8a8c6fb40 | 500FreeMinutes | 4ca071fde65d2a61 | pool-3-thread-1 | ctPublishEventServiceImpl | Processing Publish Event 548aee87-5ef0-4c1a-b8c8-d2b8a8c6fb40->500FreeMinutespdcrsm-6f88869785-vtbw2 pdcrsm 2020-11-13T15:58:07.303Z | INFO | 9fcdb109-8682-4368-b4d5-b5b720a1af77 | 548aee87-5ef0-4c1a-b8c8-d2b8a8c6fb40 | 500FreeMinutes | 4ca071fde65d2a61 | pool-3-thread-1 | ductOfferingServiceLaunch | Retrieving ProductOffering for ID OOO_DayTech201_OOOpdcrsm-6f88869785-vtbw2 pdcrsm 2020-11-13T15:58:09.088Z | INFO | 9fcdb109-8682-4368-b4d5-b5b720a1af77 | 548aee87-5ef0-4c1a-b8c8-d2b8a8c6fb40 | 500FreeMinutes | 4ca071fde65d2a61 | pool-3-thread-1 | .c.b.i.d.PdcRmiConnection | Attempting to connect to PDC using t3s://pdc-service:8002 ...pdcrsm-6f88869785-vtbw2 pdcrsm Handshake failed: TLSv1.3, error = No appropriate protocol (protocol is disabled or cipher suites are inappropriate)pdcrsm-6f88869785-vtbw2 pdcrsm Handshake succeeded: TLSv1.2pdcrsm-6f88869785-vtbw2 pdcrsm 2020-11-13T15:58:12.437Z | INFO | 9fcdb109-8682-4368-b4d5-b5b720a1af77 | 548aee87-5ef0-4c1a-b8c8-d2b8a8c6fb40 | 500FreeMinutes | 4ca071fde65d2a61 | pool-3-thread-1 | c.b.i.d.PdcDatasourceImpl | Checking if PDC object with the name "500FreeMinutes" existspdcrsm-6f88869785-vtbw2 pdcrsm 2020-11-13T15:58:12.479Z | INFO | 9fcdb109-8682-4368-b4d5-b5b720a1af77 | 548aee87-5ef0-4c1a-b8c8-d2b8a8c6fb40 | 500FreeMinutes | 4ca071fde65d2a61 | pool-3-thread-1 | o.c.b.i.s.PdcServiceImpl | Updating the PDC object "500FreeMinutes"pdcrsm-6f88869785-vtbw2 pdcrsm 2020-11-13T15:58:16.134Z | INFO | 9fcdb109-8682-4368-b4d5-b5b720a1af77 | 548aee87-5ef0-4c1a-b8c8-d2b8a8c6fb40 | 500FreeMinutes | 4ca071fde65d2a61 | pool-3-thread-1 | o.c.b.i.s.PdcServiceImpl | PDC object successfully updated for "500FreeMinutes"

See "Configuring the Log Format" for information about the format of the logs.

Chapter 6About Logging

6-2

Changing the Log LevelsYou can change the global log level and the level for PDC REST Services Managerapplication-specific log entries.

To change the log levels:

1. Open the PDC_RSM_home/apps/conf/logging-config.yaml file in a text editor,where PDC_RSM_home is the directory in which you installed PDC RESTServices Manager.

2. To change the global log level:

a. Search for the following property: -name: ROOT_LOG_LEVEL.

b. Set the value to "${env:ROOT_LOG_LEVEL:-LEVEL}", where LEVEL is the newlog level.

3. To change the PDC REST Services Manager application log level:

a. Search for the following property: -name: PDC_RSM_LOG_LEVEL.

b. Set the value to "${env:PDC_RSM_LOG_LEVEL:-LEVEL}", where LEVEL is thenew log level.

4. Save and close the file.

5. Restart PDC REST Services Manager using the control script located in the bindirectory:

PDC_RSM_home/apps/bin/RestServicesManager.sh restart

The following shows sample entries in the logging-config.yaml file, with the relevantlines and default values in bold:

Configuration: name: Default Properties: Property: - name: ROOT_LOG_LEVEL value: "${env:ROOT_LOG_LEVEL:-INFO}" - name: PDC_RSM_LOG_LEVEL value: "${env:PDC_RSM_LOG_LEVEL:-INFO}" Appenders: Console: name: LogToConsole target: SYSTEM_OUT PatternLayout: Pattern: "%d{ISO8601_OFFSET_DATE_TIME_HHCMM} | %5p | %X{eventId} | %X{projectId} | %X{productOfferId} | %X{traceId} | %-20.20thread | %-25.25logger{25} | %m%n" loggers: Root: level: "${ROOT_LOG_LEVEL}" AppenderRef:


6-3

- ref: LogToConsole Logger: - name: io.jaegertracing.internal.JaegerSpan level: error AppenderRef: - ref: LogToConsole - name: io.jaegertracing.internal.reporters level: warn AppenderRef: - ref: LogToConsole - name: oracle.communications level: "${PDC_RSM_LOG_LEVEL}" additivity: false AppenderRef: - ref: LogToConsole

Note:

The Jaeger tracing logs that appear under Logger are filtered from the logs,so you do not need to adjust their levels.

Configuring the Log FormatConfigure the log format to change the order and number of elements that appear inthe logs.

The default log format is:

%d{ISO8601_OFFSET_DATE_TIME_HHCMM} | %5p | %X{eventId} | %X{projectId} | %X{productOfferId} | %X{traceId} | %-20.20thread | %-25.25logger{25} | %m%n

Where:

• %d is the date and time of the log, in ISO 8601 format.

• %5p is the log level. See "Changing the Log Levels."

• eventId, projectId, productOfferId, and traceId are tags added for tracing eventsand objects through the system. See "Using Trace Tags to Troubleshoot Issues."

• %-20.20thread is the thread pool for the logged event.

• %-25.25logger is the service logging the event.

• %m%n is the message associated with the event.

To configure the log format:

1. Open the PDC_RSM_home/apps/conf/logging-config.yaml file in a text editor,where PDC_RSM_home is the directory in which you installed PDC RESTServices Manager.

2. Under Appenders, locate the PatternLayout property.


6-4

3. In the value for Pattern, change the order of the elements or remove anyunwanted elements.

Note:

Removing elements from the logs might reduce your ability totroubleshoot issues and trace messages.

4. Save and close the file.

5. Restart PDC REST Services Manager using the control script located in the bindirectory:

PDC_RSM_home/apps/bin/RestServicesManager.sh restart

About TracingYou can trace the flow of messages through PDC REST Services Manager by usingthe Jaeger tracer integrated with the Helidon framework, or another transaction tracingtool of your choice.

Helidon is a collection of Java libraries used by PDC REST Services Manager. Jaegeris an open-source tracing system integrated with Helidon. You can use the Jaegerinterface to monitor the PDC REST Services Manager traces.

The following figure shows an example of tracing an event through the system.On the left is a sample from the Jaeger tracer. On the right is the PDC RESTServices Manager system architecture. The numbers show how the integration pointscorrespond to the tracing flow. See "About PDC REST Services Manager" for thedetails of the flow.

You enable Jaeger tracing for PDC REST Services Manager in the application.yamlfile. See "Enabling Tracing".

Traces are tagged with various IDs to help troubleshoot and trace messages andobjects through the system. See "Using Trace Tags to Troubleshoot Issues."

Chapter 6About Tracing

6-5

For more information about Helidon and Jaeger, see:

• The Helidon project website:https://helidon.io/

• The discussion of Jaeger tracing in the Helidon documentation:https://helidon.io/docs/latest/#/se/tracing/03_jaeger

• The Jaeger website:https://www.jaegertracing.io/

Enabling TracingTo enable tracing:

1. Configure tracing in your Helidon project, as described in the Helidondocumentation: https://helidon.io/docs/latest/#/se/tracing/01_tracing


3. Under tracing, set enabled to true.

The following is a sample of the tracing section in the application.yaml file:

tracing: enabled: true service: "rsm" host: "localhost" paths: - path: "/metrics" enabled: false propagation: "jaeger" log-spans: true max-queue-size: 42 flush-interval-ms: 10001

4. Save and close the application.yaml file.



Using Trace Tags to Troubleshoot IssuesInstead of reading through logs to identify and troubleshoot issues, you can use thetrace tags to correlate logs and traces.

PDC REST Services Manager tags events with the following trace tags:

• publishId: A general tag for the event. In the example below, this is the first id.

• eventId: A tag for the event that is specific to PDC REST Services Manager. In theexample below, this is the eventId.

• projectId: A tag for the project in the enterprise product catalog. In the examplebelow, this is the id under project.


6-6

https://helidon.io/

https://helidon.io/docs/latest/#/se/tracing/03_jaeger

https://www.jaegertracing.io/

https://helidon.io/docs/latest/#/se/tracing/01_tracing

• productOfferId: A tag for a product offering. In the example below, this is the idunder each entry in the projectItems array.

• productSpecificationId: A tag for product specifications. This does not appear inthe example below, but would appear in log messages. You use the productOfferIdtag to filter logs and locate related productSpecificationId tags as needed.

The following shows an example event for publishing updates to two product offeringsfrom an enterprise product catalog to PDC. To illustrate an error scenario, a URLin the payload for the 100Minutes product offering has become corrupt. The IDscorresponding to trace tags are shown in bold.

{ "id": "d64066bd-2954-4f43-b8f2-69603c88c683", "eventId": "bd465b38-d838-4e51-ba3d-e57d46929d2b", "eventTime": "2020-11-18T09:31:50.001Z", "eventType": "projectPublishEvent", "correlationId": "UC4Fcfc6a70f-60f5-456c-93d5-d8e038215201", "domain": "productCatalogManagement", "timeOcurred": "2020-11-18T09:31:50.001Z", "event": { "project": { "id": "projectId", "lifecycleStatus": "IN_DESIGN", "name": "Project01", "acknowledgementUrl": "http://host:port/mobile/custom/PublishingAPI", "projectItems": [ { "id": "UnlimitedMinutes", "href": "http://host:port/mobile/custom/catalogManagement/productOffering/UnlimitedMinutes", "name": "UnlimitedMinutes", "version": "1.0", "@referredType": "ProductOfferingOracle" }, { "id": "100Minutes", "href": "http://host:port/mobile/custom/CORRUPTDATA/productOffering/100Minutes", "name": "100Minutes", "version": "1.0", "@referredType": "ProductOfferingOracle" } ] } }}

Trace Tags in Tracer Tools

After submitting the event, you can follow its progress and look for the trace tags in atracer tool like Jaeger.

Figure 6-1 shows excerpts from a tracer. You can immediately see that the erroroccurred in the GET request of the getProductOfferingDetails operation. You can


6-7

expand the trace spans to get the IDs for the event and the object in question, thensearch in the logs for those tags, as well as the span and trace IDs, to troubleshoot theissue.

Figure 6-1 Sample Tracer Excerpts

The following is the same data for the listenToProjectPublishEvent andgetProductOfferingDetails spans in JSON format, with the relevant IDs in the tagsarrays in bold:

{ "traceID": "f2f902949ee8e661", "spanID": "bad2ef5f3ff26084", "flags": 1, "operationName": "listenToProjectPublishEvent", "references": [ { "refType": "CHILD_OF", "traceID": "f2f902949ee8e661", "spanID": "8ce5e8f8cda38d3b" } ], "startTime": 1605709909244000, "duration": 18160, "tags": [ { "key": "eventId", "type": "string",


6-8

"value": "bd465b38-d838-4e51-ba3d-e57d46929d2b" }, { "key": "http.status_code", "type": "int64", "value": 201 }, { "key": "component", "type": "string", "value": "jaxrs" }, { "key": "span.kind", "type": "string", "value": "server" }, { "key": "http.url", "type": "string", "value": "http://host:port/productCatalogManagement/v1/projectPublishEvent" }, { "key": "http.method", "type": "string", "value": "POST" }, { "key": "projectId", "type": "string", "value": "projectId" }, { "key": "publishId", "type": "string", "value": "d64066bd-2954-4f43-b8f2-69603c88c683" }, { "key": "internal.span.format", "type": "string", "value": "jaeger" } ], "logs": [], "processID": "p1", "warnings": null },... { "traceID": "f2f902949ee8e661", "spans": [ {


6-9

"traceID": "f2f902949ee8e661", "spanID": "03031b1c18e679f2", "flags": 1, "operationName": "getProductOfferingDetails", "references": [ { "refType": "CHILD_OF", "traceID": "f2f902949ee8e661", "spanID": "528a32ac350706e2" } ], "startTime": 1605709909256000, "duration": 688729, "tags": [ { "key": "productOfferId", "type": "string", "value": "UnlimitedMinutes" }, { "key": "internal.span.format", "type": "string", "value": "jaeger" } ], "logs": [], "processID": "p1", "warnings": null },{ "traceID": "f2f902949ee8e661", "spanID": "303707dcd9c9d1ef", "flags": 1, "operationName": "getProductOfferingDetails", "references": [ { "refType": "CHILD_OF", "traceID": "f2f902949ee8e661", "spanID": "d1d2c068248a5542" } ], "startTime": 1605709909277000, "duration": 529234, "tags": [ { "key": "error", "type": "bool", "value": true }, { "key": "productOfferId", "type": "string", "value": "100Minutes" }, {


6-10

"key": "internal.span.format", "type": "string", "value": "jaeger" } ], "logs": [ { "timestamp": 1605709909807000, "fields": [ { "key": "event", "type": "string", "value": "error" }, { "key": "error.object", "type": "string", "value": "oracle.communications.brm.integration.exceptions.EccServiceException" } ] } ], "processID": "p1", "warnings": null }

Trace Tags in Logs

After finding the trace tags in the tracer tool, you can search the logs for them. You cando simple searches in the raw log data, or you can search and filter by the tags using alogging tool, such as Grafana Loki.

The trace tags appear in the following format in PDC REST Service Manager logs:

yyyy-MM-dd'T'HH:mm:ss.SSSXXX, UTC | level | eventId | projectId | productOfferId | traceId | thread | logging service | message

The following shows the success message in the logs for updating theUnlimitedMinutes product, with the relevant trace tags from the event in bold:

2020-11-14T14:29:50.508Z | INFO | bd465b38-d838-4e51-ba3d-e57d46929d2b | projectId | UnlimitedMinutes | f2f902949ee8e661 | pool-3-thread-1 | o.c.b.i.s.PdcServiceImpl | PDC object successfully updated for "UnlimitedMinutes"

For the 100Minutes product, the following error log appears:

2020-11-18T14:31:49.814Z | ERROR | bd465b38-d838-4e51-ba3d-e57d46929d2b | projectId | 100Minutes | f2f902949ee8e661 | pool-3-thread-4 | .s.LaunchPdcItemPublisher | Error calling API service 'Product Offering Service' for '100Minutes'. Status Code: 404 Error: '


6-11

Based on this message and what you saw in the tracer, you would know that PDCREST Services Manager wasn't able to make the call to the enterprise productcatalog to request information about the 100Minutes product offering. Expanding andinspecting the GET span in the tracer would reveal the corrupt URL. You could thenreview the message that came from your enterprise product catalog to confirm, andmake appropriate changes to resolve the issue.

About MetricsYou can monitor the PDC REST Services Manager metrics by using the Metrics RESTendpoint. The metrics count successful and failed messages passing through the PDCREST Services Manager integration points.

Use a monitoring tool that scrapes metrics data, such as Prometheus, to monitor themetrics available from the PDC REST Services Manager Metrics endpoint. You canget the metrics in plain text format, which is compatible with Prometheus, or JSONformat. See "Checking Access to Metrics" for information about accessing the metricsendpoint and requesting different formats. For more information about Prometheus,see: https://prometheus.io/.

The following PDC REST Services Manager metrics are available:

Integration Point Metric Description

PDC interface pdc-create-object-success-total

The number of create eventsthat returned a success fromPDC.

PDC interface pdc-create-object-error-total The number of create eventsthat returned an error fromPDC.

PDC interface pdc-update-object-success-total

The number of update eventsthat returned a success fromPDC.

PDC interface pdc-update-object-error-total The number of update eventsthat returned an error fromPDC.

Product Offer Price Project lifecycle event listener

notification-listener-change-success-total

The number of well-formedpublish events received byPDC REST Services Manager.

Product Offer Price Project lifecycle event listener

notification-listener-change-error-total

The number of publish eventsaccepted by PDC RESTServices Manager that couldnot be processed due toinvalid or incomplete eventpayloads.

Product Offering interface product-offering-get-success-total

The number of ProductOffering GET API requeststhat returned a success fromthe enterprise product catalog.

Product Offering interface product-offering-get-error-total The number of ProductOffering GET API requeststhat returned an error from theenterprise product catalog.

Chapter 6About Metrics

6-12

https://prometheus.io/

Integration Point Metric Description

Product Specification interface product-specification-get-success-total

The number of ProductSpecification GET APIrequests that returned asuccess from the enterpriseproduct catalog.

Product Specification interface product-specification-get-error-total

The number of ProductSpecification GET APIrequests that returned an errorfrom the enterprise productcatalog.

Publish Notification interface publish-job-status-success-total

The number of PublishNotification Acknowledgmentsthat returned a success fromthe enterprise product catalog.

Publish Notification interface publish-job-status-fail-total The number ofPublish Notification POSTAcknowledgments thatreturned an error from theenterprise product catalog.

Publish Product Offeringservice

publish-product-offering-success-total

The number of successfulProduct Offering Publishactions.

Publish Product Offeringservice

publish-product-offering-fail-total

The number of Failed ProductOffering Publish actions.

You can also use Helidon framework metrics. See the Helidon documentation for moreinformation: https://helidon.io/docs/v1/#/metrics/01_metrics

Checking Access to MetricsYou can access the PDC REST Services Manager metrics from any tool that canaccess REST API endpoints using an OAuth token generated by Oracle Identity CloudService for PDC REST Services Manager. You can check whether you have access byusing cURL commands.

To check whether you have access to the PDC REST Services Manager metrics:

1. In the command line on the system where cURL and your scraping tool areinstalled, export your OAuth access token with the following command:

export TOKEN=OAuth_metrics_token

where OAuth_metrics_token is the token you requested for the Metrics endpoint in"Requesting an OAuth Access Token"

2. Enter one of the following commands:

• To get the metrics in plain text format:

curl --insecure -H "Authorization: Bearer $TOKEN" https://hostname:port/metrics

where:

Chapter 6About Metrics

6-13

https://helidon.io/docs/v1/#/metrics/01_metrics

– hostname is the URL for the PDC REST Services Manager server

– port is the TLS port for the PDC REST Services Manager server

• To get the metrics in JSON format:

curl --insecure -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" https://hostname:port/metrics

About Monitoring System HealthYou can assess the health of the PDC REST Services Manager system by monitoringthe process status and overall rates of failure in logs, traces, and metrics.

To monitor process status, use the control script in PDC_RSM_home/apps/bindirectory, where PDC_RSM_home is the directory in which you installed PDC RESTServices Manager:

RestServicesManager.sh status

To maintain an active system, Oracle recommends using a service from your operatingsystem, such as systemd on Linux, to automatically start, monitor, and restart thePDC REST Services Manager system.

Chapter 6About Monitoring System Health

6-14

pdc rest services manager integration guide · 2020. 12. 18. · oracle® communications billing...

Documents