Search

Can I use custom scripts with reports in our Oracle B2C Service application?

Environment:

Custom Scripts in Analytics

Resolution:

This content is applicable for Oracle B2C Service up through version 20C. For versions 20D and later, see Answer ID 11780: Custom Scripts Replacement by Analytics Extensions for best practices.

When creating custom reports in Oracle B2C Service, there are numerous features included to allow users the ability to customize and configure custom reports. Most users will be able to define and create reports using the features within the Oracle B2C Service application itself.

The custom scripts feature allows you to define a specific PHP script that is run when the report is generated. This allows you to further act on, manipulate, and format the data in your report -- even beyond the standard features available. For example, custom scripts can be used to convert a row of data into a table, remove unwanted data, or create a link to another page. Analytics custom script functionality is not intended, and should not be used for any other purpose, such as for running PHP scripts on a report schedule (instead of using a custom CRON configuration) or for making public API requests.

Custom scripts must be written in PHP. Therefore, you should not attempt to create or implement a custom script unless you are familiar with the PHP scripting language and programming concepts. For official documentation and information on PHP, refer to http://www.php.net/.

Note: Custom scripts only run while using the report from the Oracle B2C Service console. These same reports do not run the custom scripts while used from the Customer Portal Pages.

To add a custom script to a report:

1. Open the report you want to edit.
2. Select the output level you want to add the custom script to from the Level drop-down menu at the top of the report design center.
3. Click the Level tab.
4. Click the Custom Scripts button to open the Custom Script editor. If the output level already has a custom script, the editor displays the custom script for editing.

   

5. From the Initialization tab, type the script executed before the report is processed. This script is executed once when the report starts to process.
6. Click the Headers tab.
7. Type the script that runs during the start process. This script is called once while passing the column headings. The $headers parameter is an array that contains the column headers for the report. For example:

   Array
   (
   [0] => Account ID
   [1] => Full Name
   )

   You could manipulate this array by changing, adding, or removing column headers. The resulting array displays as column headers in the report.
    
8. Click the Process tab.
9. Type the script that runs while the report is generating. This script is called with each row passing the row data. The $rows parameter is a nested array, allowing you to return a "table" of data rather than just a row. Initially, the $rows parameter contains only data in the first row of the table ($rows[0][$i]). Each data cell contains a val variable that holds the value of the data cell. It can also contain a URL variable that contains a link for the data cell. For example:

   $rows[0][0]->val = $rows[0][0]->val + 22;
   $rows[0][1]->val = 'Link';
   $rows[0][1]->url = 'http://vendorurl.com/';

   This code requires that the first column in the report is an integer type, and that the second column is a string type. The URL variable can be assigned to a cell of any data type, but the val variable must be assigned a value that matches the cell data type.
    
10. Click the Finish tab.
11. Type the script that runs during the exit process. This script is called after the rows have been processed. The Finish script returns the $exit_obj variable, which is added to the report after each row of the Process script.
12. Click the OK button to apply your custom script to your output level.
13. To remove a custom script, click the Level tab, click the Edit button, and click Remove. Click Yes at the removal confirmation.
14. Click the arrow on the Save button on the Quick Access toolbar and select a save option.

For an example of custom script code, refer to standard report "Visit Activity" (report ID 46). To view the custom script right-click on the report from the Reports Explorer and select "View Definition". The custom script code is located at the bottom of the report definition.

For additional information, refer to the 'Create a custom script' section in the Online Help User Guide documentation. To access Oracle B2C Service manuals and documentation online, refer to the Documentation for Oracle B2C Service Products.

Troubleshooting custom scripts requires the involvement of Oracle Consulting. Associated fees for troubleshooting custom scripts must be coordinated through your Sales Account Manager.

Notes:

-- The CUSTOM_SCRIPT_DATA_SIZE configuration setting limits the size of the data buffer. If many null value rows are seen, this value may need to be increased. Further, increasing the value of this configuration can eliminate errors observed when running reports. These errors, when encountered in the agent console on running reports, can show up as follows:

"Unable to Communicate with Server"
"Unexpected end of file has occurred"
"The 'exec_rv' start tag on line 7 position 8 does not match the end tag of 'php_header'. Line 10, position 16."

-- You can define PHP functions in the Initialization tab that may then be called from any of the other tabs.

-- You may remove any given row by unsetting it in the Process tab (unset($rows[0])).

-- The $rows[0] variable is a little misleading, as it is plural, but only contains a singular row being processed.