About Suspense Manager Opcodes

Recycling Suspended EDRs

PCM_OP_SUSPENSE_SEARCH_RECYCLE searches for and queues suspended call records for recycling. There are many search criteria that you may use to search the records, such as by CDR file or by recycle key.

This opcode is usually called by the pin_recycle utility, which searches for and deletes call records with a specific recycle key and a status of Succeeded (or Written-off).

Searching for EDRs in a CDR File

The BRM standard recycling feature collects and manipulates all calls contained in a CDR file at the same time. PCM_OP_SUSPENSE_SEARCH_RECYCLE searches for a specified CDR file and queues its suspended EDRs for recycling. If successful, the EDRs are assigned a status of Succeeded.

Searching for EDRs with a Recycle Key

PCM_OP_SUSPENSE_SEARCH_RECYCLE is used by features that need to temporarily delay rating of EDRs. These features include pipeline modules to add a recycle key and error to those EDRs during pipeline rating. This opcode searches for all Suspended call records containing the recycle key passed in on the input flist. It then queues those call records to be rated at the next opportunity. If successful, the EDRs are assigned a status of Succeeded.

Initiating Suspense Recycling

PCM_OP_SUSPENSE_RECYCLE_USAGE initiates EDR recycling. During recycling, suspended EDRs are sent back through their original rating pipelines. The Suspense Management Center calls this opcode when the user chooses to recycle suspended EDRs.

PCM_OP_SUSPENSE_RECYCLE_USAGE can operate in test mode. In test mode, the EDR is sent through the rating pipeline normally. The rating results, however, are not output from the pipeline if the EDR is processed successfully. In test mode, the pipeline does not make any state changes, such as updating aggregation counters in discounting.

PCM_OP_SUSPENSE_RECYCLE_USAGE takes as input an array of /suspended_usage object POIDs, a list of suspense override reasons, and a value that indicates whether the EDRs should be recycled in test mode. This opcode then creates an /admin_action/suspended_usage/recycle object with that information.

For each /suspended_usage object specified in the input flist, PCM_OP_SUSPENSE_RECYCLE_USAGE performs these operations:

Confirms that the suspended EDR has a status of Suspended. The PIN_FLD_STATUS value in the object must be 0.
Changes the EDR status to Recycling. The value of the PIN_FLD_STATUS field in the /suspended_usage object is set to 1.
Creates an /admin_action/suspended_usage/recycle object containing the recycle mode and override reasons (passed in the input flist).
Adds the POID of the newly created /admin_action/suspended_usage/recycle object to the actions array of each /suspended_usage object.
Sets the PIN_FLD_RECYCLE_OBJ field of each /suspended_usage object to the /admin_action/suspended_usage/recycle object POID. Pipeline Manager uses this field to find all EDRs associated with a recycle request.
Creates a notification event that triggers the Account Synchronization Data Manager (dm_ifw_sync) to send a message to the DAT_Listener module. This initiates the process of recycling the EDR through the rating pipeline.

After EDRs are recycled, their /suspended_usage objects are updated by using the Suspended Event (SE) Loader:

If an EDR is successfully recycled, the status is changed to Succeeded, and the PIN_FLD_STATUS value is changed to 2.
If an EDR is not successfully recycled, the status is changed back to Suspended, and the PIN_FLD_STATUS value is changed to 0. In addition, the following fields are updated because their original values could have changed:
- The suspense reason code, PIN_FLD_SUSPENSE_REASON.
- The suspense subreason code, PIN_FLD_SUSPENSE_SUBREASON.
- The Pipeline Manager error code, PIN_FLD_PIPELINE_ERROR_CODE.
If PCM_OP_SUSPENSE_RECYCLE_USAGE was run in test mode, the status is changed back to Suspended, and the PIN_FLD_STATUS value is changed to 0. The suspense reason Pipeline Manager error code are not updated, but the corresponding test values (PIN_FLD_TEST_SUSPENSE_REASON, PIN_FLD_TEST_SUSPENSE_SUBREASON, and PIN_FLD_TEST_SUSPENSE_ERROR_CODE) are updated to include information about the results of the test recycling.
The number of times the record has been recycled (in PIN_FLD_NUM_RECYCLES) is increased by 1.

PCM_OP_SUSPENSE_RECYCLE_USAGE returns the routing POID specified in the input flist.

Resubmitting Suspended Batches

PCM_OP_BATCH_SUSPENSE_RESUBMIT_BATCHES resubmits suspended CDR file. When resubmitted, suspended CDR file are sent back through their original pipeline. Suspense Management Center calls this opcode when the user chooses to resubmit suspended batches.

