Activity Opcode Workflows

5 Activity Opcode Workflows

Learn about the Oracle Communications Billing and Revenue Management (BRM) activity opcode workflows.

For information about the activity opcodes, see "Activity FM Policy Opcodes" and "Activity FM Standard Opcodes" .

Topics in this document:

Opcodes Described in This Chapter

Table 5-1 lists the opcodes described in this chapter.

Caution:

Always use the BRM API to manipulate data. Changing data in the database without using the API can corrupt the data.
Do not use SQL commands to change data in the database. Always use the API.

Table 5-1 Opcodes Described in This Chapter

Opcode	Topic
PCM_OP_ACT_END_SESSION	Recording Session Events Recording the End of a Session
PCM_OP_ACT_FIND_VERIFY	Starting Sessions
PCM_OP_ACT_LOAD_SESSION	Loading Sessions
PCM_OP_ACT_LOGIN	Starting Sessions
PCM_OP_ACT_LOGOUT	Recording the End of a Session
PCM_OP_ACT_POL_PROCESS_EVENTS	Customizing News Feed Values and Events
PCM_OP_ACT_POL_REQUEST_CREATE	Recording Failed Operations
PCM_OP_ACT_REQUEST_CREATE	Recording Failed Operations
PCM_OP_ACT_REQUEST_RETRIEVE	Retrieving Operation Failure Records
PCM_OP_ACT_START_SESSION	Recording the Start of a Session Starting Sessions Updating a Session Event
PCM_OP_ACT_UPDATE_SESSION	Updating a Session Event
PCM_ACT_USAGE	Managing Sessions
PCM_OP_PROCESS_EVENTS	Customizing News Feed Values and Events

Managing Sessions

BRM uses PCM_OP_ACT_USAGE to manage session events. For example, this opcode is called for a user login session.

Note:

This opcode is called by the other session opcodes. Do not call PCM_OP_ACT_USAGE directly.

PCM_OP_ACT_USAGE takes as input an /account object POID and a type-only POID that specifies the type of event being recorded.

BRM stores information about sessions in /event/session objects in the BRM database.

Starting Sessions

Use PCM_OP_ACT_LOGIN to start a session.

PCM_OP_ACT_LOGIN performs these operations:

Calls PCM_OP_ACT_FIND_VERIFY to verify the identity of the account.

PCM_OP_ACT_FIND_VERIFY also checks whether the account specified during login is locked and whether the password entered is valid. If the password entered is not valid, it does the following:
- Increments PIN_FLD_LOGIN_ATTEMPTS.
- Locks the account if PIN_FLD_LOGIN_ATTEMPTS equals the value specified in the MaxLoginAttempts entry in the bus_params_act.xml file.
These checks are applicable only to /service/pcm_client and /service/admin_client.
Calls PCM_OP_ACT_START_SESSION to start a login session.
Returns the user's /account POID.

PCM_OP_ACT_LOGIN is usually called by PCM_CONNECT, but it is also called directly. If called by PCM_CONNECT, this opcode ignores the database number in the application's pin.conf file and searches all schemas for the account.

PCM_OP_ACT_LOGIN also stores the PIN_FLD_NAP_IP_ADDRESS in the /event/session object on successful login. This information is used for logging CSR activities.

Recording the Start of a Session

Use PCM_OP_ACT_START_SESSION to record the start of a session event. This opcode records any type of session event object including details specific to the event type.

Sessions can be started for either /account or /service objects. The /account object must be specified for both cases.

When the /account object is used alone, PCM_OP_ACT_START_SESSION starts a session for the /account object.
When both /account and /service object POIDs are specified, PCM_OP_ACT_START_SESSION starts a session for the /service object.
When a NULL /service object is specified, PCM_OP_ACT_START_SESSION starts a session for the /account object.

Session details are recorded in the base /event/session object. You can create an inherited class from the /event/session object and add fields to describe a specific type of session in more detail.

When a session of the specified type occurs, the input flist to PCM_OP_ACT_START_SESSION can specify the type of event object to create with the PIN_OBJ_TYPE field and include the detailed information fields in the PIN_FLD_INHERITED_INFO substructure. This enables any amount of detail to be recorded for any number of session types.

In the PIN_FLD_INHERITED_INFO array, the program supplies a new storable class definition. You determine the fields necessary in the new inherited storable class type and define them by using PIN_MAKE_FLD. This procedure is explained in the pcm.h file. PCM_OP_ACT_START_SESSION then automatically creates storable class definitions and supplies updated release files containing the new storable class definitions.

BRM controls how PCM_OP_ACT_START_SESSION records the start of a session event by using these flags:

PCM_OPFLG_READ_RESULT

When this flag is set, PCM_OP_ACT_START_SESSION returns all fields in the event object in addition to the /account POID.
PCM_OPFLG_CALC_ONLY
- When this flag is set, PCM_OP_ACT_START_SESSION returns the fields that would have been used to create the event object. No fields in the database are changed, and the event object is not actually created.
- When the flag is not set, PCM_OP_ACT_START_SESSION creates an /event/session object to record the details of the session event.

Updating a Session Event

Use PCM_OP_ACT_UPDATE_SESSION to update information in a session event.

Note:

The session event object must already have been created by a call to PCM_OP_ACT_START_SESSION or by an opcode that calls that opcode.

PCM_OP_ACT_UPDATE_SESSION updates the PIN_FLD_DESCR field and any inherited data fields in the session object. Only the fields specified in the opcode's input flist are updated; all other fields in the /event/session object are left unchanged. This opcode uses the generalized PIN_FLD_INHERITED_INFO substruct so it can update /event/session objects of any type.

