Creating Timers

You can create pieces of JavaScript code that
Layer7 Live API Creator
executes at a specific time or regularly according to a schedule.
Timers are pieces of JavaScript code that
Layer7 Live API Creator
executes at a specific time or regularly according to a schedule. Timers can run any JavaScript code and have full access to the JavaScript environment, and to the underlying Java Virtual Machine (JVM).
Typical uses of timers include:
  • Data monitoring.
    You can create a timer that monitors an event change in your application database. The timer can then call a REST endpoint or publish a message. For example, you can check an action's due date and can find rows for which a required action has not been taken, and then alert users.
  • Scheduling routine procedures.
    You can create a timer that monitors a file system for file changes or updates, and then processes a transaction in
    Layer7 Live API Creator
    .
  • Time-based triggers.
    You can create a timer that runs repeated processing. For example, you can create a timer for day-end closing. The timer makes a routine call to a stored procedure REST endpoint in your backend database.
In this article:
3
Workflow
create a timer
Complete the Timer Details
  1. With your API open, in the Create section, click
    Timers
    .
    If your API does not have existing timers, the Welcome to Timers page appears. If your API has existing timers, they are listed on the Details tab.
  2. Complete one of the following options:
    • If you have not created any timers, on the Welcome to Timers page, click
      Create a Timer
      .
    • If you have created at least one timer, on the Details tab, click
      Add
      .
    The Details tab appears.
  3. Complete the following fields, and then click
    Save
    :
    Timer name
    The name for your timer. We recommend that you give your timer a unique name to avoid confusion.
    Time Zone
    The time zone for the execution of this scheduled event. For example,
    Time Zone: America/New_York
    Start date/time
    The date and time at which you want
    Layer7 Live API Creator
    to start running the timer code. If you do not specify a start date, then
    Layer7 Live API Creator
    executes the timer at the earliest opportunity, according to the schedule you configure for the timer.
    For more information about how to configure the timer schedule, see the "Configure the Timer Schedule" section.
    Required:
    No
    End date/time
    The date and time at which you want
    Layer7 Live API Creator
    to start running the timer code. If you do not specify an end date, then
    Layer7 Live API Creator
    executes the timer according to the schedule you configure for the timer.
    Layer7 Live API Creator
    executes the timer until you deactivate it or until you stop
    Layer7 Live API Creator
    .
    For more information about how to configure the timer schedule, see the "Configure the Timer Schedule" section.
    Required:
    No
    You can run the timer indefinitely by leaving the
    Start date/time
    and
    End date/time
    fields blank.
    Active
    Specifies whether the timer is active and whether
    Layer7 Live API Creator
    can execute it based on the schedule. You can deactivate the timer or can comment it out by clearing this checkbox.
    Default:
    Cleared
    Logging level
    Defines whether logging calls result in
    Layer7 Live API Creator
    adding to the log record for the execution.
    For example, if a timer's code logs using the
    debug
    level, for example
    log.debug("My timer is now executing");
    and you have set the timer's logging level as
    Info
    , then
    Layer7 Live API Creator
    does not log the logging message to the timer log.
    For more information about how to use the
    log
    object, see The log Object.
    Log only if output
    You can select this checkbox only if you have selected the
    All servers
    checkbox. Specifies that you want
    Layer7 Live API Creator
    to record timer logs in the timer log only if the timer code outputs information. If you selected the
    One server only
    checkbox, then this option has no effect, and
    Layer7 Live API Creator
    creates a log record for each execution.
    For more information about timer logs, see the "Timer Logs" section.
    If your timer executes frequently, select this option to minimize the number of log records
    Layer7 Live API Creator
    creates.
The timer is created.
Configure the Timer Schedule
Layer7 Live API Creator
executes timers based on API Server's clock. You can set the schedule of a repeating timer using the options in API Creator. For greater flexibility, you can use the options available by entering a Crontab expression.
Prerequisite:
You are in the process of creating a timer or you have created the timer.
Follow these steps:
  1. Select the timer that you want to schedule from the list of timers, and then click the
    Schedule
    tab.
  2. Complete the following field to specify the duration, and then click
    Save
    :
    Schedule
    The frequency to run the timer. (Advanced users) To configure your timer to run on a custom frequency, select
    Custom
    and enter the expression using Crontab syntax. To get more information about the Crontab syntax you can use in expressions, click
    About Crontab Expressions
    . To view examples of the syntax, click
    Examples
    . To view and confirm the configuration of your Crontab schedule, click
    Next Executions
    .
    The Crontab syntax is extensive. You can specify a schedule as an expression using Crontab syntax rather than coding it in JavaScript. For complex schedules, you might prefer the flexibility of using JavaScript. You can schedule the timer to execute, for example, every minute. And then, in the timer code, decide whether the timer should execute.
    Layer7 Live API Creator
    uses the Quartz expression parser.
    For more information about how to create your expressions, see the Quartz documentation.
    Options:
    Yearly, Monthly, Weekly, Weekly, Daily, Hourly, By minute, By Second, Custom.
    Default:
    By minute
