AX2548

Using RunEvent to execute a Scheduler job

Using RunEvent, you can trigger the execution of a Scheduler job from various contexts, such as within Axiom files, task panes, or Axiom forms. There are two different versions of RunEvent:

• RunEvent function: The RunEvent function can be used in Axiom files to trigger the execution of a Scheduler job from a spreadsheet.
• RunEvent command: The RunEvent command can be used in task panes or Axiom forms to trigger the execution of a Scheduler job.

Both the function and the command work in the same way and take the same parameters. Some limitations apply depending on the context where RunEvent is being used.

All of the information necessary to run the job is contained within the RunEvent function or command. It is assumed that an administrator (or a power user with the necessary rights) sets up the desired jobs within Scheduler, and then sets up RunEvent in the appropriate context so that end users can trigger it.

The end user who triggers the job using RunEvent does not need to have any Scheduler security permissions. The job itself can be configured to run using the permissions of the job owner or using the permissions of the end user who triggered the job (the requester). If the job is run as the requester, then the end user must have the appropriate permissions to the files impacted by the job (for example to the target file for File Processing, or to the target file group and plan files for Process Plan Files).

NOTE: You can also use the Raise Event Scheduler task to trigger the execution of a Scheduler job from a different Scheduler job. This works in a similar manner as the RunEvent features.

Setting up a Scheduler job for RunEvent

All uses of RunEvent require the same job setup in Scheduler:

• The job that you want to execute via RunEvent must already be created within Scheduler. When setting up the job, consider items such as the notification settings. Do you want the notifications to go to the user that executed the job, or to the job owner, or both?

• The job must contain an event handler that will be used to trigger the job execution. When creating the event handler, consider whether you want the job to run as the job owner, or as the requester (the user who clicks on the RunEvent function). This may impact email notifications and determines the user rights under which the job will run.

  

  For more information, see Creating event handlers for a job.

• Optionally, the job can use variables. Variable values can be defined in the RunEvent function or command and passed to the job. You would do this if aspects of the job need to be dynamic; for example, if you want to use a different filter depending on which user is running the job or based on a user selection in the file. For more information see the Variable example section below.

Setting up RunEvent

Regardless of the context, RunEvent uses the following properties to trigger Scheduler jobs:

• The event handler name that identifies the Scheduler job(s) to trigger for execution.
• An optional confirmation message to present to the user before proceeding with the event. Not available when using the command within an Axiom form.
• An optional success message to present to the user after the event has been raised.
• If variables are being used, one or more variable names and values to pass to the Scheduler job. This is available in all contexts, however, task panes do not currently support the ability to determine the variable values dynamically.

The following shows an example RunEvent function for use in an Axiom file:

The first parameter defines the display text for the function, while the second parameter specifies the event handler name. In this example we have also defined a custom confirmation message for the user and a variable value to pass a filter to the job. The following screenshot shows the function in the spreadsheet:

The next screenshot shows a RunEvent command set up on a Button component for an Axiom form. You can see the same event name and the filter variable also being read from a sheet location.

User experience

The user experience for RunEvent depends on the context and whether you are using optional custom messages.

• The user starts the process by doing one of the following:
  • Double-clicking the RunEvent function in the spreadsheet.
  • Clicking the Button component that is configured for RunEvent in the Axiom form.
  • Double-clicking the RunEvent item in the task pane.

• A confirmation prompt displays to the user, asking them to confirm that they want to proceed. The user can click Yes to proceed, or No to cancel. Default text is used if no custom text is defined in the RunEvent properties.

  

  NOTE: This step does not apply when executing RunEvent from an Axiom form. The Axiom form context does not support a confirmation message. However, you can configure the Button component to display a confirmation message before executing the RunEvent command.

• Axiom Software checks all Scheduler jobs to see if any contain an active event handler with the same name as specified within the RunEvent properties. If any are found, they are added to the schedule to be processed as soon as possible, depending on Scheduler thread availability and any higher-priority jobs in the queue.

  It is important to note that RunEvent triggers job execution based on the event handler, not based on specific jobs. If multiple jobs contain an event handler with the specified name, then all of those jobs will be scheduled.

  If variable values are defined in the RunEvent properties, those values are passed to the job. If a variable specified in the RunEvent properties is not used in the job, it is ignored.

• A confirmation message displays to the user as follows:

  • If no jobs were found that contained the specified event handler, the user is notified that no jobs were found.

  • If jobs were placed on the schedule, the user is notified that the specified event was scheduled. Default text is used if no custom text is defined in the RunEvent properties.

  NOTE: If executing RunEvent from an Axiom form, this message displays in the bottom left corner of the form, not in a separate message dialog.

When the job is finished processing, email notifications are sent according to the settings in the job.

Variable example

When using RunEvent to execute a Scheduler job, you can pass a variable value to the job. For example, imagine that you want to execute a Process Plan Files job, and you want to send a filter value to the job.

Step 1: Set up the variable in the job

The first step would be to create a job variable in the job, and then use the job variable in the filter setting.

NOTE: In this case, we have defined a default value for the filter variable (1=0) that does not result in any plan files. This is because we do not want to process any plan files unless a filter is provided by RunEvent. If we left the default value blank, that would mean all plan files would be processed if no filter was provided by RunEvent.

For more information on Scheduler job variables, see Using job variables.

Step 2: Configure RunEvent to use the Variable

Now that the job is set up to use the filter variable, you must configure RunEvent to pass in a value for that variable. If you are using the RunEvent function in an Axiom file, you use the following syntax within the function parameters:

These name / value pairs can be placed in the RunEvent function starting in the fifth parameter of the function. If you have two name / value pairs to pass to the job, you can use the fifth and sixth parameters, and so on.

For example, to pass the filter DEPT.Region='North' to the job, the RunEvent function would be constructed as follows:

More likely, you would be reading the variable value from another place in the sheet, so the function would look something like:

When the job is executed by use of this RunEvent function, the value DEPT.Region='North' will be placed in the Plan File Filter box of the Process Plan Files task, and the job will be run using that filter.

When using RunEvent in an Axiom form, the variables and their values are defined in the Event Variables section. In this context you place the name of the variable in the left-hand box, and then in the right-hand box you enter the cell reference (in brackets) where the variable value will be read.

The Event Variables section is also present when configuring RunEvent for use in a task pane, however in this context the only option is to "hard-code" the values in the RunEvent properties.