19.1 Understanding Key Automation Concepts

An Automation lets you define a recurring job to run on a schedule or to invoke on demand.

Sequencing Automation Actions

Your automation performs a sequence of one or more actions. Each can execute code in the local database or a remote one. It can also send an email or push a notification to a user. When your app runs on Autonomous AI Database, server-side geocoding is available, too, as explained in Geocoding in the Background.

Running Actions Once, or Once per Row

The automation's action sequence can run a single time, or automatically repeat to process each row of a query you define. In the latter case, actions can reference the query column names as bind variables to reference values in the current row.

Processing Conditionally

You can configure a Server-side condition on both the automation itself, and any of its actions to perform work only under certain conditions.

Determining Frequency with Schedule Expression

If scheduled, a Schedule Expression indicates how often the job executes. For common situations, use the Interval Builder dialog. Otherwise, you can also enter any valid Database Scheduler syntax for more complex requirements.

Enabling or Disabling the Job as Needed

You control the automation's Schedule Status. If enabled, then the APEX engine runs the job on your schedule. If disabled, then it only executes if you run it interactively from App Builder's Automations list page or when you call APEX_AUTOMATION.EXECUTE.

Controlling Error Handling

By default the automation ignores errors that happen in an action, and the automation continues processing the following action and remaining rows. You can adjust this behavior to terminate the automation instead, and either keep it scheduled for its next run or disable it.

Consulting Automation Logs

The APEX engine maintains an automation log you can consult in App Builder, or query using the APEX_AUTOMATION_LOG view. Your automation can log additional information, warnings, and errors to the log using the LOG_INFO, LOG_WARN, or LOG_ERROR procedures in the APEX_AUTOMATION package.

Controlling Automations Programmatically

The APEX_AUTOMATION package has a procedure to EXECUTE an automation. When doing so, one signature offers a p_run_in_background boolean parameter to control whether it runs in the current user session (false) or a new session in the background (true). Other procedures let you RESCHEDULE, ENABLE, DISABLE, or TERMINATE an automation as well. In addition, your action code can call SKIP_CURRENT_ROW to immediately continue to the next row to process, or EXIT to end the automation prematurely without processing remaining rows.

Configuring Supporting Logic

In addition to the automation's action logic, you can optionally configure names of an Initialization Procedure, a Cleanup Procedure, and a Before Row Processing Procedure as required. These can be existing procedures, or defined as part of the automation in its Additional Code Execution section.

Working with Session State

Automations can read and write the values of application items as temporary storage. The automation's optional Initialization Procedure can assign an initial value to an application item, that the Before Row Processing Procedure as well as actions can reference and modify if needed.

In addition, if the automation processes the rows of a query, then actions can reference the current row's data using column names as bind variables. Where useful, actions can also update the current row's column values, but the APEX engine does not automatically save any such changes. Your action code needs appropriate logic to update any values in the database.

Executing with No Logged-in User

Unless you use APEX_AUTOMATION.EXECUTE to execute an automation in the current user session, they run in the background using a private background session with no logged-in user. In this situation, :APP_USER returns nobody.