AX1034

Executing Scheduler jobs from an Axiom form

You can execute a Scheduler job from within an Axiom form by using the RunEvent command.

Requirements and limitations

The setup for the Scheduler job that you want to run is the same as when using the RunEvent function in Axiom files. You must define an event handler within the job, and then configure the job as desired, including any variables that you want to pass in when the job is executed. For more information on this general process, see Using RunEvent to execute a Scheduler job.

Setting up RunEvent within an Axiom form

To allow users to execute a Scheduler job from the Axiom form, you use a Button component that is configured to run the RunEvent command shortcut. This is the same command that is available for use in task panes.

To start off, add the component to the Axiom form canvas and then configure the properties as desired. You will probably want the text for the component to be something like "Process Plan Files" or "Process Monthly Reports" (depending on what the target Scheduler job is doing). You can then configure the Command for the component as follows:

  1. In the component properties, click the [...] button to the right of the Command box.

  2. In the Shortcut Properties dialog, click the [...] button to the right of the Shortcut Target box.

  3. In the Axiom Explorer dialog, select the Command Library, then select RunEvent, then click Open.

    In the Shortcut Properties dialog, the RunEvent command is now listed as the shortcut target, and the relevant shortcut parameters are now available.

  4. Complete the shortcut parameters as follows:

    Parameter Description

    Event Name

    Required. The name of the event handler that you want to trigger. Any job with an active event handler of the same name will be scheduled for execution.

    Result Message

    Optional. A confirmation message to display to the user after the jobs have been scheduled. If omitted, the standard generic message is used.

    Processing Step

    Optional. Specify the desired Processing Step for the command. By default, this is set to Form - After Updating Values, which means that the command will be performed after any changed values in the Axiom form have been submitted back to the source file.

    If desired, you can specify a different point in the refresh process for the command. For more information on when each process step occurs during the form refresh process, see Axiom form update process.

    NOTE: If you are using Event Variables, then the processing step for the command must be set to After Updating Values or later in the process. If the processing step is set to Before Processing, then the command will execute before any changed values are submitted back to the source file.

    NOTE: In other contexts, the shortcut parameters for the RunEvent command allows for defining a confirmation message. This parameter does not display for Axiom forms, because the confirmation message should be defined on the Button component properties instead.

  5. Optional. If you want to pass variable values to the Scheduler job, you can do this using the Event Variables section.

    • Enter the variable name in the left-hand box. This variable must be defined in the target Scheduler job and used in the job settings.
    • Enter the variable value in the right-hand box. You can hard-code a value, or you can enter a cell reference in brackets. For more information, see the following section.

    • If you need more rows to define additional variable values, click the plus icon .

    Example Shortcut Properties dialog

  6. Once you have finished configuring the Shortcut Properties, click OK to close the dialog and return to the component properties.

Within the Axiom form, the user can click the button to perform the RunEvent command. Axiom Software will look for any jobs with a matching event handler name and place them on the schedule to be eligible for immediate execution (pending available Scheduler threads and any higher-priority jobs already in the queue). The result message will display in the bottom left-hand corner of the form.

Collecting variable values from the Axiom form

If desired, you can set up the Axiom form to collect variable values from the user, and then pass those values to the Scheduler job via the Event Variables. To do this, you must:

  • Place one or more interactive components in the Axiom form to collect the input from the user. For example, you might use a Text Box or Combo Box component, or you might use an editable cell within a Formatted Grid component.

  • When configuring the shortcut parameters for the RunEvent command, you should designate a cell reference in brackets as the variable value. Axiom Software will read the variable value from the designated cell.

    If the component you are using to collect user input is a Formatted Grid component, then the cell reference can simply point to the editable cell in the grid (or the target cell of the interactive content tag). If the editable cell is A15 on Sheet1, then you enter [Sheet1!A15] for the variable value.

    If you are using a different interactive component, such as a Text Box component, then you should use an indirect reference for the updateable property of the component, so that the value is written to and read from a cell in another sheet. For example, for the Text property of the text box, you can enter [Sheet1!A15]. This means that the text box value will be written to and read from that cell, instead of the Text cell on the Form Control Sheet. You would then also enter [Sheet1!A15] as the variable value.

    You should use this indirect behavior instead of referencing a cell on the Form Control Sheet directly, because any time a new component is added to or deleted from the form, that cell reference may change.

The Axiom form user can complete these inputs before pressing the button to trigger the RunEvent command. There is no way to require the user to complete these inputs, however, you can use the Confirmation Message property of the button to remind the user to complete the inputs and confirm that they want to continue.

When the user presses the button in the form, the following occurs:

  • If a Confirmation Message is defined for the button, that message is presented and the user must click OK to continue (or Cancel to cancel, in which case none of the following steps occur).
  • The changed values in the form are submitted back to the source file.
  • The RunEvent command is executed (this assumes the Processing Step for the command is set to After Updating Values).
  • The refresh process for the form then continues as normal.