PCM_OP_BATCH_SUSPENSE_RESUBMIT_BATCHES takes an array of /suspended_batch object POIDs and a list of suspense override reasons as input. This opcode then creates an /admin_action/suspended_batch/resubmit object with that information.

For the whole set of /suspended_batch objects specified in the input flist, PCM_OP_BATCH_SUSPENSE_RESUBMIT_BATCHES performs these operations:

Creates a transaction if it is not already opened.
Creates an ADMIN_ACTION object, /admin_action/suspended_batch/resubmit, with the override reason, for each /suspended_batch object.
Validates the status of each /suspended_batch object (Batch Suspense Record) and updates the status with the result of the resubmission.
Creates an event Flist (with /event/notification/suspense/batch_resubmit) and calls PCM_OP_ACT_USAGE in CALC_ONLY mode.
Closes the transaction

After CDR file are resubmitted, their /suspended_batch objects (Batch Suspense Records) are updated by using the SE Loader:

The PIN_FLD_NUM_RESUBMISSIONS field in each /suspended_batch object is incriminated.
If a batch is successfully resubmitted, the status is changed to Succeeded, and the PIN_FLD_STATUS value is changed to 2.
If a batch is not recycled successfully, the status is changed back to Suspended, and the PIN_FLD_STATUS value is changed to 0. This will cause all the batches in the resubmission task to be rolled back as well. In addition, these fields are updated because their original values could have changed:
- The suspense reason code, PIN_FLD_BATCH_SUSPENSE_REASON.
- The suspense sub-reason code, PIN_FLD_BATCH_SUSPENSE_SUBREASON.
- The Pipeline Manager error code, PIN_FLD_PIPELINE_ERROR_CODE.

PCM_OP_BATCH_SUSPENSE_RESUBMIT_BATCHES returns the routing POID specified in the input flist.

Changing the Contents of Fields in Suspended EDRs

Use PCM_OP_SUSPENSE_EDIT_USAGE to change the contents of fields in suspended EDRs. Suspense Management Center calls this opcode to edit a suspended call record.

Note:

This opcode is available to Suspense Manager customers only.

Note:

You cannot edit the CDR or EDR fields of records in a CDR file that has been suspended by batch suspense and has a Batch Suspense Record.

PCM_OP_SUSPENSE_EDIT_USAGE performs these operations:

Takes as input an array of /suspended_usage object POIDs and an array of the EDR fields to be edited, including the old and new values.
For each EDR field to be edited, this opcode:
- Creates an /admin_action/suspended_usage/edit object, which includes both the old and new values.
- Adds the /admin_action/suspended_usage/edit object POID to the top of the /suspended_usage_edits object stack. If the stack is full, it removes the oldest POID.
For each /suspended_usage object, this opcode:
- Confirms that the suspended EDR has a status of Suspended. The PIN_FLD_STATUS value in the object must be 0.
- Adds the /admin_action/suspended_usage/edit object POID and the old value to each /suspended_usage object's action array.
- Updates the modified flag (PIN_FLD_EDITED), which indicates that the field has been edited.

PCM_OP_SUSPENSE_EDIT_USAGE returns an array of the POID of the /admin_action/suspended_usage/edit objects it creates.

Undoing Edits to Suspended EDRs

Use the PCM_OP_SUSPENSE_UNDO_EDIT_USAGE opcode to undo edits to suspended EDRs.

This opcode is called by Suspense Management Center to the undo edits. It replaces the value of a field in a suspended call record with the value in that field before the last edit was made.

Note:

This opcode is available to Suspense Manager customers only.

PCM_OP_SUSPENSE_UNDO_EDIT_USAGE performs these operations:

Confirms that the POID of the /admin_action/suspended_usage/edit object on the input flist matches that of the top POID of the /suspended_usage_edits object stack. If the two don't match, returns failure status (PIN_FLD_RESULT is set to 1) and returns the POID at the top of the /suspended_usage_edits object stack.
Confirms that each suspended call record affected by the edit has a status of Suspended.
Undoes the edit by replacing the existing field values with the values before the last edit was saved (the values referenced by the POID at the top of the /suspended_usage_edits object stack).
Adds the session, service, and date and time details of the undo edit operation in the PIN_FLD_UNDO_DATA array of the /admin_action/suspended_usage/edit object.
Removes the POID of the /admin_action/suspended_usage/edit object from the top of the /suspended_usage_edits object stack.

PCM_OP_SUSPENSE_UNDO_EDIT_USAGE returns a PIN_FLD_RESULT value of:

