Startup Listeners

API Server executes the JavaScript code that is defined for the startup listener each time 
Layer7 Live API Creator
API Server executes the JavaScript code that is defined for the startup listener each time 
Layer7 Live API Creator
 starts. More specifically, API Server executes the listener every time the WAR file starts. If the API Server system administrator or the infrastructure support engineer restarts the 
Layer7 Live API Creator
 WAR file, API Server executes the startup listener again.
You can create startup listeners that signal to a registry (for example, Consul) that the server is up, that log an event to an outside system, or that configures the API based on an outside source of information, such as a file or a directory system.
As API Server executes the listener, it creates an entry in the log. You can view the list of logs on the Logs tab. You can filter the list of logs by time and by listener name, refresh the list, and delete all logs.
In this article:
Create a Startup Listener
  1. With your API open, in the Create section, click 
    If you have not created a listener yet, the Welcome to Listeners and Connections page displays. If you have a listener created already, the Details tab on the Listeners page displays.
  2. Do one of the following:
    • If you have not created a listener yet, create a listener by clicking 
      Create a Listener
    • If you have a listener created already, above the list of listeners, click 
  3. Complete the following fields, and then save your changes:
    Listener name
    Defines the listener name.
    New Listener
    Register with Consul
    Listener type
    Defines the listener type. Select 
     Startup, Shutdown, MQTT, KafkaConsumer, and KafkaProducer
    Logging level
    Defines the level at which the listener outputs messages to its logs. The messages that appear in the log are only the messages that are logged at a level equal to or superior to this logging level. For example, if the listener has a logging level of 
    ), then the following code has no effect, because the listener's logging level of 
     is a higher logging level than 
    log.debug('This is a log message');
      • Off:
         The listener does not output messages to the log.
      • Error:
         The listener outputs only serious errors to the log.
      • Warning:
         The listener outputs serious errors, including warnings, to the log.
      • Info:
         The listener outputs serious errors–including warnings and information messages–to the log.
      • Debug:
         The listener outputs serious errors–including warnings, information messages and high-level debug messages–to the log.
      • Finer:
         The listener outputs serious errors–including warnings, information messages, high-level debug messages, and medium-level debug messages–to the log.
      • Finest:
         The listener outputs serious errors–including warnings, information messages, high-level debug messages, medium-level debug messages, and low-level debug messages–to the log.
    Indicates whether the startup listener is active and
    Layer7 Live API Creator
     can execute it. Controlling their state can be useful during development, or if you want to disable the listener without deleting it.
  4. Click the 
     tab, enter the JavaScript code that 
    Layer7 Live API Creator
     executes each time 
    Layer7 Live API Creator
     starts, and then click 
    You can use the following JavaScript objects inside the listener code:
    • The 
      For information about this object, see The listenerUtil Object.
    • The 
      For information about this object, see The log Object.
    • The 
       object. The standard JavaScript object for converting objects to and from JSON strings.
      You can view a list of the available methods that you can use in your JavaScript code using code completion. For more information about code completion, see Code Completion.
  5. Click the 
     tab, select the 
     checkbox, and then click 
Your startup listener is created and is active.
Example: Create a Startup Listener that Registers a Service with a Consul Cluster
Consul is a popular service discovery mechanism which allows for dynamic lookup of services. The following example is a real-world example of how to use a startup listener. In this example, whenever a server starts up with your API, you want to make sure that Consul is aware of it, so that it can refer other systems to it.
For more information about Consul, see the Consul documentation.
Use the following process to create a listener that registers a service with a Consul cluster:
Create a Startup Listener
Create a startup listener called 
Register with Consul
 as the listener type.
Enter the Startup Listener Code
  1. With your startup listener open, click the
  2. Enter the following code in the code editor, and then save your changes:
    var NewService = Java.type("com.ecwid.consul.v1.agent.model.NewService");
    var newService = new NewService();
    newService.setName("Live API Creator");
    newService.setTags(["My Live API Creator API", "Awesome"]);
    // Optional: add a service check so that Consul can check the health of the service
    var check = new NewService.Check();
    // The @heartbeat URL is handy because it does not require authentication, you could use
    // an unauthenticated custom endpoint too.
    check.setHttp("http://" + listenerUtil.getHostName() + ":8080/rest/abl/admin/v2/@heartbeat");
    var ConsulClient = Java.type("com.ecwid.consul.v1.ConsulClient");
    var client = new ConsulClient("localhost");
  3. Ensure that it is correct for your specific situation. For example, the Consul server name can be
    (as in this example) if you are running Consul on the same machine as
    Layer7 Live API Creator
    . In production system, this might not be the case. If you are not  running 
    Layer7 Live API Creator
     on port 8080, change the value in the code editor.
For more details about the consul-api API options and features, see the consul-api API documentation.
Install the Required Java Libraries
You have installed the Java library.
How you install the library depends on the platform you are running 
Layer7 Live API Creator
. For Apache Tomcat and Jetty, copy the following libraries to the
These libraries are indirect dependencies of the 
 Java library.
Start the Startup Listener
Marking your startup listener as active automatically starts the listener.
Follow these steps:
  1. With your startup listener open, click the
  2. Select the
    checkbox, and then save your changes.
     If the listener was already marked as active, clear this checkbox, save your changes, select this checkbox, and then save the changes again.
The listener starts.
Verify that the Startup Listener Ran Successfully
A successful startup is indicated by a log entry with a name similar to
Listener was started: Register with Consul
, and an empty log (unless you added some logging of your own to the code).
Look at your Consul directory and verify that the registration was successful.
Follow these steps:
  1. With your startup listener open, click the 
  2. If needed, click
  3. Locate and select the startup log for your new listener, and make sure that it does not contain any errors.
    A common error might look something like:
    Listener failed to start: Register with Consul 
    java.lang.ClassNotFoundException: org.apache.http.conn.HttpClientConnectionManager 
    This specific error message indicates that the Apache HTTP Client library is not available.
    For more information about how to install the Java libraries, see the "Install the Required Java Libraries" section.
You have created the startup listener.