diff --git a/app/components/IntegrationsList.vue b/app/components/IntegrationsList.vue index 0b2e1dc0..3c619bf1 100644 --- a/app/components/IntegrationsList.vue +++ b/app/components/IntegrationsList.vue @@ -12,6 +12,12 @@ const integrations = [ to: '/guides/integrations/clay', logo: '/docs/img/clay.png', }, + { + title: 'Zapier', + description: 'Automate workflows between Directus and thousands of other apps using Zapier.', + to: '/guides/integrations/zapier', + logo: '/docs/img/zapier.png', + }, ]; diff --git a/content/guides/11.integrations/3.zapier/.navigation.yml b/content/guides/11.integrations/3.zapier/.navigation.yml new file mode 100644 index 00000000..51a90c35 --- /dev/null +++ b/content/guides/11.integrations/3.zapier/.navigation.yml @@ -0,0 +1,2 @@ +title: Zapier +headline: Zapier diff --git a/content/guides/11.integrations/3.zapier/0.index.md b/content/guides/11.integrations/3.zapier/0.index.md new file mode 100644 index 00000000..eb54b8c7 --- /dev/null +++ b/content/guides/11.integrations/3.zapier/0.index.md @@ -0,0 +1,74 @@ +--- +id: zapier-integration +title: Integration +description: Connect Directus with Zapier to automate workflows, sync data, and integrate your CMS with thousands of other apps using the Directus Zapier integration. +technologies: + - zapier +--- + +Connect your Directus instance with Zapier to automate workflows, sync data between systems, and build powerful integrations with 6,000+ apps. + +::callout{icon="heroicons-outline:rocket-launch"} +**Quick Start** + +1. **Connect your account**: In Zapier, search for "Directus" and connect your Directus URL and API token +2. **Create a Zap**: Use Directus triggers or actions in your workflows +3. **Start automating**: Connect Directus to thousands of other apps +:: + +## Available Integrations + +The Directus Zapier integration provides two main components: + +- **Directus Actions**: Perform CRUD operations on items, users, and files +- **Directus Triggers**: Automatically start Zaps when events occur in Directus + +## Getting Started + +### Connect Your Directus Account + +1. In Zapier, click **Create Zap** +2. Search for **"Directus"** in the trigger or action step +3. Click **Connect a new account** (or select an existing connection) +4. Enter: + - **Directus URL**: Your Directus instance URL (must start with `https://`) + - **Static Access Token**: Your Directus API token +5. Click **Yes, continue** to test the connection + +#### Getting Your API Token + +1. In Directus, go to **Users** +2. Select or create a user for Zapier integration +3. Open the user's detail page +4. Scroll to **Token** section +5. Click **Generate Token** +6. Copy the token and paste into Zapier +7. **Important**: Click the checkmark (✓) to save + +::callout{icon="material-symbols:info-outline"} +**Permissions** +
+**Admin Token (Recommended for Getting Started)** +
+Many operations, including creating webhooks for triggers, require Administrator permissions. Assign the Administrator role to the user for the easiest setup and full access to all collections and features. + +
+ +**Custom Role (For Production)** +
+For better security, create a custom role with specific permissions. This allows you to limit access to only the collections and operations your workflows need. The token inherits the user's role permissions, so you can lock down access while still allowing necessary operations. +:: + +## Documentation + +**[Working with Actions →](/guides/integrations/zapier/actions)** + +Perform operations on your Directus data: create, read, update, and delete items, users, and files. + +**[Using Triggers →](/guides/integrations/zapier/triggers)** + +Set up automated workflows that trigger when events happen in Directus. + +**[Advanced Features →](/guides/integrations/zapier/advanced)** + +Use raw request actions, advanced filtering, and custom API calls. diff --git a/content/guides/11.integrations/3.zapier/actions.md b/content/guides/11.integrations/3.zapier/actions.md new file mode 100644 index 00000000..77c36331 --- /dev/null +++ b/content/guides/11.integrations/3.zapier/actions.md @@ -0,0 +1,245 @@ +--- +id: zapier-actions +title: Actions +description: Complete guide for using Directus actions in Zapier workflows, including working with items, users, and files. +technologies: + - zapier +--- + +This guide covers how to use Directus actions in Zapier to perform operations on your Directus data when triggered by other apps. + +**[← Back to Zapier Integration](/guides/integrations/zapier)** + +## Using Directus Actions + +Directus actions perform operations in Directus when triggered by other apps. You can work with **Items**, **Users**, and **Files**. + +## Available Actions + +Quick reference of all available actions organized by operation type: + +| Operation | Action | Description | +|-----------|-------|-------------| +| **CREATE** | Items – Create | Create a new item in a collection | +| **CREATE** | Users – Invite | Send an invitation email to a new user | +| **CREATE** | Files – Upload | Upload a file from binary data | +| **CREATE** | Files – Import | Import a file from a URL | +| **CREATE** | Items – Update | Update an existing item | +| **CREATE** | Users – Update | Update an existing user | +| **CREATE** | Files – Update | Update file metadata | +| **CREATE** | Items – Delete | Permanently remove an item | +| **CREATE** | Users – Delete | Permanently remove a user | +| **CREATE** | Files – Delete | Permanently remove a file | +| **SEARCH** | Items – Search / List | Find items with optional filters | +| **SEARCH** | Users – Search / List | Find users with optional filters | +| **SEARCH** | Files – Search / List | Find files with optional filters | +| **RAW REQUEST** | Items – Raw Request | Full HTTP method control (POST, PATCH, DELETE) | +| **RAW REQUEST** | Users – Raw Request | Full HTTP method control (POST, PATCH, DELETE) | +| **RAW REQUEST** | Files – Raw Request | Full HTTP method control (PATCH, DELETE) | + +--- + +## Common Operations + +Most operations follow a similar pattern. Add **Directus** as an action step, select the operation, choose the collection (for items), and configure fields. + +### Create, Update, Delete + +These operations work similarly across all resources: + +- **Create**: Select operation → Choose Collection (Items only) → Fill in fields → Map data from previous steps as needed +- **Update**: Select operation → Choose Collection (Items only) → Enter ID → Update desired fields +- **Delete**: Select operation → Choose Collection (Items only) → Enter ID + +**Note for Items**: All item operations require selecting the **Collection** first. Fields are automatically shown based on your Directus collection structure. + +::callout{icon="material-symbols:warning-rounded" color="warning"} +**Permanent Deletion** +Delete operations permanently remove data. Make sure this is what you want to do! +:: + +### Search / List + +Select **Search / List** operation → Choose Collection (Items only) → Configure options: + +| Option | Description | +|--------|-------------| +| **File ID** / **Item ID** / **User ID** | Search by specific ID | +| **Fields** | Specify which fields to return (e.g., `id, title, size`) | +| **Maximum number of items to return** | Leave empty to return all matching items (up to 100 by default) | +| **Offset** | Number of records to skip | +| **Page** | Page number for pagination | +| **Sort** | Order results (e.g., `date_created DESC`) | +| **Search** | General search query across attributes | +| **Filter (JSON)** | Advanced filtering using Directus filter syntax | + +::callout{icon="material-symbols:warning-rounded" color="warning"} +**Processing Multiple Results** +
+By default, Zapier returns only the **first result** from Search / List actions. To process all returned results, you must configure **"If multiple search results are found"** in the action settings to **"Return all results as line items"**. This allows Zapier to process each result separately in subsequent steps. +:: + +**Note for Items**: Select the **Collection** before configuring options. + +::callout{icon="heroicons-outline:light-bulb"} +**Advanced Filtering in Search / List** +
+The **Filter (JSON)** field in Search / List actions supports Directus's complete filter syntax, including logical operators (`_and`, `_or`), relational field filtering, and all filter operators. For complete filter syntax and examples, see the [Directus Filter Rules documentation](https://directus.io/docs/guides/connect/filter-rules). +
+**Example: Complex filter** +```json +{ + "_and": [ + {"status": {"_eq": "published"}}, + { + "_or": [ + {"category": {"_eq": "tutorial"}}, + {"category": {"_eq": "guide"}} + ] + }, + {"views": {"_gt": 100}} + ] +} +``` +:: + +## Resource-Specific Operations + +### Items + +Items are content entries in your Directus collections (blog posts, products, pages, etc.). All operations require selecting a **Collection** first. + +::callout{icon="material-symbols:info-outline"} +**Dynamic Field Discovery** +Fields are automatically discovered from your Directus schema and shown in the action configuration. You can map data from previous steps using the dropdown menus. +:: + +### Users + +#### Users – Invite + +To create users, use **Users – Invite**. This sends an invitation email so the user can set their password. + +**Available options:** +- **Email** (required) +- **Role** (dropdown selection) +- **Custom Invite URL** (optional) + +::callout{icon="heroicons-outline:light-bulb"} +**Direct User Creation** +For direct user creation without invitation, use **Users – Raw Request** with POST method. +:: + +All other operations (Update, Delete, Search / List) follow the standard pattern above. + +### Files + +Files are images, documents, and other media stored in Directus. + +#### Files – Upload + +Upload a file from binary data in your Zap. + +**Available options:** +- **File** (required) - Binary file data from a previous step +- **Title** (optional) +- **Description** (optional) +- **Folder** (optional) + +::callout{icon="material-symbols:info-outline"} +**File Data Source** +The file must come from a previous step that provides binary file data (like downloading a file from a URL or getting a file from another app). +:: + +#### Files – Import + +Import a file from a publicly accessible URL. + +**Available options:** +- **File URL** (required) - Must be publicly accessible +- **Title** (optional) +- **Description** (optional) +- **Folder** (optional) + +::callout{icon="heroicons-outline:light-bulb"} +**Upload vs Import** +Use **Upload** when you have binary file data from a previous step. Use **Import** when you have a publicly accessible URL to the file. +:: + +All other operations (Update, Delete, Search / List) follow the standard pattern above. + +--- + +## Tips and Best Practices + +### Relationship Fields + +**Fields with Dropdown Selection:** + +**Many-to-One (M2O) fields** (like selecting an author for a post or a form for a block) support dropdown selection. You +can select an item from the dropdown or enter a UUID directly. The dropdown works for all collections, including custom +collections. + +**File fields (single)** support dropdown selection. Select a file from the dropdown or enter a file UUID. Upload files +first using the **Files – Upload** or **Files – Import** actions if needed. + +**User fields** support dropdown selection. Select a user from the dropdown or enter a user UUID. + +**Fields Requiring Text Input:** + +**One-to-Many (O2M) fields** (like buttons in a button group) require comma-separated item IDs. For example: +`uuid-1, uuid-2, uuid-3`. Use the **Search Items** action to find the IDs you need. + +**Many-to-Many (M2M) fields** require comma-separated item IDs. For example: `uuid-1, uuid-2, uuid-3`. Use the **Search +Items** action to find the IDs you need. + +**Many-to-Any (M2A) fields** (like page builder blocks) require `collection:id` pairs separated by commas. For example: +`block_hero:uuid-1, block_text:uuid-2, block_gallery:uuid-3`. This lets you specify both which collection and which item +to link. + +**Multiple files (gallery) fields** support dropdown selection for single selection only (due to a Zapier platform +limitation). For multiple files, enter comma-separated file UUIDs: `file-uuid-1, file-uuid-2`. Upload files first using +the **Files – Upload** or **Files – Import** actions. + +All inputs are automatically converted to the proper JSON format for Directus. For advanced relational operations (like +creating nested items inline), use the **Raw Request** action. See the +[Advanced Features](/guides/integrations/zapier/advanced) guide for examples. + + +### File Fields in Items + +When creating or updating items with file/image fields, first upload or import the file using a **File** action, then use the returned **File ID** in your item creation/update. File fields require the UUID of an existing file, not file uploads directly. + + +### Testing Your Zaps + +Always test your Zap before turning it on. Click **Test** on each step to verify data flows correctly and field mappings are correct. + +--- + +## Troubleshooting + +When working with Directus API through Zapier, you may encounter various error codes. For a comprehensive list of Directus error codes and their meanings, refer to the [official Directus Error Codes documentation](https://directus.io/docs/guides/connect/errors). + +### Error Handling + +If you get errors: + +1. **Permission Errors**: Check that your Directus API token has the right permissions +2. **Not Found Errors**: Verify that the collection, item ID, or user ID exists +3. **Connection Errors**: Make sure your Directus URL is correct and accessible (must include `https://`, no trailing slash) + +### Getting Help + +If you encounter issues: + +1. **For Directus-specific questions:** Ask for help in the [Directus Community](https://community.directus.io/) +2. **For Zapier-specific questions:** Visit the [Zapier Community](https://community.zapier.com) or check [Zapier Help Center](https://help.zapier.com/) +3. **For API connection issues:** Verify your Directus configuration and permissions + +--- + +## Next Steps + +- **[← Back to Integration](/guides/integrations/zapier)** Return to the integration overview +- **[Learn about Triggers →](/guides/integrations/zapier/triggers)** Set up automated workflows diff --git a/content/guides/11.integrations/3.zapier/advanced.md b/content/guides/11.integrations/3.zapier/advanced.md new file mode 100644 index 00000000..b1965e5d --- /dev/null +++ b/content/guides/11.integrations/3.zapier/advanced.md @@ -0,0 +1,190 @@ +--- +id: zapier-advanced +title: Advanced +description: Advanced guide for using Directus API features in Zapier, including raw request actions, advanced filtering, and custom API calls. +technologies: + - zapier +--- + +This guide covers advanced Directus features in Zapier, including raw request actions and advanced filtering in Search / List actions. + +**[← Back to Zapier Integration](/guides/integrations/zapier)** + +## Raw Request Actions + +Raw Request actions provide full HTTP method control for Items, Users, and Files. These actions allow you to use Directus's native JSON syntax for filters, query parameters, and data manipulation. + +## Available Raw Request Actions + +Quick reference of all available raw request actions: + +| Resource | Operation | HTTP Methods | Description | +|----------|-----------|--------------|-------------| +| **Items** | Raw Request | POST, PATCH, DELETE | Full HTTP method control for items | +| **Users** | Raw Request | POST, PATCH, DELETE | Full HTTP method control for users | +| **Files** | Raw Request | PATCH, DELETE | Full HTTP method control for files | + +--- + +::callout{icon="heroicons-outline:light-bulb"} +**When to Use Raw Request Actions** +Use raw request actions when you need full control over HTTP methods, complex query parameters (aggregation, search, etc.), or complete control over the JSON payload structure. For advanced filtering in Search / List actions, use the Filter (JSON) field instead. +:: + +## Using Raw Request Actions + +Raw Request actions allow you to make custom Directus API calls with full control over the HTTP method and request body. + +### Setting Up a Raw Request Action + +1. Add **Directus** as an action step +2. Select **Raw Request** operation (Items, Users, or Files) +3. Choose the **HTTP Method** (POST, PATCH, or DELETE) +4. For Items, select the **Collection** +5. Configure the request: + - **ID**: Item/User/File ID (required for PATCH/DELETE) + - **Request Body (JSON)**: JSON data for POST/PATCH requests + - **Filter (JSON)**: Filter conditions for DELETE operations + +::callout{icon="material-symbols:warning-rounded" color="warning"} +**Token Permissions** +Ensure your Directus API token has the correct permissions for the resource and operations you're using. Raw request actions require the same permissions as their standard counterparts. +:: + +### Items - Raw Request + +**POST** - Create items with full JSON control: +```json +{ + "title": "My New Post", + "content": "Post content here", + "status": "published", + "author": "author-uuid-here", + "categories": ["category-uuid-1", "category-uuid-2"] +} +``` + +**PATCH** - Update items with complex data structures: +```json +{ + "title": "Updated Title", + "status": "archived", + "metadata": { + "tags": ["updated", "archived"], + "notes": "Item has been archived" + } +} +``` + +**DELETE** - Delete items by ID or using Filter (JSON) for bulk deletion + +### Users - Raw Request + +**POST** - Create users with full JSON control: +```json +{ + "email": "user@example.com", + "first_name": "John", + "last_name": "Doe", + "role": "role-uuid-here" +} +``` + +**PATCH** - Update users with complex data structures: +```json +{ + "status": "suspended", + "metadata": { + "reason": "Account violation" + } +} +``` + +**DELETE** - Delete users by ID or using Filter (JSON) for bulk deletion + +### Files - Raw Request + +**PATCH** - Update file metadata with complex data structures: +```json +{ + "title": "Updated Title", + "description": "New description", + "tags": ["tag1", "tag2"] +} +``` + +**DELETE** - Delete files by ID or using Filter (JSON) for bulk deletion + +## Working with Relations + +When using **Raw Request** actions or creating items with relations: + +**Many-to-One:** +```json +{ + "title": "My Post", + "author": "author-uuid-here" +} +``` + +**Many-to-Many:** +```json +{ + "title": "My Post", + "categories": ["category-uuid-1", "category-uuid-2"] +} +``` + +**One-to-Many:** +```json +{ + "title": "My Post", + "comments": [ + {"text": "Great post!", "user": "user-uuid-here"} + ] +} +``` + +## Advanced Tips + +### Using Dynamic Values in Filters + +You can use data from previous steps in your filters by using Zapier's field mapping in the filter fields. + +### Batch Processing + +For bulk operations: +1. Use **Search / List** to get all items +2. Enable **"Return all results as line items"** +3. Add a **Filter** step if needed +4. Add **Update Item** to process each item + +## Performance Tips + +- **Select only needed fields**: Use field mapping to reduce data transfer +- **Use pagination**: Use the **Limit** field in search actions, process in batches +- **Filter in Directus**: Always use Directus filters rather than Filter steps when possible + +**Example:** +```json +{ + "filter": { + "status": {"_eq": "published"}, + "date_created": {"_gte": "$NOW(-30 days)"} + }, + "limit": 100 +} +``` + +--- + +## Next Steps + +- **[← Back to Integration](/guides/integrations/zapier)** Return to the integration overview +- **[Learn about Actions →](/guides/integrations/zapier/actions)** Basic operations guide +- **[Learn about Triggers →](/guides/integrations/zapier/triggers)** Automation workflows + +## Additional Resources + +- [Directus Filter Rules](https://directus.io/docs/guides/connect/filter-rules) - Complete filter syntax and operators +- [Directus Query Parameters](https://directus.io/docs/guides/connect/query-parameters) - All available query parameters diff --git a/content/guides/11.integrations/3.zapier/triggers.md b/content/guides/11.integrations/3.zapier/triggers.md new file mode 100644 index 00000000..832667f0 --- /dev/null +++ b/content/guides/11.integrations/3.zapier/triggers.md @@ -0,0 +1,116 @@ +--- +id: zapier-triggers +title: Triggers +description: Complete guide for using Directus triggers in Zapier workflows to automatically start Zaps when events happen in Directus. +technologies: + - zapier +--- + +This guide covers how to use Directus triggers in Zapier to automatically start your Zaps when something happens in Directus. + +**[← Back to Zapier Integration](/guides/integrations/zapier)** + +## Using Directus Triggers + +Directus triggers automatically start your Zaps when events happen in Directus. + +## Available Triggers + +Quick reference of all available triggers organized by resource type: + +| Resource | Event | Description | +|----------|-------|-------------| +| **Items** | Created | Triggers when a new item is added to a collection | +| **Items** | Updated | Triggers when an existing item is modified | +| **Items** | Deleted | Triggers when an item is removed from a collection | +| **Users** | Created | Triggers when a new user is added | +| **Users** | Updated | Triggers when a user is modified | +| **Users** | Deleted | Triggers when a user is removed | +| **Files** | Uploaded | Triggers when a file is uploaded to Directus | + +--- + +## Setting Up a Trigger + +1. In your Zap, select **Directus** as the trigger app +2. Choose the trigger event: + - **New or Updated Item**: Select the **Collection** to watch, then choose the **Action** (Created, Updated, or Deleted) + - **New or Updated User**: Choose the **Action** (Created, Updated, or Deleted) + - **New File Uploaded**: No additional configuration needed +3. Click **Continue** and test the trigger + +The trigger automatically creates a Flow in Directus with a webhook that starts your Zap when the selected event occurs. + +### How Triggers Work + +When you set up a Directus trigger in Zapier: + +1. Zapier automatically creates a Flow with a webhook in your Directus instance +2. Directus sends notifications to Zapier when the selected event happens +3. Your Zap runs automatically with the data from Directus +4. When you turn off your Zap, the Flow and webhook are automatically removed + +--- + +## Tips and Best Practices + +### Using Trigger Data + +You can use data from the trigger in subsequent steps. The trigger data contains the full item, user, or file object that triggered the Zap: + +- Map fields from the trigger to actions in other apps +- Use the search box to quickly find the field you need +- All data from the trigger is available in subsequent steps + +### Filtering Trigger Events + +You can add Filter steps after the trigger to only process specific events: + +- Check if `status` equals `published` before sending notifications +- Filter by collection or field values +- Only process certain types of files + +::callout{icon="material-symbols:info-outline"} +**Filtering Tip** +Use Zapier's **Filter** step after the trigger to add conditional logic. For example, only send notifications when `status` equals `"published"`. +:: + +--- + +## Troubleshooting + +### Trigger Issues + +**Triggers Not Firing:** + +- Ensure your Zap is turned on +- Verify the trigger is set up correctly (right collection, right action) +- Check that your Directus flows are active (the integration creates these automatically) +- Ensure your Directus instance can reach Zapier's webhook URLs +- Test by manually creating/updating an item in Directus +- Check Directus logs for any errors + +**Webhook Not Created:** + +- Verify your Directus API token has permission to create webhooks +- Ensure your Directus instance is accessible from the internet + +**Connection Issues:** + +- Make sure your Directus URL is correct and accessible (must include `https://`, no trailing slash) +- Verify your API token is valid and has the right permissions + +### Getting Help + +If you encounter issues: + +1. **For Directus-specific questions:** Ask for help in the [Directus Community](https://community.directus.io/) +2. **For Zapier-specific questions:** Visit the [Zapier Community](https://community.zapier.com) or check [Zapier Help Center](https://help.zapier.com/) +3. **For trigger issues:** Check that both your Directus and Zapier instances are accessible + +--- + +## Next Steps + +- **[← Back to Integration](/guides/integrations/zapier)** Return to the integration overview +- **[Learn about Actions →](/guides/integrations/zapier/actions)** Perform operations on your Directus data diff --git a/public/img/tutorials/n8n.png b/public/img/tutorials/n8n.png new file mode 100644 index 00000000..0c27e382 Binary files /dev/null and b/public/img/tutorials/n8n.png differ diff --git a/public/img/tutorials/zapier.png b/public/img/tutorials/zapier.png new file mode 100644 index 00000000..4758c624 Binary files /dev/null and b/public/img/tutorials/zapier.png differ diff --git a/public/img/zapier.png b/public/img/zapier.png new file mode 100644 index 00000000..4758c624 Binary files /dev/null and b/public/img/zapier.png differ