The schedule for the timer is configured. The next 20 executions that are based on the defined frequency are displayed.
Define the Timer Code
Prerequisite:
You are in the process of creating a timer or you have created the timer.
Follow these steps:
  1. Select the timer for which you want to define the code from the list of timers, and then click the
    Code
    tab.
  2. Enter the JavaScript code that
    Layer7 Live API Creator
    executes at the data and time you define for the timer, and then click
    Save
    .
    You can use the following JavaScript objects inside your timer code:
    • The
      scheduleDate
      object. Use this JavaScript
      Date
      object to define the date and time you would like
      Layer7 Live API Creator
      to execute the timer.
      The following code snippet shows an example on how to use the
      scheduleDate
      object in your code:
      // Do not execute on July 4, unless it's a Saturday
      // scheduledDate is a standard JavaScript Date object, so getMonth() returns a zero-based number,
      // and getDay() returns 0 for Sunday, 1 for Monday, etc...
      if (scheduledDate.getMonth() == 7 &&
      scheduledDate.getDate() == 4 &&
      scheduledDate.getDay() != 6) {
      // Do nothing
      }
      else {
      // Normal execution goes here
      }
      For more information about the JavaScript
      Date
      object, see the Mozilla documentation.
    • The
      timerUtil
      object. Use this object to invoke RESTful services and publish messages.
      For information about the
      timerUtil
      object, see The timerUtil Object.
    • The
      log
      object. This object includes methods such as
      debug
      ,
      info
      , and
      warn
      .
      For information about the
      log
      object, see The log Object.
    • The
      JSON
      object. This object is a JavaScript object for converting objects to and from JSON strings. This object includes methods such as
      parse
      and
      stringify
      .
      For more information about how to use the JSON object, see JavaScript.
      You can view a list of the available methods that you can use in your JavaScript code using code completion.
      For more information about viewing the JavaScript code example that you can access from the code editor in timers, see JavaScript Code Examples.
The timer code is defined.
Activate the Timer
Layer7 Live API Creator
executes active timers based on the timer schedule.
  1. Select the timer that you want to activate from the list of timers, and then click the
    Details
    tab.
  2. Select the
    Active
    checkbox, and then click
    Save
    .
The timer is activated.
Test the Timer
You can test your timer to make sure it is behaving as you expect. This is useful when developing the timer. Select the timer that you want to test from the list of timers, and then click
Test this Timer Once
.
Timer Logs
Layer7 Live API Creator
creates an execution log each time it executes a timer. Each log entry lists the timer start date and time, duration, server information, and the result, if any. The log entries for the timers that
Layer7 Live API Creator
executes successfully are listed with status of "OK". Those that
Layer7 Live API Creator
executes unsuccessfully are listed with a status of "ERROR".
You can access these logs by creating a logger for externalizing your API logs.
For more information about how create a logger, see External Logging.
Troubleshoot Timers in Clustered Environments
You can view timer logs and identify the node within the cluster where
Layer7 Live API Creator
executed the timer. In a cluster, each server has a unique ID, which is by default a UUID. This unique ID is the server ident. You can set the server ident during installation or at server startup. To limit the execution to a single instance, deploy the server with an active timer.
For more information about the option to set the server ident during installation, see API Server Startup Options.
The following are methods you can use to troubleshoot timers in clustered environments:
  • Use a listener instead of a timer. With listeners,
    Layer7 Live API Creator
    sends messages to the cluster. The first listener to receive the message executes the code.
  • Write a database across the cluster using the server UUID. The first listener to commit the transaction executes the code on that server instance.
You can locate the server ident by clicking
APIs
, and then clicking
Server
.
Deploy Timers to Other Environments
You can deploy your timer to other environments by deploying it as part of your API.
Follow these steps:
  1. Export your API.
    Your timer is exported in the inactive state by default. If you want your timer to run immediately in the deployed environment, activate your timer.
    For more information about how to export APIs, see Import and Export APIs.
  2. Import your API.
    For more information about how to import APIs, see Import and Export APIs.
  3. Modify your API.
    For more information about how to modify your API using the Admin CLI, see the Admin CLI documentation on GitHub.