How Debugging Works
When creating a project, some things will not work the first time you try them. This is normal when implementing something as complex as an automated content project. For this reason, it is useful to know the possible error sources and the best ways to correct these errors.
Types of Errors
There are five separate kinds of errors you can encounter:
- Errors in the input data,
- Errors accessing the data,
- Orthography and punctuation mistakes in the Write tab or Lookup Tables,
- Syntax errors inside a Mapping node, Condition node or Phrase node,
- Logical errors, where wrong conclusions are drawn by one or more nodes.
Errors surface in several ways depending on their type.
- Some errors just appear as a wrong output only, and almost all error types mentioned above can manifest themselves like that.
- Some errors trigger error messages in our platform. This usually points towards syntax errors (category 4 above).
How to Find the Culprit
For finding the cause of an error, you can make use of the fact that the information flow in your project adheres strictly to one direction. Every piece of information (in that order)...
- Starts in your dataset.
- Gets accessed by Data nodes.
- Is perhaps modified in some way in a Node in the Transform tab.
- Is put into a Variable node to be accessible in the Write tab.
- Is used as a Container or Trigger in the Write or Narrate tabs.
- And may be modified by the settings of a Container.
To isolate a mistake, find the step in the list above. Move backwards from the last step and check every possible configuration or modification that is performed in each step. Once you find the correct information again, you went back one step too far - return to the previous step. This should indicate the source of the error.
When you find the mistake, make sure it only affected the information chain you traversed backwards.
Tools you can use to Find Errors
Several tools are provided to find errors, trace their origin and fix them. In this article, these tools are introduced and you will get a description of their basic use when creating a project and encountering an error.
Selecting a Suitable Preview Test Object
What it Does
Single objects from the uploaded data can be selected to be used as test inputs. The software then processes your configuration to create sentences and calculate logical decisions based on those example objects.
Why use it?
The results show if the project implementation has any errors in any of the steps; from data access step to text output step. Because the input was selected and is not a random object, the results become predictable and any deviations from the expected result is noticeable and most of the time quite easy to pinpoint.
Preliminaries
- Data must be uploaded in order to select an object as test object.
- This data should contain all the features that need to be tested.
How to use
There are two ways to select a fitting Test Object for the Preview.
The first and more general way to select a Test Object is as follows:
- Open the project you want to use to begin the test.
- Select the Data Sources area at the top.
- Select the Collection that contains the documents you want to use for the test.
- Hover your mouse over the Document you want to use for the test, a star and a trash bin should appear to the right.
- Click on the star so that the symbol becomes solid, and should stay solid after you move your mouse away from the Document.
You have just selected the object to use for testing!
A more specific way to select a Test Object is available to you in the Analyze tab. Here you can select a Test Object that have a specific value that you would like to test with. Select one as follows:
- Open the project you want to use to begin the test.
- Select the Composer area at the top.
- Select the Analyze tab in the green navigation bar.
- Select one of the analyses in the left column.
- Select a data field from the listing.
- In the right column you will now see exemplary values that occur in your documents for this data field. Click on the magnifying glass icon next to a value you are interested in to see only documents with this value.
- In the now open smaller dialogue you see all the Documents which have that value.
- Hover your mouse over the Document you want to use for the test, a star and a trash bin should appear to the right.
- Click on the star so that the symbol becomes solid, and should stay solid after you move your mouse away from the Document.
TIP
If you update your Documents in your Collection, the Test Objects are not automatically updated with them. To update a Test Object, navigate to the Composer. Open the Preview Test Objects drop-down menu and click Configure Test Object. Select a Test Object on the left and click Update on the right.
Live Preview on Statement Level
What it Does
The live preview of a statement displays a statement as it would appear in the output text. It takes into account the selected test object and carries out all calculations and evaluations for that statement that it would do in the final text. However, it shows only one of the possible output variants.
Why use it?
You can see your changes to a statement instantly.
This is very helpful to determine if the implementation of that statement is correct and complete. You can spot orthographic, logical, and data access errors as they happen and correct them quickly.
In most cases, this feature makes it unnecessary to render the entire text for an object, or even all the texts in a collection, since the problem is within a particular statement.
Preliminaries - Required
- A Test Object must be selected.
- The statement has to contain something that can be evaluated.
How to use
- Open the project you want to test.
- Navigate to the Composer.
- Navigate to the Write tab.
- Each statement automatically displays this preview.
TIP
The preview is also displayed if the statement is not triggered to appear in the resulting text. This allows you to work on statements and spot mistakes that are not available for the final text yet.
Live Preview on Node Level
What it Does
The node preview shows you the output that a node has for the current Test Object. Error messages are also displayed if the configuration of the node is technically incorrect.
Why use it?
Mapping nodes and Condition nodes are prone to spelling and syntax errors, since they must be written precisely and in adherence to a strict syntax. It is important for the user to find these errors quickly and easily. Configuration errors or incorrect output can also occur with other node types.
Preliminaries - Required
- The project has to contain and make use of nodes.
How to use
A node shows its results - calculated output, truth state or an error - directly in the node itself. When you select a node, you will find a scrollable result display at the bottom right of the Transform tab. There is also a project-wide breakdown of all errors and warnings, which can be found in the navigation bar of the Composer.
TIP
An interactive lesson on the component of a node can be found in our basic Seminar.
Review Tab
What it Does
In the Review tab you can view the original data and a generated text for a Test Object side by side.
Why use it?
This view is very helpful to compare the values you find in the data set and the output that they create. You can look for discrepancies, and can check if orthography of the static parts of your configuration is correct.
The composition of the complete output text that is visible here, helps you get a sense of what your final output for your products will look like.
The text that is generated here will not mark a Document as generated in the Collection directly. This can be helpful if you configured your systems for an automatic deployment of freshly generated content via webhooks.
Preliminaries - Required
You need a selected Test Object as described above.
How to use
- Navigate to the Composer area.
- Select the Review tab in green navigation bar.
- Select one of the Test Objects in the left column.
- The Test Object's data will be displayed and a text output will be generated.
- Press Regenerate if you want to review another version of your text.