At the end of sessions, PCM_OP_ACT_UPDATE_SESSION records the session end time.

Recording the End of a Session

Use PCM_OP_ACT_LOGOUT to record the end of a login session. It calls PCM_OP_ACT_END_SESSION to end the session and assess any changes.

Recording Session Events

Use PCM_OP_ACT_END_SESSION to record the end of a session event. PCM_OP_ACT_END_SESSION performs these operations:

Records the session's ending timestamp.
Updates the PIN_FLD_DESCR field and any inherited data fields in the /event/session object.
Returns the following, depending on the flags passed in:
- When the PCM_OPFLG_READ_RESULT flag is set, this opcode returns all fields in the event object, in addition to the POID.
- When the PCM_OPFLG_CALC_ONLY flag is set, this opcode returns the fields that would have been used to create the event object. No fields in the database are changed, and the event object is not actually created.
- When no flags are set, this opcode returns the POID of the event object.

Loading Sessions

Use PCM_OP_ACT_LOAD_SESSION to create and record a session event as a single operation. This opcode is valuable as a tool to load sessions in real time.

Customizing News Feed Values and Events

Use the PCM_OP_ACT_POL_PROCESS_EVENTS to process events and update the database with news feed entries. The PCM_OP_ACT_POL_PROCESS_EVENTS policy opcode is called by the PCM_OP_PROCESS_EVENTS standard opcode.

Use the PCM_OP_ACT_POL_PROCESS_EVENTS policy opcode to customize values in the news feed and to add new events for the news feed.

As input, this opcode takes the following information:

PIN_FLD_EVENT: Specifies the events.
PIN_FLD_TYPE: Specifies the type of news feed, which differentiates the news feed category from other news feeds.
PIN_FLD_REASON_ID: Specifies the reason code for news feed, which links to the localized name of the news feed category.
PIN_FLD_MESSAGE: Specifies the summary information for the news feed. The message has the following format:
```
numeric_ID1;;numeric_ID2|~|placeholder_value1|~| placeholder_value2
```
where:
- numeric_IDN is an unique identifier that maps to the reason code in the localization message. You can add multiple numeric IDs separated by ;;.
- placeholder_valueN is the value that replaces the placeholder character in the localization message for the corresponding numeric ID. The placeholder values are separated by |~|.
For example:
```
132;;133|~|P1-1|~|10003
```
which displays the following message:
```
Payment reversed
P1-1 original payment, 10003
```
PIN_FLD_FLAGS: Specifies whether to create the /newsfeed object or not.
- If it is set to 1, this opcode creates a new /newsfeed object.
- If it is set to 0, this opcode does not create a new /newsfeed object.

Managing Operation Failure Records

Use the following opcodes to manage operation failure records, which are stored in /request/failed, /request/failed/opcode, and /request/failed/rest objects:

To create an operation failure record, use PCM_OP_ACT_REQUEST_CREATE. See "Recording Failed Operations".
To customize an operation failure record before it is saved in the database, use PCM_OP_ACT_POL_REQUEST_CREATE. See "Recording Failed Operations".
To retrieve one or more operation failure records, use PCM_OP_ACT_REQUEST_RETRIEVE. See "Retrieving Operation Failure Records".
To delete an account and all operation failure records associated with it, use PCM_OP_CUST_DELETE_ACCT. See "Deleting Accounts".

To view the input and output flist specifications for these opcodes, see BRM Opcode Flist Reference.

Recording Failed Operations

Use the PCM_OP_ACT_REQUEST_CREATE opcode to record failed operations in a /request/failed, /request/failed/opcode, or /request/failed/rest object. For more information about these objects, see Storable Class Reference.

To record details about a failed operation, customize your client application to replace sensitive information, such as passwords, in the request payload with dummy data. Then, your client application must call the PCM_OP_ACT_REQUEST_CREATE opcode and pass the following information in the opcode's input flist:

PIN_FLD_PARTIAL set to the status of the payload: complete (0) or incomplete (1). Incomplete indicates that sensitive information was dropped from the payload and will need to be added before the operation is reprocessed.
PIN_FLD_STATUS set to the status of the operation: successful (0), failed (1), or written off (2). Written off indicates that the failed operation does not need to be reprocessed and can be deleted.
PIN_FLD_TYPE_STR set to the MIME type of the payload, such as text/pin_flist for opcode flists or application/json for REST APIs.
PIN_FLD_PAYLOAD_STR contains the payload data from the request in string format.
Details about the error or failure.

PCM_OP_ACT_REQUEST_CREATE does the following:

Converts the payload into a buffer field.
Converts any error or failure details into a buffer field.
Calls the PCM_OP_ACT_POL_REQUEST_CREATE policy opcode to customize details about the failed operation. By default, the opcode does nothing.
Creates a /request/failed, /request/failed/opcode, or /request/failed/rest object. In multischema systems, the object is created in the same schema in which the operation failed.
Creates an /event/notification/request/create notification event.

Retrieving Operation Failure Records

Use the PCM_OP_ACT_REQUEST_RETRIEVE opcode to retrieve one or more /request/failed, /request/failed/opcode, or /request/failed/rest objects.

To retrieve a specific /request object, pass the POID of the /request object in the opcode's input flist.

To retrieve all /request objects based on specific criteria, pass the type-only POID for the /request object as well as the following optional input:

To retrieve records for a specific account, pass PIN_FLD_ACCOUNT_OBJ set to the /account object POID.
To retrieve records with a specific status, pass PIN_FLD_STATUS set to 0 (Successful), 1 (Failed), or 2 (Written Off).
To retrieve records created by a specific client application, pass PIN_FLD_PROGRAM set to the name of the calling program.