Debug View

Should you run into problems while creating a template's logic, the Debug view may come helpful. It offers two different kinds of data of a template's evaluation process that can help in figuring out why some parts of the logic are not working as you'd expect.

As the Debug view is part of the Dynamo template composing UI, none of the features specified here work as intended if a template is composed through the API since there's no UI to display the generated debug data.

Variable context

An integral part of any template evaluation process is the variable context that supplies commands with values for their attributes and into which these commands can then store the values they themselves produce. This subview displays all the values and their keys that exist in the variable context at a specific point of the template's evaluation, and can therefore be a great help if expressions are not resolving as expected or if you'd like to just inspect results of your template's Salesforce queries, for example. It also shows all the automatically created variables such as "UserInfo" which one might easily forget - or not even know of in the first place - but which can sometimes be quite useful in the logic.    

To display the Variable context view, a Debug break needs to occur in the template's logic. The potential for Debug break can be inserted into any command - it is basically a universal command attribute that takes an EL-expression as its value and interprets its resolved value as a Boolean. Should the result be "true", the Debug break occurs after the command is evaluated. Setting its value as "true" would therefore cause the break to occur always at this specific command, but you can also form expressions with less consistent results to make the break occur in certain cases only which can be useful inside loops, for example. However, should the evaluation of the Debug break's expression fail, no break occurs.  

When a Debug break occurs successfully, the run of the logic Flow is immediately stopped and the UI shifts into the Debug view.

Each variable in the context has its key and the type of its value displayed on the lines with grey background. Below that is the variable's value. If the value is of a type that has properties or contains other values, such as a Map or a Collection, clicking the '+' square opens the value, displaying its contents. Clicking it again hides the contents. With most of these types of values you'll see the keys and values of the contents, but with Collections you'll see no keys as the values don't have such - instead the index of each item is displayed. Maps and Collections with no content have nothing to click, so the value space simply displays "empty" in this case.

If the Debug break occurs inside of a command that creates a child context (such as forEach of the Loops library), the Variable context view is split into the Base context and one or more Child contexts (as displayed in the first image). In this case you may see the variable's type followed by a notice saying the variable is masking a variable in a parent context. This means that this child context has a variable with the same name as a variable in another context and commands in the child context can only see the child context's value for it - a potential source of unexpected expression results. The child context section may also explain why a variable seems to be missing in a later part of the logic as any of the variables there will be gone along with the child context when the context-creating command finishes.    

Logic trail

The Logic trail is a subview that displays every command evaluation that happened during the logic's evaluation. You can inspect details of every command's attributes, the variables they produced and see which evaluations failed due to errors. This is also a tool for inspecting what the Flow is spending time on, as it reports the time it took to execute every command and Step.

To be able to view the Logic trail, the evaluation process has to be instructed to collect this data. This can be done by specifying the request parameter "debugTrail" with the value "true", or in the Template builder you can check the "Debug View" option that appears in the submenu of the Test button. With this parameter any template will run as usual, but at the end of the evaluation the Debug view displaying the Logic trail from the start all the way to the end will appear. If a Debug break occurs during the evaluation, the Logic trail will appear together with the Variable context state in the Debug view, displaying the trail up to the break.

The Logic trail starts out at a high-level view, displaying sections representing the evaluated Steps of the Flow. Each Step section's header tells the amount of time it took to evaluate that Step and the amount of command evaluations that occurred within, as well as the amount of failed evaluations if there are such. To see the command evaluations of a Step, click its "Show contents" button - a view like the one below appears.    

Each evaluated command has its own grey line telling the command's name, its system-generated ID and the amount of milliseconds it took to evaluate the command. The ID might look somewhat confusing, but its there to aid in finding the same command evaluation again on another run of the logic. These IDs are automatically generated based on the Step and how many commands have been evaluated during that Step so far, so the IDs will be the same between runs if the Flow remains structurally unchanged and keeps taking the same path.

The command evaluation lines appear in the order in which the commands were evaluated in, the first command being at the top. The lines are indented if the commands are evaluated as children of other commands, and further indented if they're child commands of other child commands. As the parent command's evaluation always starts before its children, the line directly preceding indented lines is always the evaluation of the parent command. For parent commands, the evaluation time including the evaluation times of all the child commands is presented in addition to the command's own time.  

Within the Step sections there may also be subsections representing other evaluation processes occurring within the Flow's evaluation process. A common example of this is the evaluation of a HTML document resource done by a composeContent command. The title of the subsection indicates what this evaluation is for - in the case of HTML documents it is the path of the resource within the template. The command just above the subsection is most likely to be the one causing the evaluation to happen, and so its evaluation time includes the time it took to do the entire other evaluation process. Also note that the sequential number that is a part of each system-generated evaluation ID starts from zero within each of the other evaluation processes, as they are their own unique processes despite being inside the main Flow evaluation.  

To see more information of a particular evaluation, click the square on the left of its name to open up the details view. If a line does not have this clickable square, there's nothing to show in the details view - some command evaluations can be simple like that. The details view displays two kinds of information:

  • All of the command's attributes that have defined values are shown. Attributes that are EL-resolved display the expression as well as the value the expression resolved into. Should the resolved value be of a type that has properties or contains other values, the value may opened up to display its contents as well.
  • If the command produced one or more variables, these are displayed under the "Produced variable(s)" heading. The variable's value may also be inspected in a similar manner to other values in the debug view.

Below is an example of a query command retrieving some records from Salesforce, with one of the Data items representing the query results opened up for inspection.  

The Logic trail also provides a more descriptive view into command errors. Every command whose evaluation didn't finish successfully due to an error has its line darkened and marked with "Evaluation unsuccessful". Opening up the details will display the error message above the attribute values. In the image below a Salesforce record command produces an error as it is querying a record of an unknown object type, causing Salesforce to return an error response which the record command then passes forward.  

The evaluation of any of the EL-evaluated attributes of a command may also end up in an error. Sometimes this leads to the entire command's evaluation failing, but sometimes not and the evaluation still finishes successfully - to some extent. A non-critical attribute evaluation error having occurred is communicated on the command's line and the details view specifies the error in the related attribute's "Resolved into" section. A common error is the "Unable to find variable 'X'", which occurs if the expression refers to a variable that has not been set by any of the preceding commands or isn't one of the automatically generated variables.