Creating Listeners

Listeners are pieces of JavaScript code that non-REST events can invoke. For example, execute the code when the server starts up or when a message is received on a given connection. You define how listeners respond to events. For example, a time-based listener can trigger the insertion of a row in a database or a system can process a message that it receives by publishing another message.
calac41
Listeners are pieces of JavaScript code that non-REST events can invoke. For example, execute the code when the server starts up or when a message is received on a given connection. You define how listeners respond to events. For example, a time-based listener can trigger the insertion of a row in a database or a system can process a message that it receives by publishing another message.
Typical uses of listeners include:
  •  
    Microservices.
     Microservices are autonomous and independent. For example, Service-1 requires access to Service-2, even when it is down. Some brokers, such as MQTT and Kafka, provide message queuing for delayed delivery. You can use listeners to process these messages.
    A typical listener might accept the message, convert to a JSON/XML string, and invoke the 
    listenerUtil.restPOST/PUT
     method. This method activates interface logic, which then activates reactive logic.
    The 
    Publish and subscribe to messages
     use case applies to this approach to using listeners.
    For more information:
  •  
    Internet of Things (IoT).
     IoT devices use MQTT. You can establish listeners to handle these messages. Typical IoT processing persists the message. You can modify or validate inbound data, with extra automation (persistence and object model), by declaring reactive logic events.
  •  
    DevOps.
     
    CA Live API Creator
     can also invoke listeners when the server starts. You can then register with a service discovery platform, such as Consul, or self-configure the server (for example, set data source connection parameters).
In this article:
 
 
Workflow
The following diagram shows the workflow for creating a listener in API Creator:
create a listener_new
create a listener_new
Connections
Connections are a set of properties that defines how to connect to an external system. MQTT, Kafka, RabbitMQ, and Java Message Service (JMS) listeners require a connection.
For more information about connections, see Create Connections.
Listener Types
You can create the following types of listeners in API Creator.
MQTT Listeners
MQTT listeners execute JavaScript code based on the arrival of messages to a specific topic in  MQTT brokers.
For information about how to create MQTT listeners, see MQTT Listeners.
Kafka Listeners
Kafka listeners execute JavaScript code based on the arrival of messages to a specific topic in Kafka brokers.
For information about how to create Kafka listeners, see Kafka Listeners.
RabbitMQ Listeners
RabbitMQ listeners execute JavaScript code based on the arrival of messages to a specific queue and exchange in a RabbitMQ broker.
For information about how to create RabbitMQ listeners, see RabbitMQ Listeners.
JMS Listeners
JMS listeners execute JavaScript code based on the arrival of messages to a specific topic in a JMS broker or brokers.
For information about how to create JMS listeners, see JMS Listeners.
Startup and Shutdown Listeners
Startup listeners are pieces of JavaScript that 
CA Live API Creator
 invokes whenever you start the 
CA Live API Creator
 server. API Server executes the listener's JavaScript code every time 
CA Live API Creator
 starts. More specifically, API Server executes it every time the 
CA Live API Creator
 WAR file starts. If the infrastructure support engineer or the system administrator restarts 
CA Live API Creator
 WAR file, the listener is again executed.
If you are running 
CA Live API Creator
 on a cluster of machines, the JavaScript code executes on each node as it starts.
Shutdown listeners are the mirror image of startup listeners. 
CA Live API Creator
 invokes shutdown listeners whenever you stop the 
CA Live API Creator
 server.
 If the container (for example, Apache Tomcat, Jetty, IBM WebSphere, and Oracle WebLogic) suffers a serious failure, 
CA Live API Creator
 might not invoke shutdown listeners upon shutdown.
For more information:
Listener Logs
 
CA Live API Creator
 maintains a log of its activity in the admin database. 
CA Live API Creator
 also generates logs for listener code that uses the 
log
 object in JavaScript scope. These logs are available from within the listener, on the Logs tab.
You can display the details for a log entry by clicking the log entry. You can search for a log entry by timestamp and the listener or connection name or the log summary. You can also refresh the list by clicking 
Refresh
 or by selecting the 
Auto-refresh
 checkbox. You can purge log entries from the database by clicking 
Delete All Logs
.
 
Log Details
 
You can access the following details for your listener logs on the Logs tab:
Detail
Description
Timestamp
The date and time 
CA Live API Creator
 generated this log entry.
Summary
The description for this log entry.
Logging level
The logging level for this log entry.
Listener
The name of the listener or connection.
Listener type
Defines the protocol that you want 
CA Live API Creator
 to follow to establish a link to an external system to exchange information.
 
Values: 
MQTT, Kafka, RabbitMQConsumer, or JMSConsumer
Server
The identifier of the server that created the log entry.
Parameters
The listener or connection parameters.
This log detail is not available for log entries that originate inside the listener code.
Log
The log entry in JSON format.
Listener Status
Listeners are either active or inactive. Active listeners are enabled in the API and inactive listeners are disabled in the API. API Server executes the listener code when it receives messages only for active listeners. You can mark a listener as active or inactive by selecting or clearing the 
Active
 checkbox.
Listeners in the "Running" status have initialized themselves successfully based on the configured connection. Listeners in the "Stopped" status have issues with the configured connection, with the listener parameters, or with the code.
 You can view the listener status from the status icon that appears at the top of the page in API Creator. The following image shows a startup listener in the "Stopped" status:
  Screen Shot 2017-09-22 at 4.39.28 PM.png  
The status is based on the following factors:
  • The validity of the parameters.
  • The status of the underlying connection.
  • Exceptions in the listener code that are causing the connection to fail.
 Troubleshoot listener issues using the log entries. Click 
Refresh
 or select the 
Auto-refresh
 checkbox.
You can also view a listener's status using the icon that displays to the left of the listener name in the list of listeners:
Icon
Listener Status
The listener is in the "Running" status and is active.
The listener is in the "Stopped" status and is active.
The listener is in the "Stopped" status and is inactive.