Workflow and Control Flow

Deciding whether or not to use some data in your text or which (text) part to use depending on a condition is the most common task when writing a single text that should cover a large number of different cases.

The NLG Cloud provide a large number of mechanisms that you can use in your text creation process. This section gives you a more general view without going into the detail.

Workflow

The most general workflow is left to right. For example, the menu represents the work flow you usually follow. Check the data (Analyze), decide on or modify the content to use (Transform), write the text (Write), proofread the text(Review) and at the end publish the text (Result). Your workflow is not linear from left to right and you are going to jump between these steps. We don't hinder you to do as you wish, but in that way you know in what kind of a step you are in and what you can do there.

This approach from left to right also applies to the individual areas. For example, in Transform, you select the nodes on the left side, use them in the middle, and configure them on the right side. In addition, the nodes follow the same concept. The ports on each node represent the data/content flow. The data nodes have their ports on the right side only (Output) and the variable nodes that you can use in Write only on the left side (Input). The other nodes that somehow process your content may have nodes on both sides. This is about accessing data, then processing data and finally making it accessible in Write.

Another example, in Write you see all created variables on the left side. In the middle you write your text, where you can include them in the text using containers, and on the right side you configure these containers. Again, with slight modifications, you find the same approach in the middle. A statement is used to write a part of your text, for example a whole sentence. If you add another statement, it will be on a different line, but the resulting text will still be a single line if you don't add an explizit line break.

Control Flow

The most fundamental control flow mechanism in the NLG Cloud is the if else expression. "IF the condition is met return this ELSE return that." You can use the return value or content either in your text directly or process it further. With that expression you can cover all your cases but it's rather arduous and error-prone. So, use it with caution when a combination of the options listed below can't solve your case.

TIP

When writing automatically generated text, at some stage you come to the point where you lose track and any small change could render a single piece of text from a stack of 1000 unusable. This is not new, but it surprises many people when they reach this state. One of the reasons for this is that you combine data, text logic and the actual text. On the way to the finished text you have made many decisions - which data to use and how to process it, which content is allowed to appear in the text and which statements should be triggered, which branches should be active in the statements and which stories should be generated.

To make it easier we provide:

- Condition Nodes [TODO: links](),
- Logic Ports [TODO: links](),
- Connections [TODO: links](),
- Group Nodes [TODO: links](),
- Decision Node [TODO: links](),
- Mapping Nodes [TODO: links](),
- (Trigger) Variables [TODO: links](),
- on/off-Switches [TODO: links](),
- Branchings and Branches [TODO: links]() and
- Statement Loops [TODO: links]().

You can see a Condition Node as a constraint if else expression - without the else-part. You can use parameters, function and other expressions (even if else) but the result has to be a Truth value [TODO:link Boolean]. You can use it like a railroad junction. If the condition evaluates to true you can proceed with the route(s) - activate connected nodes.

The Logic Ports in general provide(right side) or use the result (left side). All nodes with a logic port on the left side have a predefined behavior. If the logic port isn't used the node is active else the node reacts to the input. If the input is false the node deactivates. There is only a single node with a logic port on the right side which has a predefined behavior - the data node. If a data field has no content the result is false. That allows you to directly deactivate nodes or in combination with a trigger parts of your text that need to have that content to sound reasonable TODO:link.

The issues the Logic Ports help you to solve concern the logic you use for data processing or text. You can easily spot which Nodes are interconnected through logic and if they will be active or deactivated. For example, a data node has content that is placed in 5 different parts in your text but is slightly modified for each case, so 4 places should be filled but you see it only in 3. By following the Connections you can find all the involved Nodes in that process. If you see a Connection on a Logic Ports, then it's a signal that probably a custom condition is attached to a Node. You can now easily follow the Connection and checked if you have crafted the right expression or data to fulfill your condition correctly.

As mentioned, Connections are used to connect Nodes with each other. There are 2 different kinds of connection. A content and logic connection. You can easily distinguish them by checking the color of the port they are coming from or connected to. The main advantage of the Connections is the visible data flow.

WARNING

The case where it might be impossible to distinguish between content oder logic connections is when you use Mapping Nodes.

The Decision Node is like a railway switch without using many Condition Nodes. You have a single input and you can match it against different values (strings, digits) where a match activates a route.

The Group Nodes has a special functionality as a control flow mechanism. It creates a list from the content it gets. The special thing about it is when the inputs are a Phrase Nodes. By connecting it to a Variable Node and use it through a Container in your text you gain access to that control options. With them you can configure which elements of a list should be used and output them for enumeration statements or as a bullet point list. To achieve the same functionality on data you can use Mapping Nodes. If we use the content of a Phrase Node, it means we can apply grammatical features to the items of a Group Node and this is done in Write.

Another control flow mechanism in Transform is the mentioned Mapping Node. It can take parameters, use predefined functions TODO:LINK and expressions TODO:LINK and the result can be of ANY type. It gives you the highest form of freedom to process your data but can also take away a lot of maintainability and may lead to many issues. That depends on how you use it. The main use case for it is, if you need to modify your data. The control mechanism applies if you need to modify your data based on a condition and the result of it should be content and not a Truth Value.

TIP

We strongly recommend to use a Condition Node and connect it to the Mapping Node for activation. That way you separate the logic from data processing and it also becomes visible to you on the surface. Additionally, you should split every data processing step into multiple Mapping Nodes. That way you can easily track the results of each processing step with the in-built preview.

With a Trigger Variable you can control various parts of the text that you want or don't to generate. For example, you can (de)activation stories TODO:link, statements TODO:Links and branchesTODO:Links. It is very useful if you want to have a more dynamic text that reacts to you data.

In some configuration interfaces you will find on/off-Switches. The unique aspect is what these switches enable and disable a particular behavior. For example, if you deactivate a story with a switch you will see a prompt to select a Trigger Variable for user defined behavior. A statement has another Switch - Text Shortening. If you deactivate it the statement might be ignored to fit a predefined text length. A Container has a Switch, too, but it will only be available if the Container is used in a Branch.

To create a Branches you first create a Branchling for a text part. A Branchling decides which Branch should be used for text generation. With the functionality of Branchlings and Branches TODO:Link Configs you can easily add synonyms or semantically interchangeable text parts to your text. Furthermore, with the Branch Trigger you can control which Branch (text part) should be used. For example, you can exclude Branches if a particular condition is not met.

A Statement Loops is a very powerful tool to generate text for repetitive tasks. For example, a bullet point list. Using the Markdown syntax you can create a list in a Statement or over separate Statements, but issues with e.g. formatting may occur if you have a (very) long list. With Statement Loops you can create a single statement with correct formatting that should be applied to every list item. Another bonus of a Statement Loop is that it has its own Transform and Write area. That way you can focus only on the data and text that is relevant for the loop.