How to retrieve actions in Zoho

Retrieving actions in Zoho involves iterating over a structured plan's action list and executing each tool call in sequence, with the system automatically handling read-only versus write permissions along the way.

Why this matters

When you build automations or AI-assisted workflows on top of Zoho, your integration needs to reliably fetch and execute the correct sequence of actions from a plan object. Understanding how the retrieval and execution pipeline works helps you debug failed steps, handle clarifying questions gracefully, and ensure your connection credentials are valid before any tool is called.

Step-by-step

Step 1. Confirm your Zoho connection is active before attempting to retrieve or run any actions. The system calls getzohoapi with your userid and apptype to obtain a live API handle and connection metadata. If no valid connection is returned, the pipeline halts immediately and surfaces a reconnection error to the caller. ^[2]

Step 2. Parse the plan object to access its actions list. The plan is stored as JSON (commonly referred to as plan_json), and you retrieve the list with plan.get("actions"). If the JSON is malformed or the list is absent, the system logs the failure and returns an "Invalid plan" error — so always validate your plan payload before proceeding. ^[4]

Step 3. Iterate over each action in the list. Every action entry carries at minimum a tool key (the name of the Zoho tool to invoke) and a params dictionary containing the arguments for that tool. Loop through the list and extract both values for each step. ^[1]

Step 4. Validate each tool call before execution. For every action, call validatetoolcall with the apptype, the tool name, and its params. This returns a permission level — either "read" or something else. If every action in the plan resolves to "read" permission, the entire plan is classified as read-only and can be executed immediately without a separate approval step. If any action lacks "read" permission, the allread_only flag is set to False and the plan requires explicit user confirmation before applying. ^[5]

Step 5. Execute each action using executetoolwithrepair. Pass in the api handle, apptype, tool name, and params. For read-only tools, set allowrepair=True so the system can automatically retry with corrected parameters if the first attempt fails. The function returns an execout dictionary containing the result, and optionally a clarifyingquestion if the tool needs more information from the user. ^[3]

Step 6. Check the output of each execution. If execout.get("clarifyingquestion") is populated, pause the action loop, surface the question to the user, and record it in your chat messages store before releasing any concurrency locks. If the result is a dictionary containing an "error" key, capture that error message for display. Otherwise, treat the action as successfully completed. ^[2]

Step 7. After a successful execution, build contextual links to the affected records using buildzoholinks. Supply the result, the resolved tool name (execout.get("tool") or tool), the resolved params, apptype, the data-centre code (dc), and any org/portal identifiers from the connection metadata (crmorgid, deskorgid, desk_portal). These links let users navigate directly to the records that were read or modified. ^[8]

Step 8. For browser-based tools (such as browsernavigateandscreenshot for inspecting Zoho admin pages), the execution path is slightly different. The BROWSERTOOLREGISTRY is checked first to confirm the tool exists, then required params are validated, and finally the browser session's authentication status is verified. If the session has expired, the system returns an actionrequired field instructing you to re-authenticate via the browser login endpoint. ^[7]

Common pitfalls

• Missing Zoho connection: If getzohoapi returns nothing, no actions will execute. Always verify the connection is established and the correct app_type is specified before triggering a plan. ^[4]
• Invalid plan JSON: A malformed plan_json string causes the entire apply operation to abort. The system logs a sample of the bad payload (up to 200 characters) to help with debugging. ^[4]
• Exceeding the action count limit: The system checks planactioncount against Config.MAXPLANACTIONS when the workflow engine enforcement flag is active. Plans with too many actions may be denied before any tool is called. ^[4]
• Browser session expiry: For browser-based tool calls, an expired or unauthenticated session returns an error rather than silently failing — watch for the "action_required" key in the response. ^[7]
• Non-read-only actions in streaming mode: In the streaming plan endpoint, read-only plans execute inline with a live status feed. Plans containing write actions are returned to the client as a pending plan payload instead, requiring a separate apply step. ^[5]

What to check

• Confirm that getzohoapi returns a valid API handle and that the dc (data-centre) value in the connection metadata matches your Zoho account's region.
• Verify that every action's tool key matches a registered tool name and that all REQUIRED params are present before submitting the plan.
• After execution, inspect the status field on each result — look for "success" versus "error" — and confirm that buildzoholinks returns navigable record URLs for any affected data. ^[3][8]

---

*Beam Help provides independent expert support for Zoho and is not official Zoho support. Always test plan execution in a sandbox environment before applying changes to production data.*