Hook
Documenting Domo Magic ETL dataflows is nobody's idea of a good time — but an undocumented dataflow is a maintenance nightmare. What if your chatbot could read the dataflow definition and write the description for you?
Why It Matters
Dataflow definitions live as dense JSON blobs full of noise — version metadata, execution history, internal IDs — that obscure the actual transformation logic. Manually summarizing them doesn't scale, and most teams skip it entirely. By wiring the Domo Dataflow API to an LLM with a purpose-built prompt, you get accurate, plain-English descriptions generated on demand. This also sets the pattern for any tool call where you need to reduce a structured API response to something a language model can reason about cleanly.
What You'll Learn
- Query the Domo Dataflows API by ID and extract the
actionsarray from the raw response - Write a
process_dataflow_definitionfunction that strips irrelevant fields and returns a clean dictionary for LLM consumption - Craft a system prompt that roles the LLM as a "senior Domo ETL engineer" to translate JSON into plain-English transformation summaries
- Wire an endpoint handler (
llm_describe_dataflow) that accepts a dataflow ID and returns a structured description - Understand why reducing the JSON payload before passing to the LLM matters for accuracy and token efficiency
From Raw API Response to Human-Readable Description
The core insight here is payload reduction. The Dataflow API returns a lot — version numbers, execution history, internal flags — most of which is useless context for a language model trying to describe what the dataflow does. The process_dataflow_definition function does the heavy lifting: it extracts only id, name, and actions from the API response and packages them into a clean dictionary before anything touches the LLM.
The system prompt is equally deliberate. Rather than a generic assistant, the model is prompted as a senior Domo ETL engineer whose job is to translate JSON transformation definitions into readable process descriptions. This keeps outputs consistent and appropriately technical — not a summary for a business user, but a concise description a data engineer would recognize.
The endpoint handler llm_describe_dataflow ties it together: pass in a dataflow ID (e.g., 12 for the Domo Governance dataflow used in the demo), get back a structured description via generate_content. The response is serialized directly to JSON via messages.m.to_json() — no dataframe gymnastics needed at this stage.
What makes this pattern reusable is the separation of concerns: API extraction, payload normalization, prompt engineering, and LLM invocation are each discrete steps. Swap out the Dataflow API for any other Domo API — datasets, cards, alerts — and the same skeleton applies.
