How to create a heartbeat process for Atom runtime monitoring

Document created by Adam Arrowsmith Employee on Aug 2, 2016Last modified by Adam Arrowsmith Employee on Sep 25, 2017
Version 2Show Document
  • View in full screen mode

This article describes how to create a simple "heartbeat" process to use in help assessing an Atom's runtime health.


 Get the example process used below from the Process Library here.



Use Case

As part of a comprehensive Atom runtime monitoring strategy, it is important to ensure that in addition to the Atom service running and communicating with the platform, it is actually executing processes. This can be achieved by creating simple "heartbeat" processes that produce some expected result. This result can then be inspected at predetermined intervals by an external agent or monitoring tool.


Two generic heartbeart processes to consider are:

  • Scheduled process - To verify the scheduler is running and processes are executing.
  • Web service listener process  - To verify the web server is running, accepting requests, executing processes, and returning responses.
    • Note: Publishing web services requires the Services Enablement feature in your account.


 In addition, the Atom runtime has a built-in heartbeat API that can be used for external load balancers to monitor when determining available nodes for incoming web requests. See Atom web server monitoring.



  1. Create a scheduled process that overwrites a file on the local disk with simple Atom runtime information.
    1. Create a listener process that returns a response with simple Atom runtime information.
      1. Use a common subprocess that captures a few Atom runtime values for use in either process.
      2. Configure an external monitoring tool or script (outside of AtomSphere) to periodically check that the local status file has been updated recently (last modified timestamp) or invoke the web service and check for a successful response (HTTP 200).




      Scheduled Process

      This scheduled process generates a simple document and overwrites a file named atom_heartbeat.txt in the local Atom's /tmp directory.



      1. No Data start shape.
      2. Common subprocess to capture a few execution properties (see below).
      3. Message shape to format a simple text document.
      4. Set file name and directory.
      5. Disk write configured to overwrite if exists.


      Web Service Listener Process

      This web service listener process exposes a GET service (e.g. ../ws/simple/getAtomHeartbeat) that returns a simple text response.



      1. Web Services Server LISTEN start shape. Input Type=None. Output Type=single Data
      2. Common subprocess to capture a few execution properties (see below).
      3. Message shape to format a simple response document.
      4. Return documents to client.


      Common Subprocess

      This common subprocess can be referenced by the heartbeat processes to capture several execution variables and store as Dynamic Process Properties for use in preparing the outputs in respective process.



      1. Data Passthrough start shape.
      2. Data Process shape with custom scripting step (see below). Documents are passed through unmodified.
      3. Return Documents to calling process.


      Custom script:

      * Description: Sets the current Process Name, Execution ID and Atom ID
      * as Dynamic Process Properties. Intended for debugging or status purposes.
      * Input: None
      * Output:
      *        BOOMI_PROCESS_NAME
      *        BOOMI_EXECUTION_ID
      *        BOOMI_ATOM_ID

      import com.boomi.execution.ExecutionUtil;
      import com.boomi.execution.ExecutionManager;

      for ( int i = 0; i < dataContext.getDataCount(); i++ ) {
        InputStream is = dataContext.getStream(i);
        Properties props = dataContext.getProperties(i);

        dataContext.storeStream(is, props);

      // get the process name
      def processName = ExecutionManager.getCurrent().getProcessName();

      if (ExecutionManager.getCurrent().getParent() != null) {
          processName = ExecutionManager.getCurrent().getParent().getProcessName();
      ExecutionUtil.setDynamicProcessProperty('BOOMI_PROCESS_NAME', processName, false);

      // get the execution ID
      def executionId = ExecutionManager.getCurrent().getTopLevelExecutionId();
      ExecutionUtil.setDynamicProcessProperty('BOOMI_EXECUTION_ID', executionId, false);

      // Set the origin Atom ID - information
      ExecutionUtil.setDynamicProcessProperty('BOOMI_ATOM_ID', ExecutionUtil.getContainerId(), false);


      Usage Considerations

      • You can take the heartbeat process concept further to perform "deep pings" to check the availability of downstream applications and databases. For example, in the web service heartbeat instead of just getting AtomSphere process execution information and returning, it could "ping" a downstream system database with a simple query or connectivity test (something appropriate for the given application/protocol that always returns an expected result if the system is online) to check if it is available.
      10 people found this helpful