Creating Timers

Timers are pieces of JavaScript code that  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).
lac52
Timers are pieces of JavaScript code that 
CA 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 
    CA 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
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.
    Timer type
     
    The type of timer.
    Options:
     
    • Execute once: 
      CA Live API Creator
       executes these timers only one time, on the date and time that you specify.
    • Repeating: 
      CA Live API Creator
       executes these timers on a repeating basis, starting and ending on the date and time that you specify.
    Default:
     Repeating
    Start date
     
    The date and time at which you want 
    CA Live API Creator
     to start running the timer code. If you do not specify a start date, then 
    CA 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
     
    The date and time at which you want 
    CA Live API Creator
     to start running the timer code. If you do not specify an end date, then 
    CA Live API Creator
     executes the timer according to the schedule you configure for the timer. 
    CA Live API Creator
     executes the timer until you deactivate it or until you stop 
    CA 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
     and 
    End date
     fields blank.
    Active
     
    Specifies whether the timer is active and whether 
    CA 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
    No overlap
     
    If you do not want 
    CA Live API Creator
     to overlap the execution of this timer, select this checkbox. Selecting this checkbox for a repeating timer to ensure that 
    CA Live API Creator
     does not execute the timer again while the previous execution is still ongoing. This option can be useful for long-running timers.
     If you have configured 
    CA Live API Creator
     to run as a cluster, 
    CA Live API Creator
     might still be in the process of executing the timer on a different server. Selecting the 
    All servers
     checkbox and this checkbox might cause a conflict and might not behave as expected.
    One server only
     
    (This option is for when you have configured 
    CA Live API Creator
     to run as a cluster.) Select this option if you want 
    CA Live API Creator
     to execute the timer on a node in the cluster instead of on all nodes in the cluster. 
    CA Live API Creator
     records the node on which it executed the timer in the timer log.
    Prerequisite:
     You have configured Hazelcast for cluster synchronization strategy. For more information, see Configure to Run as a Cluster.
    All servers
     
    (This option is for when you have configured 
    CA Live API Creator
     to run as a cluster.) Select this option if you want 
    CA Live API Creator
     to execute the timer at the scheduled time, nearly simultaneously on all nodes in the cluster. This option can be useful, for instance, if the timer looks for a change in the local file system.
    Logging level
     
    Defines whether logging calls result in 
    CA Live API Creator
     adding to the log record for the execution.
    For example, if a timer's code logs using the 
    debug
     level:
    log.debug("My timer is now executing");
    and you have set the timer's logging level as 
    Info
    , then 
    CA 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 
    CA 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 
    CA 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 
    CA Live API Creator
     creates.
The timer is created.
Configure the Timer Schedule
 
CA 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.
 
CA Live API Creator
 executes 
execute once
 timers:
  • On the defined start date or according to their schedule.
  • Only if the server is running at the scheduled time of execution.
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.
     
    CA 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 
    CA 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  
      CA 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
 
CA 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
 
CA 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 
CA Live API Creator
 executes successfully are listed with status of "OK". Those that 
CA 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 
CA Live API Creator
 executed the timer. In a cluster, each 
CA Live API Creator
 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 change it.
For more information about the option to set the server ident during installation, see API Server Startup Options.
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 environment by deploying your timer 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.