0 if the undo edit was successful. Also:
- The PIN_FLD_POID field contains the POID of the /admin_action/suspended_usage/edit object.
- The PIN_FLD_COUNT field contains the number of records that were processed.
1 if the /admin_action/suspended_usage/edit POID in the input flist does not match the POID at the top of the /suspended_usage_edits object stack.

Deleting Records for Suspended EDRs

Use PCM_OP_SUSPENSE_DELETE_USAGE to delete records for suspended EDRs.

Note:

This opcode is available to Suspense Manager customers only.

The Suspense Management Center calls this opcode to delete EDRs. EDRs can be deleted only if their status is Written-off or Succeeded.

PCM_OP_SUSPENSE_DELETE_USAGE takes as input an array of /suspended_usage object POIDs to be deleted.

For each /suspended_usage object specified in the input flist, PCM_OP_SUSPENSE_DELETE_USAGE performs these operations:

Confirms that the suspended EDR has a status of Succeeded or Written off. The value of the PIN_FLD_STATUS field in the /suspended_usage object must be 2 or 3.
Deletes the /suspended_usage object.
Generates a /event/notification/suspense/delete object that records the deletion.

PCM_OP_SUSPENSE_DELETE_USAGE returns the routing POID specified in the input flist.

Deleting Records for Suspended Batches

Use PCM_OP_BATCH_SUSPENSE_DELETE_BATCHES to delete /suspended_batch objects (Batch Suspense Records).

Note:

This opcode deletes records, not the files associated with them.

Suspense Management Center calls this opcode to delete Batch Suspense Records (/suspended_batch objects). Batch Suspense Records can be deleted only if their status is Written-off or Succeeded.

PCM_OP_BATCH_SUSPENSE_DELETE_BATCHES takes as input an array of /suspended_batch object POIDs to be deleted.

For each /suspended_batch object specified in the input flist, PCM_OP_BATCH_SUSPENSE_DELETE_BATCHES performs these operations:

Creates a transaction if it is not already opened.
Confirms that the suspended batch file has a status of Succeeded or Written-off. The value of the PIN_FLD_STATUS field in the /suspended_batch object must be 2 or 3. Otherwise, an error code is generated and the transaction ends.
Deletes the /suspended_batch object.
Generates an /event/notification/suspense/batch_delete event.
Closes the transaction.

PCM_OP_BATCH_SUSPENSE_DELETE_BATCHES returns the routing POID specified in the input flist.

Deleting Call Records with a Specific Recycle Key and a Status of Succeeded or Written-Off

Use PCM_OP_SUSPENSE_SEARCH_DELETE to delete call records with a specific recycle key and a status of Succeeded or Written-off.

Set the PIN_FLD_FLAGS field to either of these values:

0: Directs this opcode to delete EDRs with a status of:
- Succeeded (successfully processed)
- Written-off
1: Directs this opcode to delete EDRs with a status of:
- Succeeded (successfully processed)
- Written-off
- Suspended. This opcode first writes off, then deletes, these EDRs

Deleting EDRs in a CDR File

PCM_OP_SUSPENSE_SEARCH_DELETE is used with the BRM standard recycling feature, which acts on all the calls contained in a single CDR file simultaneously. Using pin_recycle with the -d parameter deletes all calls in a CDR file that have a status of Succeeded. Using pin_recycle with the -D parameter deletes all calls in a CDR file with a status of Succeeded or Written off.

Deleting Calls with a Recycle Key

PCM_OP_SUSPENSE_SEARCH_DELETE is also used by features that need to temporarily delay rating of EDRs. These features include pipeline modules to add a recycle key and error to those EDRs during pipeline rating. The error prevents EDRs from being rated by assigning them a status of Suspended. Those features then use PCM_OP_SUSPENSE_EDIT_USAGE to find and recycle the call records. If successful, the EDRs are assigned a status of Succeeded. This opcode then deletes those successfully recycled call records.

Writing Off Suspended EDRs

Use PCM_OP_SUSPENSE_WRITTEN_OFF_USAGE to write off suspended EDRs.

When a suspended EDR is written off, it can no longer be edited or recycled.

Note:

This opcode is available to Suspense Manager customers only.

PCM_OP_SUSPENSE_WRITTEN_OFF_USAGE takes as input an array of /suspended_usage object POIDs.

PCM_OP_SUSPENSE_WRITTEN_OFF_USAGE creates an /admin_action/suspended_usage/writeoff object that records the write-off.

For each /suspended_usage object specified in the input flist, PCM_OP_SUSPENSE_WRITTEN_OFF_USAGE performs these operations:

