Recording Billing Care REST API Request Failures

About Recording Billing Care REST API Request Failures

Billing Care REST API requests may occasionally fail to process completely. For example, a payment request could fail due to an incorrect account address or because a network connection dropped. You can configure the Billing Care REST API to store information about failed REST requests in the BRM database, so you can view them for analysis and reporting, or reprocess them at a later time.

When a Billing Care REST API request fails, BRM stores the following details about the failure in /request/failed/rest objects:

The request's basic header information, such as Content-Type, Accept, and Content-Length
The request payload, removing any sensitive information such as card numbers and expiration dates

In multischema systems, the object is stored in the schema in which the failed request occurred. For more information about the /request/failed/rest object, see Storable Class Reference.

To enable the Billing Care REST API to record request failures, see "Enabling the Recording of REST Request Failures".

To customize the details recorded for a REST request failure, see "Customizing REST Request Failure Details".

Enabling the Recording of REST Request Failures

To enable the Billing Care REST API to record details about REST request failures:

If your system does not have a CustomConfigurations.xml file, create the file. See "Creating a Custom Configuration File".
Open the CustomConfigurations.xml file in an editor.

Note:

By default, the CustomConfigurations.xml file is in the myproject/src/java/custom/configurations directory, where myproject is your NetBeans IDE Billing Care customizations project.

In the file, set the request.record.failure key to true:

<flags>        
   <key>request.record.failure</key>        
   <value>true</value>
</flags>

Save and close your CustomConfigurations.xml file.
Save the file in your NetBeans IDE project.

Customizing REST Request Failure Details

You can customize the Billing Care REST API to perform additional tasks when recording request failures, such as:

Storing additional headers from the failed request
Removing additional sensitive data from the request payload
Changing how the request payload is serialized for storage in the /request/failed/rest object
Overriding fields in the /request/failed/rest object
Specifying to record request failures for only specified Billing Care REST API endpoints

To customize the details recorded for a REST request failure:

Customize the logic for recording request failures. See "Customizing the Request Record Logic".
Customize which headers to record and the information to remove from request payloads. See "Customizing the Headers and Payload to Record".
Configure the Billing Care REST API to use your custom logic for recording request failures. See "Overriding the Default Request Record Logic".

The Billing Care SDK includes sample Record Request customizations, including a README.txt file explaining the samples, in the SDK_home/samples/RecordRequestsCustomization directory, where SDK_home is the directory in which you installed the Billing Care SDK. Use these samples when developing your own Record Request customizations.

Customizing the Request Record Logic

To customize the logic for recording request failures:

Create a CustomPCMRequestInfoModule.java file in your myproject/src/java/com/oracle/communications/brm/sdk directory, where myproject is the folder containing your NetBeans IDE project.

Note:

A sample CustomPCMRequestInfoModule.java file is provided in the SDK_home/samples/RecordRequestsCustomization/src/java/com/oracle/communications/brm/sdk directory.

In the file, implement your custom logic by overriding the recordFailure( ) method.

The sample logic below calls the custom method from customRecordFailureWorker to do the following:

Record additional headers
Remove additional information from the request payload
Create an input flist for the PCM_OP_ACT_REQUEST_OPCODE opcode
Call the PCM_OP_ACT_REQUEST_OPCODE opcode to record the failed request in a /request/failed/rest object

@override
public void recordFailure(String id, String descr, String correlationId, String errorCode, Exception ex, Object payload) throws EBufException {
    if(!BRMUtility.getRecordFailureFlag()){            
        return;         
    }        
    PortalContext ctx = null;        
    BaseOps baseops = getBaseOps();        
    try {            
        if (baseOps instanceof PCMBaseOps) {                
            logger.fine("Setting BRM Connection Object to BaseOps");                
            ctx = BRMUtility.getConnection();                
            ((PCMBaseOps) baseOps).setContext(ctx);           
        }            
        HttpServletRequest request = getUserContext().getRequest();            
        CustomRequestInfoWorker customRecordFailureWorker = new CustomRequestInfoWorker();            
        customRecordFailureWorker.setBaseOps(baseops);            
        customRecordFailureWorker.setUserContext(getUserContext());            
        Map<String, String> headerInfoMap = new HashMap<>();            
        customRecordFailureWorker.addHeaders(request, headerInfoMap);            
        int partial = customRecordFailureWorker.truncateSensitiveInfo(payload);            
        String payloadStr = customRecordFailureWorker.preparePayload(payload, request);            
        FList inputFList = customRecordFailureWorker.convertToInputFListForRecordFailure(id, correlationId, partial, errorCode, ex, headerInfoMap, payloadStr, request, descr);            
        customRecordFailureWorker.invokeRequestCreate(inputFList);        
    } catch (EBufException excp) {             
        throw excp;        
    } finally {            
        if (ctx != null) {                
            BRMUtility.releaseConnection(ctx);            
        }        
    }
}

Save the file in your NetBeans IDE project.

Customizing the Headers and Payload to Record

You can customize the Billing Care REST API to record additional headers or to remove additional information from the request payload. To do so, perform the following:

Copy the sample CustomRequestInfoWorker.java file from the SDK_home/samples/RecordRequestsCustomization/src/java/com/oracle/communications/brm/sdk directory to your myproject/src/java/com/oracle/communications/brm/sdk directory.

To add custom headers to the operation failure record, override the addHeaders( ) method. For example:

@Override    
public void addHeaders(HttpServletRequest request, Map<String, String> headerInfoMap) {        
   super.addHeaders(request, headerInfoMap);        
   //Your custom logic here        
   logger.fine("Adding custom headers");    
}

To modify what information is removed from the request payload, override the truncateSensitiveInfo( ) method. This method must return isPayloadPartial when sensitive information is removed from the payload. For example:

@Override    
public int truncateSensitiveInfo(Object payloadObj) {        
   int isPayloadPartial = super.truncateSensitiveInfo(payloadObj);        
   logger.fine("Truncating sensitive information from payload");        
   //Your Custom Logic here        
   return isPayloadPartial;    
}

Save the file in your NetBeans IDE project.

Overriding the Default Request Record Logic

You configure the Billing Care REST API to use the logic from your custom request module rather than the default request module by editing the customModule.properties file.

To override the default Billing Care REST API request record logic:

Open the customModule.properties file from the myproject/src/java/custom directory.

Add the following entry to the file:

billingcare.rest.requestinfo.module=com.oracle.communications.brm.sdk.CustomPCMRequestInfoModule

Save and close the customModule.properties file.
Save the file in your NetBeans IDE project.
Package and deploy your Billing Care SDK. See "Packaging and Deploying Customizations".