Information for: DEVELOPERS   PARTNERS

Creating a graph

A graph is a series of connected nodes that execute their steps in a predictable fashion. Each node in the graph is either an adaptor, a piece of business logic or another graph. Nodes are connected by Links. A graph will always have a start node and must finish with a return node otherwise it will not be valid.

The following example graph has three nodes - a Columnar Table and two Return Nodes. It also has two links - one is a Goto link and the second is an Error Link.

Journey Graph

The Start Node - this denotes where the graph begins

The first node in the graph is decorated with an attachment on its left hand side - this denotes where the head or start of the graph is and can be moved to any node in the graph.

Links - this denotes where the data flows

The graph is traversed by executing each node in turn and following the relevant link from the current node to the next node based on the return value of the current node. The links are traversed in the following priority order:

  • Error - The most important condition and will always execute first if the node does not execute correctly
  • Conditional - Any conditional expression that returns True
  • Goto - If none of the above links are traversed

Listening Adaptors - this denotes where and how data will be picked up to be put into the graph

Acquia Journey calls the executable pieces Graphs because they are directed acyclic graphs which are executed by our proprietary graph engine. Graphs can have special starting nodes called listeners that generate work for the graph to execute. Listeners are always shown in the top left hand part of the graph window. Currently, we support having the following listener types:

  • Database
  • Queue
  • Twitter
  • API

Drawing a Graph

Open the Project Editor from the Home Screen or from the top right part of the Acquia Journey Screen. Press the Plus Button to create a New Item and choose the Blank graph from the right hand selection panel. Give the graph a name and press the large Create New Item Button at the bottom of the window.

This will give a blank graph with a single Start Node.

New nodes can be added to the graph by hovering over any existing node and dragging away from the link handle. Nodes can always be removed from the graph by right-clicking on the node and choosing Delete Node.

Nodes will generally snap to a grid if moved individually. Many nodes can be moved at once by creating a rubber-band selection around the nodes and then selecting the grey background to move all of the nodes.

Nodes can be deleted by right-clicking on the node and selecting - Delete Node. Any links associated with the node will also disappear with the node. Links can be moved separately by grabbing the connection point and moving it to a new node.

Replacing Ghost Nodes

Any of the Ghost Nodes - shown by grey boxes - in the graph can be replaced by double clicking on the node or right-clicking and selecting Replace Node. Either action will bring up the Replace Node chooser window which shows all of the basic node types, previously created graphs and business logic.

Choose one of the nodes, graphs or pieces of business logic to replace the ghost node. This exercise can be repeated for all of the nodes in the graph. For each node in the graph it is then necessary to set its particular values for input and output.

By default links are created as Goto links. The link type can be changed by selecting the link and using the Edit Link panel on the right hand side.

Links can be one of three types:

  • Goto - traverse the link without any conditions
  • Error - traverse the link if an error occurs in the node
  • Conditional - traverse the link if the Link Condition evaluates to True

In each case an alternative Link Description can be given. This is useful in particular if you have a long Condition that can be summarised more easily with a short description.

Conditions

Conditions can be chosen from the list of basic expression types or they can be advanced expressions.

Advanced expressions are any valid JavaScript boolean expression. The value of the preceding node is populated into the variable VAL. Common expressions include:

  • String equality

    VAL === "My String Value"
    
  • Numeric equality

    VAL == 6
    

See the reference section on conditions and expressions for further examples.

Graph validation

A graph can only be executed if all of the following conditions are true:

  • No ghost nodes
  • No ghost links
  • No nodes which have an input or output that has not been mapped to a data source
  • At least one return node

After all of these conditions are satisfied the Graph Editor window will show the indicator. See the Validation Warnings section below.

Graph Editor collaboration

The Journey Map and the Graph Editor are collaborative tools. Only one person at a time can be editing a graph but multiple people can be viewing the graph. If the graph is being edited by another user then the screen will be “gray” and a “Currently Being Edited By” message will be shown at the bottom right of the screen. You can watch other people modify the graph whilst it is in a locked state.

To take the lock press the Release Lock button. This will allow you to edit the graph. If two people release the lock at the same time the next person to actually edit the graph will be the person who captures the lock.

Validation warnings

Warning Note
Graph does not have a return node Every graph must have at least one return node.
Graph contains ghost nodes Before a graph can be executed all ghost nodes (displayed in grey) need to be replaced with executable node types. The number in parentheses indicates how many ghost nodes there are.
Graph contains ghost links Before a graph can be executed all links must be one of Conditional, Error or Goto. Click the highlighted links to set the type of the link. The number in parentheses indicates how many ghost links there are.