Confirms that the suspended EDR has a status of Suspended; the PIN_FLD_STATUS value must be 0.
Adds the POID of the newly created /admin_action/suspended_usage/writeoff object to the array of actions in the /suspended_usage object.
Changes the status to Written-off. The value of the PIN_FLD_STATUS field in the /suspended_usage object is changed to 3.
Generates an /event/notification/suspense/batch_writeoff event.

PCM_OP_SUSPENSE_WRITTEN_OFF_USAGE returns the POID of the /admin_action/suspended_usage/writeoff object created.

Writing Off Suspended Batches

Use PCM_OP_BATCH_SUSPENSE_WRITE_OFF_BATCHES to write off suspended CDR files.

When you write off a suspended CDR file, you can no longer resubmit it, but you can delete it.

The opcode creates an /admin_action/suspended_batch/writeoff object that records the write-off and sets the status of the Batch Suspense Record (/suspended_batch) to Written-off.

PCM_OP_BATCH_SUSPENSE_WRITE_OFF_BATCHES performs these operations:

Create a transaction if it is not already opened.
Confirms that the suspended EDR has a status of Suspended; the PIN_FLD_STATUS value must be 0.
PCM_OP_BATCH_SUSPENSE_WRITE_OFF_BATCHES takes as input an array of /suspended_batch object POIDs.
Adds the POID of the newly created /admin_action/suspended_batch/writeoff object to the array of actions in the /suspended_batch object.
Changes the status of the Batch Suspense Record (/suspended_batch) to Written off; The value of the PIN_FLD_STATUS field in /suspended_batch is changed to 3.
Generates an /event/notification/suspense/batch_writeoff event.
Closes the transaction.

PCM_OP_BATCH_SUSPENSE_WRITE_OFF_BATCHES returns the POID of the /admin_action/suspended_batch/writeoff object created.

Processing Suspended Records in Bulk

You can use the Suspense Manager opcodes to edit, delete, recycle, and write off a large number of suspended records. For more information, see:

Processing Suspended Records in Multiple Steps

You can process the suspended records in multiple steps by calling the opcodes multiple times, to avoid a large database transaction:

Specify the number of records to process in each opcode call in a configuration file and load the file into the /config/pin_suspense_system_params storable class.

For more information, see "Configuring the Number of Suspended Records to Process in a Transaction".
Call the opcode in calc-only mode to retrieve the count and POID range of the records that match your search criteria.
Use a simple logic to determine the number of times to call the opcodes depending on the number of records you want each opcode call to process.
Call the opcode several times with a set of records each time and consolidate the results returned by each opcode call.

Note:

For each opcode call, you must provide the POID range and the corresponding arguments in the input flist.

Because each operation is performed in multiple steps, if the operation is successful in any of the steps, you get the number of records processed. You also get an error message for the unsuccessful records, which you can display to the user. If any one of the steps fails, the entire step and the following steps are canceled and an error message is returned.

Note:

Suspense Management Center and the pin_recycle utility perform suspense management operations in multiple steps by calling the opcodes multiple times.

Editing Suspended Records in Bulk

Use the PCM_OP_SUSPENSE_SEARCH_EDIT opcode to perform the same set of edits on a large number of suspended records that meet the criteria you specify.

This opcode makes changes to the records in one database operation instead of accessing the database for each record. It calls the following opcodes:

PCM_OP_BULK_WRITE_FLDS, to update the objects in the database.
PCM_OP_ACT_USAGE, to generate the edit event notification.

Note:

You cannot undo edits performed on a large number of records or any edits made before the bulk edit operation.

PCM_OP_SUSPENSE_SEARCH_EDIT follows these steps to edit suspended records:

Takes as input the following information:
- The POID type of the suspended usage class.
- The search criteria template.
- The fields and values that need to be edited in the object.
- An array of the EDR fields to be edited, including the old and new values.
Does one of the following:
1. If the PCM_OPFLG_CALC_ONLY flag is set, returns the count and the POID range of records that meet the search criteria.
2. If the PCM_OPFLG_CALC_ONLY flag is not set, searches for the /suspended_usage_edits objects that correspond to the account, which is determined by the login session.
Does one of the following:
1. If it finds /suspended_usage_edits objects for the specified account, clears all the POIDs of the edit actions stored in the objects.
  
  Note:
  
  After the objects are changed, the current changes or previous changes cannot be undone.
2. If it does not find a /suspended_usage_edits object for the appropriate account, creates a new /suspended_usage_edits object.
For each EDR field to be edited, creates an /admin_action/suspended_usage/edit object, which includes both the old and new values.
For each /suspended_usage object, performs the following operations:
- Verifies that the suspended EDR has a status of Suspended. The PIN_FLD_STATUS value in the object must be 0.
- Adds the /admin_action/suspended_usage/edit object POID and the old value to each /suspended_usage object's action array.
- Updates the PIN_FLD_EDITED field to indicate that the field has been edited.

