6.10 Scheduling Queries

Each database element and alarm that has a query needs a basic schedule that allows the adapter to routinely check for additional information and updates.

Schedules are shared among all database and element definitions within the adapter definitions. Therefore, before changing a schedule that could be used by multiple definitions, make sure the changes are appropriate for all.

If you do not create and assign a schedule to the database element or alarm definition, the DEFAULT_SCHEDULE is automatically used. The default schedule, which can be modified, runs every 5 minutes over a 24 hour cycle.

Set a schedule to run at adapter start, on a routine basis, or at set times. Multiple options can be selected. When specifying a time, you can use UTC (coordinated universal time).

The adapter property Scheduling Timezone can determine which time zone is used to run scheduled queries. For more information, see Section 4.4, Specifying Run-Time Adapter Properties.

6.10.1 Scheduling a Query

  1. Select an element or alarm in the Definition Navigator pane.

  2. In the right pane, click the Schedule icon to assign a schedule to the query.

    If no schedules exist, skip ahead to the next step-by-step instructions on how to create a schedule:

  3. Click (Select an Existing Schedule) to open the dialog box.

  4. Select a defined schedule.

    The schedule’s name displays in the Name field:

  5. Click OK to assign the schedule to the definition.

6.10.2 Creating a Schedule

  1. Select an element in the Definition Navigator pane.

  2. In the right pane, click the Schedule icon.

  3. Click (Create a New Schedule).

    The Query Results pane is cleared so you can specify the schedule requirements.

  4. Specify the name in the Schedule ID field.

  5. Specify when to run the query (you can select multiple check boxes):

    • To run the query whenever the adapter is started, select the At Adapter Start check box.

    • To run the query on a routine basis, select the On a Routine Basis check box.

    • Use the spinners to specify how often the query runs between specific times of a day.

  6. To run the query at specific times, select the At the Following Times check box, then create a time slot and specify the start time:

    Multiple start times are allowed. Use the buttons to manage multiple time slots:

    Create a new time slot.

    Delete the current time slot.

    If multiple times exist, move the current one up or down in the list.

    Keep in mind the adapter property Scheduling Timezone can determine which time zone is used to run scheduled queries.

    For more information, see Section 4.4, Specifying Run-Time Adapter Properties.

  7. Select the On the Following Days check boxes to specify the days associated with the selected times.

  8. To trigger the schedule through a scripted event, select the On a Scripted Event check box.

    For more information, see Section 6.10.7, Triggering Schedules through Scripted Events.

  9. To use settings from a macro expression instead of those specified here, select the At Times Parsed From Macro Expression check box, then select an expression from the drop-down list.

  10. To designate that times are in UTC (coordinated universal time), select the Times Are in UTC check box.

  11. To save the new schedule, click (Save Schedule Changes).

    The schedule is now available in the Schedule Library for use with other element and alarm definitions within this adapter definition.

6.10.3 Editing a Schedule

Schedules are shared between alarm and element definitions within an adapter definition. Verify that all changes made to a schedule are valid for other definitions that use it.

To edit a schedule:

  1. Select an element in the Definition Navigator pane.

  2. In the right pane, click the Schedule icon.

  3. Click (Edit an Existing Schedule).

  4. Select a schedule, then click OK to open the schedule.

    The schedule displays in the Query Results pane.

  5. Make the necessary changes to the schedule.

  6. Click (Save Schedule Changes).

6.10.4 Disabling a Schedule

Clicking the Schedule Disabled check box disables all queries associated with the schedule, including queries using macro expressions.

To disable a schedule so that all queries associated with the schedule do not fire and run:

  1. Click the Schedule icon.

  2. Click (Edit an Existing Schedule).

  3. Select a schedule, then click OK to open the schedule.

  4. Select the Schedule Disabled check box.

  5. Click (Save Schedule Changes).

6.10.5 Clearing a Schedule

Clear a schedule so it does not apply to a specific definition. This is useful when you want to replace the current schedule with a new one. In effect, the Clear button removes a schedule from an adapter definition, but leaves it available for other queries.

