Amazon Connect contact flows and Twilio studio flows are designed to be user-friendly. However, clients often have trouble understanding flows because long widget text is truncated, unessential technical detail is not filtered out, and transition arrows often overlap or are obscured behind widgets.
IVR-to-Flowchart Tool
The IVR-to-Flowchart tool generates flowcharts to present a high-level overview of flows to clients.
How it all works
The tool uses JavaScript and Mermaid which is a charting language. It parses flows in JSON format, converts them to strings of Mermaid code, and writes those strings to a file in HTML and Markdown format. The tool is triggered via the command line, and it can receive JSON flow from exported files or via Connect and Twilio APIs. It also allows users to select what flows to convert and the flowcharts can be previewed and exported as PDF, PNG, or SVG, or they can be printed.
Description of Features
Each flowchart section is indicated as follows:
- Error transitions – red lines
- Long ARNs and SIDs – excluded to reduce clutter
- Handoffs to outside processes like queues and function invocations – dotted lines
Widget types are distinguished by the following node shapes:
- Terminal widget – stadium shape
- Connector – a circle
- Data storage – cylinder
- Decision – rhombus
- Setting logging or recording behavior – rectangle
- Outputting a message to the participant – a rectangle with rounded edges
Node shapes were chosen based on common flowchart symbols and their associated meanings.
How the Tool Works
Settings are configured via an .env file. Also, you can configure whether to import from a file or via API and whether the flows are from Amazon Connect or Twilio.
When reading Amazon Connect flows from a file, the JSON object must be exported from the new user interface released in September 2022 because the JSON object is formatted differently than the old user interface. To trigger the tool, run npm run ivr2f in the command line from within the project directory.
How to Use the Output
The Markdown Preview Mermaid Support VS Code extension can be used to render quick previews of the flows in Markdown format. Flows in HTML format can be served using the Live Server VS Code extension and saved in PDF or printed format. Flowcharts can be saved in the PNG or SVG format by screenshotting or pasting Mermaid code into Mermaid’s Live Editor and exporting the flow.
Design Choices and Implementation
Mermaid offered the convenience of a prebuilt charting language with a sleek appearance; however, this posed a few challenges. There is no built-in text wrapping, so text wrap had to be manually implemented by placing <br> tags in the correct positions throughout the text. Reserved characters in Mermaid like quotes and parentheses had to be removed from the widgets’ content before adding them to the flowchart. Additionally, Mermaid offers limited customizability, so text size and node positioning are not optimized for readability in every flowchart. In retrospect, I would have looked for a charting tool with more customizability; mxGraph may be a promising alternative.
Conclusion
The IVR-to-Flowchart tool is a useful tool that simplifies complicated contact flows for clients and the flowcharts can be previewed and exported in different formats. The tool uses JavaScript and Mermaid, a charting language, to parse JSON flow and convert it into a string of Mermaid code. The tool’s different node shapes and line styles make it easy to distinguish different widget types and flowchart sections.