If successful, PCM_OP_SUSPENSE_SEARCH_EDIT generates an edit notification event that includes the administrative action POID of the edit action and returns success along with the count of the objects edited. If the operation fails in any record, it cancels the entire operation and returns failure with the appropriate error code, leaving the state of the record as it was before the operation.

Writing Off Suspended Records in Bulk

Use the PCM_OP_SUSPENSE_SEARCH_WRITE_OFF opcode to write off all suspended records that meet the criteria you define.

Note:

You cannot edit or recycle suspended records that are written off.

This opcode writes off a large set of suspended records in one database operation instead of accessing the database for each record. It calls the following opcodes:

PCM_OP_BULK_WRITE_FLDS to mark a large number of objects in the database as written off.
PCM_OP_ACT_USAGE to generate the write-off event notification.

PCM_OP_SUSPENSE_SEARCH_WRITE_OFF follows these steps to write off suspended records:

Takes as input the POID type of the suspended usage class and the search criteria template for the objects to be written off.
If the PCM_OPFLG_CALC_ONLY opcode flag is set, returns the count of records that match the search criteria and the POID range of the records that satisfy the criteria.
If the PCM_OPFLG_CALC_ONLY flag is not set, creates the /event/notification/suspense/batch_writeoff object that records the write off and returns that object with the count of records written off.
For each /suspended_usage object that meets the criteria specified in the template, performs these operations:
- Verifies that the suspended EDR has a status of Suspended. The PIN_FLD_STATUS value in the object must be 0.
- Adds the POID of the newly created /admin_action/suspended_usage/writeoff object to the array of actions in the /suspended_usage object.
- Changes the status to Written-off. The value of the PIN_FLD_STATUS field in the /suspended_usage object is changed to 3.

If successful, PCM_OP_SUSPENSE_SEARCH_WRITE_OFF generates a write-off notification event that includes the administrative action POID of the write-off action and returns success along with the number of records written off. If the operation fails in any record, it cancels the entire operation and returns failure with the appropriate error code, leaving the state of the record as it was before the operation.

Deleting Suspended Records in Bulk

Use the PCM_OP_SUSPENSE_SEARCH_DELETE opcode to delete all suspended records that meet the criteria you define.

Note:

You can only delete records that are succeeded or written off.

This opcode deletes a large set of suspended records in one database operation instead of accessing the database for each record. It calls PCM_OP_ACT_USAGE to generate the delete event notification.

PCM_OP_SUSPENSE_SEARCH_DELETE follows these steps to delete suspended records:

Takes as input the POID type of the suspended usage class and the search criteria template for the objects to be deleted.
If the PCM_OPFLG_CALC_ONLY opcode flag is set, returns the count of records that match the search criteria and the POID range of the records that satisfy the criteria.

If the PCM_OPFLG_CALC_ONLY flag is not set, creates the /event/notification/suspense/batch_delete object that records the deletion.
For each /suspended_usage object that meets the criteria specified in the template, performs these operations:
- Verifies that the suspended EDR has a status of Succeeded or Written off. The PIN_FLD_STATUS value in the object must be 2 or 3.
- EDRs with a status of Succeeded and those with a status of Written off that do not have a deferred duration are deleted immediately.
- If the status of the suspended record is Written off, the opcode checks if there is a deferred duration and if the deferred duration is greater than 0. The deferred duration is a parameter defined in the /config/suspense_params object.
  
  Note:
  
  The load utility is provided to load the deferred duration parameter.
  
  If there is a deferred duration, then the PCM_OP_SUSPENSE_SEARCH_DELETE opcode will not remove the suspended record from the database but rather change the status of the suspended records from written off to delete pending. The PCM_OP_SUSPENSE_SEARCH_DELETE opcode will create a schedule object to run the PCM_OP_SUSPENSE_DEFERRED_DELETE opcode.
- The schedule object will call the PCM_OP_SUSPENSE_DEFERRED_DELETE opcode to be run at the deferred duration time.
- The PCM_OP_SUSPENSE_SEARCH_DELETE or PCM_OP_SUSPENSE_DEFERRED_DELETE opcode deletes the object from the suspense db.
Generates a /event/notification/suspense/delete object that records the deletion for each suspended record that was deleted.

If successful, PCM_OP_SUSPENSE_SEARCH_DELETE generates a delete notification event that includes the administrative action POID of the delete action and returns success along with the number of records deleted. If the operation fails in any record, it cancels the entire operation and returns failure with the appropriate error code, leaving the state of the record as it was before the operation.