1. Understanding Scheduled Processes
  2. Schedule Custom Groovy Object Functions

Schedule Custom Groovy Object Functions

Use the Schedule Custom Groovy Object Functions scheduled process to make an asynchronous call to an external web service using an object function at a scheduled time. You can optionally define object functions to return values.

You can also specify typed parameters, which the caller will be required to provide values for, when the function is invoked. The supported return types and optional parameter types are the same as for global functions. However, scheduled processes only support object functions that have no parameters and that have String as the return type, if the function is defined to return values. So, if you're defining an object function to be used in a scheduled process, ensure that it has no parameters defined, and if you're defining the function to return a value, ensure that its return type is String.

Tip: Before you begin scheduling the object function, it's recommended that you perform the following steps:

  • Record the API name of the object as the object name.

  • Record the object function name.

  • Ensure that the object function compiles and runs properly using validation or trigger invocation mechanism within Application Composer, where runtime message debugging is supported.

Test capacity runs to determine the best batch size to handle large data set. You can use scheduled processes in several scenarios. Here are a few examples of when you may need to schedule processes:

  • To perform mass update of records based on certain criteria.

  • To trigger workflows based on criteria that will be met in the future, as a workaround for time-based workflows.

To run custom logic with heavy updates that can be scheduled during off-hours.

A few things to note:

  • You can write a function as complex as needed.

  • You can write a function to return values in a .txt file.

    The .txt file displays any values that the Groovy code returns. To view the .txt file of a process, click the status link for that process.

  • Each scheduled process has a runtime limit of 30 minutes to run an object function. This is to prevent long-running jobs that can consume large amounts of resources to support object functions operating on large volumes of data.
    Note: If your Groovy script triggers a long-running process that's implemented via ESS/PLSQL, any Groovy triggers already created on the target object won't get called. This is because ESS/PLSQL operates directly at the database level, bypassing ADF and the model layer.

  • Each job run constitutes a transaction. This means that all the operations specified by the Groovy script in the object function have to run to completion to complete the transaction. Otherwise, the transaction is rolled back and no records are updated.

  • Once the job execution starts, the Cancel button won't work and you can't cancel the job.

  • If a record is updated, the Last Updated By value changes to the user who submitted the job, and the Last Updated Date value changes to the date and time of the update.

  • The log file displays any errors occurred during the process. To view the log file of a process, click the status link for that process.

Privileges Required

Verify that you have the following roles:

  • Customer Relationship Management Application Administrator

  • Application Implementation Consultant

  • Master Data Management Application Administrator

  • ZCX_MANAGE_EXTENSIBLE_OBJECT_PRIV

Before You Start

Review the following before scheduling this scheduled process:

Recommended Frequency:

  • Call the web service using an object function at a scheduled time using the Scheduled Processes tool. You can process a set of records on a daily or weekly basis, asynchronously, when users don't need to see immediate feedback in the user interface.

  • Schedule business logic code and update a set of records periodically, on a daily, weekly, or monthly basis, asynchronously, by just specifying the object's name and its function.

Execution Time:

  • Each scheduled process has a runtime limit of 30 minutes to run an object function. This is to prevent long-running jobs that can consume large amounts of resources to support object functions operating on large volumes of data.

    Note: The 30 minute limit only applies to validation and execution of the object function operations specified for that run. As long as the required database transaction handling has begun within the allocated 30 minutes, the completion of the scheduled process can span past the 30 minute limit. This enables database inserts and updates of large data sets that often take a long time to complete their operation. Hence, the end-to-end processing time can be longer than 30 minutes.If your Groovy script triggers a long-running process that's implemented using scheduled jobs PLSQL, any Groovy triggers already created on the target object won't get called. This is because scheduled jobs PLSQL operates directly at the database level, bypassing ADF and the model layer.

  • Due to the 30 minute limit on the object function execution, it's best to break up the work done in each object function execution. This can be best done by testing a series of capacity runs in a test environment. Using the same object function, each job execution can work off a subset of the total data to be processed. By scheduling the same job to run at regular time intervals, the full set of data can be processed over multiple job runs.

