Workflow Debugger

Q & A for v.1 

Q. While I am heavily using Magnus - I am not technical person. Can you guide me how to start using Magnus Debugger and what are the main features here? Any best practices to follow? 

A. The Magnus Workflow Debugger allows you to run a workflow while stepping through and watching each task run, inspecting the various task and parameter values, and pausing at specific tasks or parameter changes. This can be helpful during the development of workflow logic, where not all runtime values and logic are known yet. To quickly jump in and get started, see the key features and quick overview below.

Q. How can I quickly jump into debugging a workflow?
A. Key features and quick overview:

1. Start Debugger: press the green play icon in the Debug View panel.
   The debugger will load up the workflow and pause execution before the first task in the workflow.
2. Breakpoints: click the left margin next to a task in the Debug View to enable a breakpoint on that task.
   This will cause the workflow to pause just before running that task.
3. Debug View – Current Task: the current task has a red outline. Dimmed while running, or a solid outline while paused waiting for debug instructions.
4. Debugger Controls toolbox:
   1. Continue – continue running the workflow in the debugger (F8)
   2. Pause – pause the workflow in the debugger at the next possible stopping point. This can take a while depending on the task.
   3. Step Over Task – run the next task at the current level; if the next task has nested tasks, all the nested tasks are also run (F10)
   4. Step Into Task – run the next task, stepping into nested tasks if applicable (F11)
   5. Step Out of Task – run the rest of the tasks at the current level (e.g. finish executing the body of a loop) (Shift+F11)
   6. Stop – stop debugging, the workflow is killed if it has not yet finished.
5. Runtime Parameters panel: view all the workflow parameters, updated in real-time as the workflow runs in the debugger. Recently changed parameters are highlighted in yellow.
6. Run Details panel: workflow run detailed information is populated in real-time.
7. Watch List panel: watch parameter updates and script evaluation, see the Watch List section below. Recently changed watch results are highlighted in yellow.
8. Runtime Output panel: raw workflow output, although the Run Details panel has more easily consumable information.
9. Panel control buttons: minimize/restore the panels and reset their sizes and positions back to their defaults.
   
   

Q. I am an experienced software developer and use debugging technique in my day-on-day life. Obviously, I have greater expectations of off debugging process/features. What is special (if any) about Magnus Debugger that I need to know?

A. The Magnus workflow debugger allows you to debug your workflows right in the workflow editor on live data. Debugging is currently done on the task level, which means each step runs the whole task, and breakpoints happen between tasks. Some common features from other debuggers can be found, such as breakpoints and watching values change in real-time, however stepping into individual lines of code or sub-tasks is not currently in scope. Also see the limitations and v2 backlog below.

Q. What are (if any) known potential issues and how to handle them? 
A. While the workflow is being debugged (running in workflow debugger) …

1. The workflow is generally prevented from running via other means. In other words, it blocks it from running on schedule or other means (workflow task, remote API, manual, trigger, etc.)
2. The actual workflow logic is executing, which can leave things (such as in a production workflow) in bad state if not carefully considered. e.g. stopping a workflow before it has finished can leave that logic partially executed, and the next run of the workflow may not know how to handle that situation (though a workflow should ideally be resilient in that case, it can still be less than ideal)
3. The workflow debugger can time out if it is not being used actively, which can kill the workflow before completion.
   
   

Q. What are limits, limitations? 

A. List:

1. Idle timeout: 15 minutes
   The debugged workflow is killed if the debugger is not being used.
2. Max duration of debugged workflow: 2 hours
   The debugged workflow is killed if it takes longer than reasonable to debug.
3. Cannot step into task internals / subtasks
4. Cannot step into or use breakpoints on script task’s script lines of code
5. Cannot step into or use breakpoints on workflow task’s child workflow
   (Can only debug the currently loaded workflow, not any other workflows that are started)
6. Cannot step into or use breakpoints on tasks nested within an async loop (loop task with Async Mode enabled)
   
   

Q. What is the Watch List?

A. The Watch List allows you to watch values in real-time as they are updated by the workflow, similar to viewing the message in a Misc Task or viewing the return value of a Script Task, and optionally break (pause) the workflow when the value changes. Features:

1. Watch a value similar to the message in a Misc Task – use normal parameter substitution. Examples:
   1. Watch: The <var_name> has <var_count> <var_object>s
      Result: The Salad has 7 Ingredients
2. Watch a value similar to the return value of a Script Task – prefix with an equal sign (“=”) followed by a JavaScript expression (allows parameter substitution). Examples:
   1. Watch: = :var_x * 2
      Result: 8
   2. Watch: = :var_iterationId >= 5
      Result: true
3. Pause workflow execution on change. Check the Break column of a watch entry, and the workflow will pause execution each time the result changes. Examples:
   1. Watch: = :var_iterationId >= 5
      Break: when the loop’s iteration ID hits 5.
4. Use the Unwatch All trash icon to clear the watch list.

Q. What to expect next (in v2)? 

A. possible new features which are being considered (note that this list is not finalized, and features may be added or removed before v2 is completed; please let us know if any sound more useful to you)

1. View more parameter information: record types, source of data.
2. Update parameters, adhoc setting of parameters.
3. Replay functionality: go back to previous task, start over from beginning, step through and inspect already executed workflow.
4. Send your suggestions!