Skip Navigation
Expand
Using custom scripts with reports
Answer ID 2284   |   Last Review Date 04/12/2019

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

Environment:

Custom Scripts in Analytics

Resolution:

When creating custom reports in Oracle Service Cloud, 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 Service Cloud 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 Service Cloud 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.
    Click the Custom Scripts button to open the Custom Script editor.
  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 online documentation for the version your site is currently running. To access Oracle Service Cloud manuals and documentation online, refer to the Documentation for Oracle Service Cloud 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.

Available Languages for this Answer:

Notify Me
The page will refresh upon submission. Any pending input will be lost.