OL Connect Automate

Node-RED is a programming tool for wiring together hardware devices, APIs and online services. It was originally developed by IBM as an open source project and evolved into a general purpose IoT/IIoT (Internet of Things/Industrial Internet of Things) programming tool. It provides a browser-based editor that makes it easy to wire together flows using the wide range of nodes in the palette.

With the OL Connect Automate stack, Upland Software, Inc. has added its own set of nodes to this palette: OL Connect nodes and a couple of supporting nodes. The OL Connect nodes allow Node-RED to communicate with the OL Connect server and access the OL Connect Database and File Store. The supporting nodes perform common file system related tasks like triggering a flow when a new file arrives or list the files in a specific folder.

Automate vs. Workflow

The OL Connect Automate stack for Node-RED was born out of the need to provide users of OL Connect with a modern, web-based, cloud-friendly, unicode-aware automation tool.
For years, this job has been handled by OL Connect Workflow (aka Workflow), whose first version dates back to the turn of the century.
However, as powerful and efficent as Workflow is, its evolution is somewhat hampered by its original design: a native-code, 32-bit, on-premise application that only partially supports unicode. Consequently, we decided to explore other automation methods that could, at first complement, and ultimately replace Workflow. The packages that are part of the OL Connect Automate stack are the first step in this direction.

Note: The OL Connect Automate stack is a technology preview. The stack is not (yet) a replacement for OL Connect Workflow; in its current inception, it should be considered a complement to it.

The information in this chapter will help you get started with OL Connect Automate. It focuses on the OL Connect nodes, the settings that need to be made to communicate with the OL Connect server, and the most common flows in OL Connect solutions with Node-RED.
Tips and techniques regarding standard nodes in such solutions can be found in another topic: Node-RED: nodes and common techniques.

For general information about Node-RED, please refer to Node-RED's website: nodered.org.

Installation

  1. Follow the instructions on Downloading and installing Node.js and npm | npm Docs (npmjs.com).

  2. Start the Node-RED editor.

  3. Next, download and install the OL Connect nodes.

    You can do this using the Palette module: in the right-hand sidebar, click Manage Palette and look for @objectif-lune.

    Or, run the following command in your Node-RED user directory - typically ~/.node-red:
    npm install @objectif-lune/node-red-contrib-connect

    See also: https://flows.nodered.org/search?term=objectif-lune.

Note: Obviously, you must have OL Connect installed on a server that can be reached from the one where Node-RED is installed, otherwise you won't be able to perform any automation tasks.

Tip: Example flows are provided by OL Connect Automate, once installed. The examples appear in the flows folder in the Import dialog in Node-RED which allows you to import an example flow into a new or existing flow; see Importing and Exporting Flows in the Node-RED documentation.
Each example comes with a Comment node (Read me) with instructions.

OL Connect nodes

In a Node-RED application for OL Connect, flows communicate with the Connect Server and access its Database and/or File Store through one or more OL Connect nodes.

Currently, the following nodes are part of the OL Connect Automate stack:

  • data mapping, data get, data update values, document mapping, properties set, query items

    These nodes access the OL Connect database in order to either store or retrieve data - extracted from data files - or to set properties on the data.

  • paginated content, paginated job, paginated output, all in one, preview pdf, document mapping

    These nodes are used to create print output, including pdf previews on a web page. See An OL Connect print flow in Node-RED.

  • email content, sendgrid, mailjet

    The email content node renders emails, which can then be sent via an Email Service Provider using the sendgrid or mailjet node, or a third party node. See An OL Connect email flow in Node-RED.

  • html content

    This node renders web pages or Capture OnTheGo forms based on an OL Connect template. See An OL Connect web flow in Node-RED.

  • preview image

    This node merges the Print, Email or Web context of an OL Connect template with a single record and returns an image.

  • file store upload, file store download, file store delete

    These nodes access the OL Connect File Store, which holds OL Connect resources such as templates and data mapping configurations as well as output files such as email content and PDF files.

  • OL Connect Server

    This one configuration node is used by all nodes. It allows entering a URL and credentials to connect to an OL Connect server.

Note: The documentation of all individual nodes is embedded in Node-RED's editor. Hover over a node in the palette at the left, or select the node in a flow; then click the book icon.

Supporting nodes

The "files and folders" package contains nodes to perform common file system related tasks like triggering a flow when a new file arrives or list the files in a specific folder.

  • folder capture, folder listing

    These nodes help capture data. Folder capture monitors a folder for incoming files. The folder path can be set via a global variable. Typically these global variables are populated in a startup flow.

  • folder operations, file operations

    These nodes can move, copy or delete files and folders.

Connection settings for OL Connect Server

In order to setup a OL Connect Server connection:

  1. Add one of the OL Connect nodes to a flow.

  2. Double-click the node to open its Properties window and click the Edit Server icon (a pencil).

  3. Enter the URL, user name and password to use to connect to the OL Connect Server.

  4. Click Done.

The next time you add an OL Connect node to this flow, the server will appear in the list of servers in that node's Properties window.

OL Connect resources in Node-RED

OL Connect resources are files created with the Designer or DataMapper. In order to use them in the OL Connect nodes in a flow in Node-RED they need to be deployed to the OL Connect Server first.

Deployed resources are registered in the OL Connect database and saved in the File Store. OL Connect nodes can either refer to them by name or by using the internal database ID (also referred to as the managed file ID). The simplest approach is to use the resource name in the respective field of the node.

There are two ways to deploy OL Connect resources to the File Store: using the Designer or from within a flow in Node-RED's editor.

Flows in an OL Connect application

These are some of the typical flows in a Node-RED OL Connect solution.

  • Startup flow

    A Startup flow initializes variables in Node-RED's context - through which information is shared between nodes without using the messages that pass through a flow - and deploys Connect resources for the project. See OL Connect Startup flow for a detailed description.

  • Print flow

    A print flow creates and outputs paginated content. See An OL Connect print flow in Node-RED.

  • Email flow

    An email flow creates email content and stores it in the File Store or sends it immediately using an email service provider. See An OL Connect email flow in Node-RED.

  • Web (form) flow

    A web flow creates web content and stores it in the File Store or serves it immediately. See An OL Connect web flow in Node-RED.

  • PDF preview flows

    A PDF preview flow provides a PDF preview, usually at the request of a browser. See An OL Connect preview PDF flow in Node-RED.