Creating a graph

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

The graph below has three nodes - a Columnar Table and two Return Nodes. It also has two links: a Goto link and an Error link. The first node in the graph has an attachment on its left-hand side; this attachment can be moved to any node in the graph to make it the first node:

Journey Graph

Starting a Graph

To begin a graph for a project, perform the following actions:

  1. On the Home Screen, identify the project you want to customize.
  2. In the project's tile, click the Project Editor Project Editor icon icon.
  3. Click the Action menu icon Action menu icon in the top left-hand side of the screen.
  4. Click + Create New.
  5. In the Graphs box, click Blank to select a blank graph.
  6. In the Name text field, name your graph.
  7. Click Create New Item at the bottom of the page to create your graph.

New nodes can be added to the graph by pointing your mouse to any existing node. A grab arrow will appear. Click and hold to select the grab arrow, and drag your mouse pointer to an empty area of the graph to create a new node linked to your previous node:

Add another node

Nodes can always be removed from the graph by right-clicking on the node and choosing 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.

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:

Move a group of nodes

Listening Adaptors

Graphs can have special starting nodes, called Listening Adaptors, which denote where and how data will be picked up to be put into the graph. Listeners are always shown in the top left-hand part of the graph window. The following listener types are supported:

  • Database - to process a queue of items from a database table
  • Queue - to process messages arriving in a message queue
  • Twitter - for Twitter stream items like hashtags, keywords, or direct messages
  • Graph API - to allow other systems to interact with your graph

To add a Listening Adaptor to a graph, click the + Add Add Listener icon at the top of the screen, select your Listener Type, provide your listener's information, and click Save.

Acquia Journey calls the executable pieces Graphs because they are Directed Acyclic Graphs, which are executed by our proprietary graph engine.

Parameters

When called from within another graph, a graph may receive parameters, which allows you to reuse business logic with different input values. When the graph is executed, the schema location for each parameter is populated by the graph that called it. The value is copied to the schema location, so modifications of the value within the called graph will not modify the value known to the calling graph.

To add parameters, complete the following steps when editing a graph:

  1. Click Add Parameters at the top of the screen to open the Parameters dialog.
  2. For each parameter you want to add, click Add Parameter, then enter a name for your new parameter.
  3. Click the arrow journey-left-arrow.png icon to the right of your parameter, then select the schema location to get the parameter from when the graph is called.
  4. When you are finished, click the ( x ) in the upper right corner of the dialog.

To modify or delete a parameter, complete the following steps when editing a graph:

  1. Click Edit at the top of the screen.
  2. Make any necessary changes:
    • To delete a parameter, click the trashcan icon to the left of the parameter name.
    • To modify a parameter's schema location, click the arrow icon to the right of the parameter name, then pick a new schema location.
  3. When you are finished, click the ( x ) in the upper right corner of the dialog.

To remove all parameters from your graph, complete the following steps:

  1. Click Remove at the top of the screen.
  2. In the Delete Item dialog, click Yes, Delete Item to remove all parameters from your graph.

The graph is traversed by executing each node in order, and following the appropriate link, based on the result, to the next node. The links between nodes denote how the data flows, and are traversed in in order of priority:

  • Error - This is the most important condition; it 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

To edit a link between nodes, click the arrow between the nodes. The Edit Link panel will appear on the right-hand side of the page. In the Edit Link panel, you can set the type of link (Error, Conditional, or Goto) as well as provide an alternative Description if your link needs more explanation.

Replacing ghost nodes

Ghost node icon Nodes with no information, known as Ghost Nodes, are shown with grey boxes in your graph. For your graph to validate, all Ghost Nodes must be replaced with nodes containing valid information.

To replace the Ghost Node with a valid one, perform the following actions:

  1. Double-click on the ghost node, or right-click on the node and select Replace Node from the menu.
  2. In the Replace Node window that appears, set inputs and outputs for the node.

Conditions

The condition expression is any valid JavaScript expression. The value of the preceding node is automatically 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
  • All nodes have their inputs and outputs mapped to data sources
  • At least one return node exists

Once all of these conditions are satisfied the Graph Editor window will show the Valid Graph indicator. Graphs with validation warnings will display a validation warning icon: Validation warning icon.

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, shown in grey, need to be replaced with executable node types. The number in parentheses shows 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 on the highlighted links to set the type of the link. The number in parentheses shows how many ghost links there are.

Contact supportStill need assistance? Contact Acquia Support