Notification Opcode Workflows

Opcodes Described in This Chapter

Table 18-1 describes the notification management opcodes.

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 18-1 Opcodes Described in This Chapter

Opcode	Topic
PCM_OP_NOTIFICATION_CALC_DELIVERY_TIME	Calculating the Notification Delivery Time
PCM_OP_NOTIFICATION_CREATE_SPECIFICATION	Creating Notification Specifications
PCM_OP_NOTIFICATION_GET_LASTNOTIFY_TSTAMP	Retrieving Last Notification Time and Offset
PCM_OP_NOTIFICATION_GET_SPECIFICATION	Retrieving Notification Specifications
PCM_OP_NOTIFICATION_MODIFY_SPECIFICATION	Modifying Notification Specifications
PCM_OP_NOTIFICATION_POL_GET_SPECIFICATION	Customizing Notification Retrieval
PCM_OP_NOTIFICATION_POL_PREP_SPECIFICATION	Preparing Notification Specifications
PCM_OP_NOTIFICATION_POL_VALID_SPECIFICATION	Validating Notification Specifications
PCM_OP_NOTIFICATION_PROCESS_NOTIFICATION	Managing In-Advance and Post-Expiration Notifications
PCM_OP_NOTIFICATION_VERIFY_PUBLISH_REQUIRED	Verifying Customer Opt-In Preferences

Creating Notification Specifications

Use the PCM_OP_NOTIFICATION_CREATE_SPECIFICATION opcode to create notification specifications, defining the customers who can receive messages through an external notification application and how and when to deliver the messages. This opcode creates a /config/notification_spec object.

You set the notification specification name, associated business event, validity dates, silent period mode, notification type, aggregation mode, opt-in type, and offset value by providing the information in the input flist.

You specify to send notifications in advance or after an event occurs by including the following in the input flist:

PIN_FLD_NOTIFICATION_SPEC.PIN_FLD_NOTIFICATION_TYPE: The type of notification set to in advance (1) or after an event occurs (5).
PIN_FLD_ADVANCE_NOTIFICATIONS.PIN_FLD_OFFSET_VALUE: The amount of time before or after an event to send a notification, such as 5 or 10.
PIN_FLD_ADVANCE_NOTIFICATIONS.PIN_FLD_OFFSET_UNIT: The unit for the offset value, which can be minutes (2), hours (3), days (4), months (5), years (6), or weeks (10).

Set the input flist spec under the PIN_FLD_NOTIFICATION_SPEC.PIN_FLD_AGGREGATE_MODE: Whether to send individual notifications for each triggering event (0) or aggregate all expiring candidates' details at respective search level

The PCM_OP_NOTIFICATION_CREATE_SPECIFICATION opcode does the following:

Validates the mandatory parameters in the input flist.
Retrieves the optional fields from the database and sets them in the input flist.
Calls the PCM_OP_NOTIFICATION_POL_VALID_SPECIFICATION policy opcode to validate the input parameters. See "Validating Notification Specifications".
Searches the database for an existing /config/notification_spec object with the same notification specification name. If one already exists, the opcode sends an error.
Calls the PCM_OP_NOTIFICATION_POL_PREP_SPECIFICATION policy opcode to prepare the input parameters. See "Preparing Notification Specifications".
Calls the PCM_OP_CREATE_OBJ opcode to create the /config/notification_spec object.

Modifying Notification Specifications

Use the PCM_OP_NOTIFICATION_MODIFY_SPECIFICATION opcode to modify attributes in a specified notification specification (/config/notification_spec object).

Note:

You can modify any field in the /config/notification_spec object except PIN_FLD_NAME and PIN_FLD_EVENT_NAME.

The PCM_OP_NOTIFICATION_MODIFY_SPECIFICATION opcode does the following:

Validates the mandatory parameters in the input flist.
Calls the PCM_OP_NOTIFICATION_POL_VALID_SPECIFICATION policy opcode to perform validations. See "Validating Notification Specifications".
Searches for the /config/notification_spec object that matches the specified POID.
Calls the PCM_OP_WRITE_FLDS opcode to update the /config/notification_spec object with the fields provided in the input flist.

Retrieving Notification Specifications

Use the PCM_OP_NOTIFICATION_GET_SPECIFICATION opcode to retrieve an existing notification specification (/config/notification_spec object).

If you pass in an object POID, notification specification name, status, event name, or delivery description in the input flist, the opcode returns the appropriate /config/notification_spec. Otherwise, the opcode returns all /config/notification_spec objects in the BRM database.

The PCM_OP_NOTIFICATION_GET_SPECIFICATION opcode does the following:

Validates the mandatory parameters in the input flist.
Calls the PCM_OP_NOTIFICATION_POL_GET_SPECIFICATION policy opcode to perform any customizations before retrieving the notification specification. See "Customizing Notification Retrieval".
Calls the PCM_OP_SEARCH opcode to find the /config/notification_spec objects and prepares the output flist.
Returns the POID of one or more /config/notification_spec objects in the PIN_FLD_RESULTS output flist array.

Managing In-Advance and Post-Expiration Notifications

