Docs / Workflows / Actions / Integration action
Integration action
Run one action in a connected service, such as reading an issue, sending an email or uploading a file.
Actions from integrations
A job runs one action. The action is either built in, such as an LLM call or an Agent, or it comes from an integration, such as Gmail’s Create Draft. An integration is a connected account. It gives your jobs the events that can start them, the actions they can run and the tools an Agent can call.
Each integration’s actions are either read actions, which look things up, or write actions, which change something. The integration’s own page lists every one of them.
Connection and action
A standalone integration action selects a connected account and one supported action. For example, a Slack connection identifies the workspace and Send Message identifies the operation. The connection supplies authentication. The action’s input fields supply the channel, message and other required values.
Read actions retrieve data. Write actions change data or perform an external action. The provider catalogue determines this classification. Supabase’s Execute SQL is a write action even when its SQL happens to contain SELECT, because it can also change the database.
Inputs and output
Input fields can contain fixed values or references such as {{ properties.reply }}. A whole-value reference preserves its JSON type. Text around the reference produces a string. The selected action defines which inputs are required and which output fields it returns.
For example, Send Message can take a fixed Slack channel and text from an incoming reply property. Map its returned channel and timestamp values into the job’s output event when later jobs need to identify that message.
Action results are available under action.*. They are separate from the original event’s properties. Download actions can also attach files to the output event. A successful send can confirm that a provider accepted a message without confirming that the recipient received or read it.
Use integrations in Agent and Code
- Standalone action
- Runs the selected operation once with inputs configured on the job. Use this when the required action is already known.
- Agent tool
- Offers selected connection/action pairs to a model. The model chooses when to call those tools and supplies their arguments as it works.
- Code SDK call
- Calls a provider tool from Python through the OAIZ SDK. The Code job’s allowed integrations list selects the connections and action types the script can call. A connection with an empty action-types list allows no calls.
The same provider action is available to a standalone job, an Agent and Python code. Its inputs and returned values stay the same. The provider reference explains each supported action.
Tool permissions
A connection share can grant all tools or selected tools. The Read only option selects the provider’s current read-tool list. Individual tool selection can include reads and writes, but a write tool also needs an Edit or Owner share. These restrictions govern the person’s interactive use of the connection.
A job’s integration calls follow the grants of its job account, not the share of the person who configured it. Agent and Code jobs also limit integration calls to their selected tools.
Read and write effects in tests
Integration reads and writes have separate run permissions. Tests normally allow reads and disable writes. Disabled operations return example results instead of performing the provider operation. Enabling writes permits real sends, updates and deletions.
Turning off event publication does not by itself turn off an integration operation. It controls whether the job’s output event is published. A test with writes enabled can change a connected service even when its output stays unpublished.