To clear a schedule:

  1. Select an element in the Definition Navigator pane.

  2. In the right pane, click the Schedule icon.

  3. Click (Select an Existing Schedule).

  4. Select a schedule, then click OK to open the schedule.

  5. Click (Clear Schedule Selection).

    All schedule fields are cleared and reset.

6.10.6 Deleting a Schedule

Deleting a schedule removes it from the system. If the schedule is assigned to other alarms and elements within the adapter definition, you must assign valid schedules to them.

To delete a schedule:

  1. Select an element in the Definition Navigator pane.

  2. In the right pane, click the Schedule icon.

  3. Click (Select an Existing Schedule).

  4. Select a schedule, then click OK to open the schedule.

  5. Click (Delete an Existing Schedule) to permanently delete the schedule from the system.

6.10.7 Triggering Schedules through Scripted Events

Schedules can be triggered through a scripted event. The following are two example scripts:

// This script will fire a run of the Data Integrator schedule named ONCE for 
// any Data Integrator adapters running that have the trigger by scripted 
// event enabled.
load( 'util/bdievent' )
fireBDIEvent( 'ONCE' )

// This script will fire a run of the Data Integrator schedule named ONCE for a
// specific Data Integrator adapter running named BAM5 if it has the trigger by
// scripted event enabled.
load( 'util/bdievent' )
fireBDIEvent( 'ONCE' , 'BAM5' )

An alternative to the Schedule pane in the Definition Navigator pane is specifying schedule settings in text form as a macro expression (adapter property).

Enable the macro expression option and provide a macro expression that contains text (nonempty string). At run-time, the text is used to configure the schedule. All settings in the Schedule pane are ignored. If the macro expression is empty, then the settings in the Schedule pane are used. If the Schedule pane has the Schedule Disabled option selected, then the schedule does not fire, regardless of whether a macro expression is selected.

Macro expression schedule text can use either of the following formats:

  • [setting1]; [setting2]; [setting3]; ...

  • [setting1] & [setting2] & [setting3] & ...

Settings are case-insensitive. The following lists acceptable setting values:

  • ‘disable' (aliases are 'disabled', 'off', 'none', 'false'): If present, the schedule does not fire regardless of the other settings.

  • ‘utc': If present, then dates are interpreted as being in UTC format.

  • ‘atstart' (aliases are 'at start', 'onstart', 'on start'): If present, the schedule fires upon adapter startup.

  • ‘atevent' (aliases are 'at event', 'onevent', 'on event'): If present, then the schedule can be triggered by a scriptable event as described previously.

  • ‘every n seconds|minutes|hours [between HH:MM and HH:MM] [on MON,TUE,WED,THU,FRI,SAT,SUN]': Where n is a number representing the interval, which can be seconds, minutes or hours (abbreviate using the first letter).

    The between times and the On Days clauses are optional. HH hours are always in 24‑hour notation as AM and PM are not allowed. Examples:

    • every 5m

    • every 1h between 20:00 and 23:00

    • every 1h on Mon,Wed,Fri

    • every 1 hour

    • every 5 hours between 10:00 and 16:00 on Sat,Sun

  • ‘at HH:MM, HH:MM, HH:MM [on MON,TUE,WED,THU,FRI,SAT,SUN]': Where the On Days clause is optional. HH hours are always in 24‑hour notation as AM and PM are not allowed. Examples:

    • at 10:00

    • at 10:45, 22:45

    • at 13:30, 16:30 on Mon,Wed,Fri

6.10.8 Scheduling Queries at Adapter Startup and On Demand

Use a job script to run Data Integrator queries at fixed times during the day, such as during off-business hours or when the Data Integrator adapter starts or restarts.

The executeQueriesForSchedule method is available to trigger queries on demand for a run-once schedule. The following example script uses this method:

...
try
{
   var adapterElement = formula.Root.findElement( adapterName );
   if (adapterElement != null)
   { 
       var adapter = adapterElement.getAdapter();
       if ((adapter != null) && (adapter.isStarted() == true))
      {
           var bdi = adapter.getControl();
           if (bdi != null)
          {
                bdi.executeQueriesForSchedule( scheduleName );  
          }
       }
  }
catch(e)
{
     formula.log.info("Scheduling BDI from script failed, with following error
message: " + e);
}
...