Use the PCM_OP_NOTIFICATION_PROCESS_NOTIFICATION opcode to manage in-advance and post-expiration notifications. This opcode is called by the pin_gen_notifications utility.

PCM_OP_NOTIFICATION_PROCESS_NOTIFICATION is a wrapper opcode that calls other opcodes to create in-advance and post-expiration notifications. It does the following:

Calls the PCM_OP_NOTIFICATION_VERIFY_PUBLISH_REQUIRED opcode to verify that the business event should be published. See "Verifying Customer Opt-In Preferences".
Determines whether to send the notification now or schedule it for later. If the notification is scheduled for later, it creates a /schedule/notification object.
Calls the opcode specified in the PIN_FLD_OPCODE input flist field, which generates the notification event.

Note:

The field passes in the opcode number. To find an opcode's number, see the opcode header files in BRM_home/include/ops.

Calculating the Notification Delivery Time

Use the PCM_OP_NOTIFICATION_CALC_DELIVERY_TIME opcode to calculate the customer's message delivery time. This opcode is called by the pin_gen_notifications utility.

The PCM_OP_NOTIFICATION_CALC_DELIVERY_TIME opcode calculates the delivery time based on the preferred time, scheduled time, silent period, and silent day settings. See "About Message Delivery Times" in BRM Managing Customers for more information about these settings. If the delivery time is scheduled for the future, the opcode returns the PIN_FLD_WHEN_T output flist field set to the delivery timestamp.

Verifying Customer Opt-In Preferences

Use the PCM_OP_NOTIFICATION_VERIFY_PUBLISH_REQUIRED opcode to verify a customer's opt-in or opt-out preferences for receiving notification messages.

The PCM_OP_NOTIFICATION_VERIFY_PUBLISH_REQUIRED opcode does the following:

Checks the customer's opt-in and opt-out preferences by reading the PIN_FLD_NAME field set to the following in the customer's /profile/subscriber_preferences object: NotifyOptInList and NotifyOptOutList.

If the /profile/subscriber_preferences object does not include the fields, it checks the value of the PIN_FLD_NOTIFY_OPT_TYPE field in the /config/notification_spec object.
Returns the PIN_FLD_DELIVERY_STATUS output flist field set to one of the following:
- 1: Specifies to publish the business event to the Kafka server
- 0: Specifies not to publish the business event

Retrieving Last Notification Time and Offset

Use the PCM_OP_NOTIFICATION_GET_LASTNOTIFY_TSTAMP opcode to determine if an event's due date and time occur during the customer's message delivery window. This is a helper opcode that is called by internal opcodes before they create the actual notification event.

The PCM_OP_NOTIFICATION_GET_LASTNOTIFY_TSTAMP opcode returns the following fields in the PIN_FLD_DATES output flist array:

PIN_FLD_DUE_T set to the event's due date and time
PIN_FLD_STATUS set to one of the following:
- 0: Specifies that the due date timestamp does not occur during the delivery window
- 1: Specifies that the due date timestamp does occur during the delivery window

Customizing Notifications

You can customize notifications before they are sent to external applications by using the following opcodes:

PCM_OP_NOTIFICATION_POL_GET_SPECIFICATION. See "Customizing Notification Retrieval".
PCM_OP_NOTIFICATION_POL_PREP_SPECIFICATION. See "Preparing Notification Specifications".
PCM_OP_NOTIFICATION_POL_VALID_SPECIFICATION. See "Validating Notification Specifications".

Customizing Notification Retrieval

Use the PCM_OP_NOTIFICATION_POL_GET_SPECIFICATION policy opcode to validate and implement any customizations while retrieving notification specifications. This policy opcode is called by the PCM_OP_NOTIFICATION_GET_SPECIFICATION opcode.

By default, the PCM_OP_NOTIFICATION_POL_GET_SPECIFICATION opcode does the following, but you can customize it to do more:

Validates the mandatory parameters passed in the input flist.
Returns errors if any parameters are invalid.

Preparing Notification Specifications

Use the PCM_OP_NOTIFICATION_POL_PREP_SPECIFICATION policy opcode to prepare the fields for the notification specification and implement any customizations while creating the notification specifications. This opcode is called by the PCM_OP_NOTIFICATION_CREATE_SPECIFICATION opcode.

For more information about the PREP and VALID opcodes, see "About the PREP and VALID Opcodes" in BRM Developer’s Guide.

Validating Notification Specifications

Use the PCM_OP_NOTIFICATION_POL_VALID_SPECIFICATION policy opcode to validate and implement any customizations while creating notification specifications. This policy opcode is called by the PCM_OP_NOTIFICATION_CREATE_SPECIFICATION opcode.

The PCM_OP_NOTIFICATION_POL_VALID_SPECIFICATION policy opcode does the following:

Validates the mandatory parameters in the input flist.
Calls the PCM_OP_SEARCH opcode to search for duplicate notification specification names.
Validates that all fields are in the required format.
Does one of the following:
- If it encounters BRM system-related errors, sets the PIN_FLD_RESULT output flist field to FAIL, shares the designated error message, and clears the Error Buf to avoid any break in the flow.
- If it does not encounter errors, reviews other logical areas for failures and sets the PIN_FLD_RESULT output flist field to PASS.