The tests can be done in the following number of steps:

  1. Determine how much data can be processed in a 30 minute time interval.

    The size of data to be processed in each run is controlled by the Groovy script in the object function. You can control the following factors using Groovy script changes in your object function:

    • View criteria definition

    • Data filter defined on the result set returned from the view criteria definition

      Note: Database enhancements can be used to improve search effectiveness on view criteria and data filter results. For example, defining additional indexes on database columns search can return results much faster than a full table scan.

    • Maximum fetch size specified by setMaxFetch, which normally defaults to 500 rows if not defined

      If the data size chosen causes the job to fail with ExprTimeoutException, reduce the data size using setMaxFetch.

      The amount of data that can be processed within a 30 minute limit's dependent on the complexity of the data, type of operation on that data, and the resultant database update operation complexity, all of which are subjected to traffic and resource contentions. Data complexity is a reflection of the attributes making up the object to be operated on, and the parent, child, and associated object structures that need to be traversed or updated to complete the operation. The more complex the data, the more costly it's to collect and manipulate the information needed to complete the operation.

      For example, a simple custom object with very few attributes and no related parent, child, associated objects incurs the least cost whereas an out-of-the-box standard object such as Opportunity, with large number of attributes and multiple child and associated object relationships (such as account, contact, and lead) incurs a higher search and update cost. In terms of type of operations, insert operations incur the highest cost, followed by updates, followed by reads, with the cost increasing as amount of data processed increases. For update operations, the amount of data that can be processed depends on the cost of search operation and cost of updates, with the former dictated by the view criteria and latter by the operations performed on the result set obtained from the search, as specified by the Groovy script in the object function. Database update operation is dependent on the type of operation specified in the object function. Reads don't incur any database update cost whereas insert and update operations do, increasing with the data complexity.

  2. Determine how long each job takes to complete. Besides data size, the type of database operations needed to support the object function can greatly affect the completion of the job. Database data creation, updates, and deletes (when permitted by business rules) normally take a longer time to complete than data reads. The amount of time needed to complete database updates and creates transactions can far exceed that of the object function execution time. This cost is particularly high for cases where object data complexity is high. These costs are often seen in job completion times that far exceed the 30 minute limit. The time interval between the scheduled time and completion time of the job is the time taken to complete the job.

  3. Schedule each job to run slightly over the job completion time. To ensure that the previous job is completed, it's best to add a few extra minutes to the job completion time obtained in step 2 while scheduling each job.

Parameters

Parameter

Optional or Mandatory

Description

Parameter Values

Special Combinations Required

Notes

Object Name

Mandatory

Specify the object's API name For example, OpportunityVO.

N/A

None

The object name you provide here must be the same as the object's API name on Application Composer's Object Overview page. Also, if you have any jobs scheduled from a previous release you must change the object name to match the object's API name on Application Composer's Object Overview page.

Object Function

Mandatory

Specify the object's function name. For example, OpptyMsg

N/A

None

None

Troubleshooting Information

  • Each job run constitutes a transaction. This means that all the operations specified by the Groovy script in the object function have to run to completion to complete the transaction. Otherwise, the transaction is rolled back and no records are updated.

  • Once the job execution starts, the Cancel button won't work and you can't cancel the job.

  • If a record is updated, the Last Updated By value changes to the user who submitted the job, and the Last Updated Date value changes to the date and time of the update.

  • The log file displays any errors occurred during the process. To view the log file of a process, in the Log and Output section, click the attachment link to download the console log file.
    Note: If the object function was defined to have no return values, only the console log file is displayed and is downloaded when you click the link. Otherwise, an Attachment dialog opens with the console log file and the console text file.
  • Review the log and note the failed record IDs.
  • The runtime messages of scheduled Groovy object functions don't display the println messages. So, as a workaround, you can create a custom button for the object function with the println function, and then invoke that button from the object's detail page. See Actions and Links for information on creating buttons.

    Adding the println function in object functions and enabling runtime messages can help determine the exact cause for failure. See Runtime Messages for more information about the println function.