From 779baca7ebbab80f59fa2515515daaad61229849 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Tue, 19 May 2026 13:38:47 +0200 Subject: [PATCH 1/4] docs(integrations): rewrite Actor-to-Actor integration page Refresh the Add an integration flow to match the new integrations dialog in Apify Console. The previous instructions referenced a removed "Apify (Connect Actor or Task)" affordance. Several TODOs remain inline for items that still need confirmation. Refs #2460 Co-Authored-By: Claude Opus 4.7 (1M context) --- sources/platform/integrations/actors/index.md | 47 +++++++++++-------- 1 file changed, 28 insertions(+), 19 deletions(-) diff --git a/sources/platform/integrations/actors/index.md b/sources/platform/integrations/actors/index.md index 5d3aeea41f..e416ce2d65 100644 --- a/sources/platform/integrations/actors/index.md +++ b/sources/platform/integrations/actors/index.md @@ -1,6 +1,6 @@ --- title: What are Actor integrations? -description: Learn how to connect Actors together and trigger tasks from other Actors, enabling you to build automated multi-step workflows on the Apify platform. +description: Learn how to connect Actors and tasks on the Apify platform using the integrations catalog in Apify Console to build automated multi-step workflows. sidebar_label: Actor-to-Actor sidebar_position: 0 slug: /integrations/actors @@ -12,44 +12,53 @@ You can check out a catalog of Integration Actors within [Apify Store](https://a ::: -Actor integrations provide a way to connect your Actors with other Actors or tasks easily. They provide a new level of flexibility, as adding a new integration simply means creating [integration-ready Actors](/platform/integrations/actors/integration-ready-actors). Thus, new integrations can be created by the community itself. +Actor integrations connect your Actors with other Actors or tasks, letting you build multi-step workflows on the Apify platform. Because any [integration-ready Actor](/platform/integrations/actors/integration-ready-actors) can act as the target of an integration, the community can keep extending the catalog with new integrations. + -## How to integrate an Actor with other Actors? +## Add an integration -To integrate one Actor with another: +To connect an Actor with another Actor or task: -1. Navigate to the **Integrations** tab in the Actor's detail page. -2. Select `Apify (Connect Actor or Task)`. -![Add integration](./images/integrations_add.png) -3. Find the Actor or task you want to integrate with and click `Connect`. +1. Open the Actor's detail page and select the **Integrations** tab. + - If the Actor already has integrations set up, the **Integrations** tab lists them instead. Click **Add integration** to open the catalog. +1. In the **Add integration** catalog, find the target Actor in one of two places: + - **Suggested for this Actor** - Actors relevant to the source Actor's output. + - **Search integrations** field at the top - search across the full catalog. +1. Click the Actor card to open its setup screen. -This leads you to a setup screen, where you can provide: + -- **Triggers**: Events that will trigger the integrated Actor. These are the same as webhook [event types](/platform/integrations/webhooks/events) (*run succeeded*, *build failed*, etc.) +On the setup screen, configure: -![Integration trigger select](./images/integration_triggers.png) +- **Triggers** - Events that fire the integrated Actor. These match webhook [event types](/platform/integrations/webhooks/events) (`run succeeded`, `build failed`, and so on). -- **Input for the integrated Actor**: Typically, the input has two parts. The information that is independent of the run triggering it and information that is specific for that run. The "independent" information (e.g. connection string to database or table name) can be added to the input as is. The information specific to the run (e.g. dataset ID) is either obtained from the implicit `payload` field (this is the case for most Actors that are integration-ready), or they can be provided using variables. -- **Available variables** are the same ones as in webhooks. The one that you probably are going to need the most is `{{resource}}`, which is the Run object in the same shape you get from the [API](/api/v2/actor-run-get) (for build event types, it will be the Build object). The variables can make use of dot notation, so you will most likely just need `{{resource.defaultDatasetId}}` or `{{resource.defaultKeyValueStoreId}}`. + ![Integration trigger select](./images/integration_triggers.png) + +- **Input for the integrated Actor** - The input usually has two parts: static fields whose value doesn't change between runs (for example, a database connection string or table name) and dynamic fields specific to the triggering run (for example, a dataset ID). Static fields go in as-is. Dynamic fields are pulled from the implicit `payload` field (the default for most integration-ready Actors) or set with variables. +- **Available variables** - The same variables as in webhooks. The most common is `{{resource}}`, which holds the Run object in the shape returned by the [API](/api/v2/actor-run-get), or the Build object for build event types. Variables support dot notation, so `{{resource.defaultDatasetId}}` or `{{resource.defaultKeyValueStoreId}}` is usually all you need. ## Test your integration -When adding a new integration, you can test it using a past run or build as a trigger. This will trigger a run of your target Actor or task as if your desired trigger event just occurred. The only difference between a test run and regular run is that the trigger's event type will be set to 'TEST'. The test run will still consume compute units. +When you add a new integration, you can test it using a past run or build as a trigger. The integrated Actor or task runs as if the trigger event just happened. The only difference from a regular run is that the event type is set to `TEST`. The test run still consumes compute units. + +To test, set the input and options, save, then pick an option from the test menu: -To test your integration, first set your desired input and options and save. You can then select one of the options from the menu. If the source of your integration is a task, you can test it using a past run. For Actors, you can use a past run or build. Alternatively, if the source of your integration has neither, you can test your integration with a random joke in the webhook's payload. +- A past run, if the source is an Actor or a task. +- A past build, if the source is an Actor. +- A random joke in the webhook payload, if the source has no runs or builds yet. ![Test integration options](./images/integrations_test_options.png) -When testing with a custom run or build, you will need to enter its ID. You can find it on the run's or build's detail page. Ensure that the run or build belongs to the **source** Actor, since that is where the trigger will be coming from. +For a custom run or build, enter its ID - you can find it on the run's or build's detail page. The run or build must belong to the **source** Actor, since that is where the trigger originates. ## Implementation details -Under the hood, the Actor integrations use regular [HTTP POST webhooks](https://www.redhat.com/en/topics/automation/what-is-a-webhook) and target the Apify API, for which this feature provides a friendlier UI. The UI allows you to fill the payload template using the Actor input UI rather than plain text and constructs the URL to start your Actor with the given options. +Actor integrations are regular [HTTP POST webhooks](https://www.redhat.com/en/topics/automation/what-is-a-webhook) targeting the Apify API. The Integrations UI is a friendlier wrapper that lets you fill the payload template through the Actor input UI instead of plain text, and constructs the URL that starts the target Actor with the chosen options. -The UI ensures that the variables are enclosed in strings, meaning that even the payload template is a valid JSON, not just the resulting interpolation. It also automatically adds the `payload` field that contains the default webhook payload. Thanks to this, when using Actors that are meant to be used as integrations, users don't have to fill in the variables: the Actor takes the data from this field by itself. +The UI keeps variables enclosed in strings, which means the payload template is valid JSON rather than only the interpolated result. It also adds a `payload` field with the default webhook payload, so integration-ready Actors can read run data from `payload` without users having to set variables themselves. ## Blog tutorial -You can read a complete example of integrating two Actors in [this tutorial](https://blog.apify.com/connecting-scrapers-apify-integration/). +For a complete walkthrough, see [Connecting scrapers with Apify integrations](https://blog.apify.com/connecting-scrapers-apify-integration/). From 7f4bdb9b6f50902c0cd2ba0f29d92ed7bc987191 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Tue, 19 May 2026 14:03:03 +0200 Subject: [PATCH 2/4] docs(integrations): address review feedback on Actor-to-Actor page - Use "trigger" instead of "fire" for consistency with platform terminology - Drop conversational "still" from the test-run note - Remove emphasis bold from "source" Actor (style guide reserves bold for UI elements) - Replace single "Blog tutorial" link with a "Next steps" section pointing at the two sibling pages plus the blog walkthrough Co-Authored-By: Claude Opus 4.7 (1M context) --- sources/platform/integrations/actors/index.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/sources/platform/integrations/actors/index.md b/sources/platform/integrations/actors/index.md index e416ce2d65..350f98347b 100644 --- a/sources/platform/integrations/actors/index.md +++ b/sources/platform/integrations/actors/index.md @@ -32,7 +32,7 @@ To connect an Actor with another Actor or task: On the setup screen, configure: -- **Triggers** - Events that fire the integrated Actor. These match webhook [event types](/platform/integrations/webhooks/events) (`run succeeded`, `build failed`, and so on). +- **Triggers** - Events that trigger the integrated Actor. These match webhook [event types](/platform/integrations/webhooks/events) (`run succeeded`, `build failed`, and so on). ![Integration trigger select](./images/integration_triggers.png) @@ -41,7 +41,7 @@ On the setup screen, configure: ## Test your integration -When you add a new integration, you can test it using a past run or build as a trigger. The integrated Actor or task runs as if the trigger event just happened. The only difference from a regular run is that the event type is set to `TEST`. The test run still consumes compute units. +When you add a new integration, you can test it using a past run or build as a trigger. The integrated Actor or task runs as if the trigger event just happened. The only difference from a regular run is that the event type is set to `TEST`. Test runs consume compute units. To test, set the input and options, save, then pick an option from the test menu: @@ -51,7 +51,7 @@ To test, set the input and options, save, then pick an option from the test menu ![Test integration options](./images/integrations_test_options.png) -For a custom run or build, enter its ID - you can find it on the run's or build's detail page. The run or build must belong to the **source** Actor, since that is where the trigger originates. +For a custom run or build, enter its ID - you can find it on the run's or build's detail page. The run or build must belong to the source Actor, since that is where the trigger originates. ## Implementation details @@ -59,6 +59,8 @@ Actor integrations are regular [HTTP POST webhooks](https://www.redhat.com/en/to The UI keeps variables enclosed in strings, which means the payload template is valid JSON rather than only the interpolated result. It also adds a `payload` field with the default webhook payload, so integration-ready Actors can read run data from `payload` without users having to set variables themselves. -## Blog tutorial +## Next steps -For a complete walkthrough, see [Connecting scrapers with Apify integrations](https://blog.apify.com/connecting-scrapers-apify-integration/). +- [Creating integration Actors](/platform/integrations/actors/integration-ready-actors) - design your own Actor to be used as an integration target. +- [Integrating Actors via API](/platform/integrations/actors/integrating-actors-via-api) - set up the same integrations programmatically with the Apify API. +- [Connecting scrapers with Apify integrations](https://blog.apify.com/connecting-scrapers-apify-integration/) - a complete walkthrough on the Apify blog. From d0d6b9b4a894dcf2325ee4d92e1b2bcf7a86becd Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Tue, 19 May 2026 15:02:49 +0200 Subject: [PATCH 3/4] docs(integrations): clarify integration-ready Actors page - Rename page title to "Develop integration-ready Actors" so the developer audience is explicit; add sidebar_label to match - Lead the page with a one-line audience statement and an explicit framing that any Actor can be a target but designed ones provide a better experience - Add a note linking to Integration Actors in Apify Store for inspiration, using the UI term "Integration Actor" for the catalog/category and "integration-ready" only as a descriptive adjective for Actor design - Update the cross-link in the Actor-to-Actor page to match the new sibling title Co-Authored-By: Claude Opus 4.7 (1M context) --- sources/platform/integrations/actors/index.md | 2 +- .../actors/integration_ready_actors.md | 15 ++++++++++++--- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/sources/platform/integrations/actors/index.md b/sources/platform/integrations/actors/index.md index 350f98347b..cc1b220729 100644 --- a/sources/platform/integrations/actors/index.md +++ b/sources/platform/integrations/actors/index.md @@ -61,6 +61,6 @@ The UI keeps variables enclosed in strings, which means the payload template is ## Next steps -- [Creating integration Actors](/platform/integrations/actors/integration-ready-actors) - design your own Actor to be used as an integration target. +- [Develop integration-ready Actors](/platform/integrations/actors/integration-ready-actors) - design your own Actor to be used as an integration target. - [Integrating Actors via API](/platform/integrations/actors/integrating-actors-via-api) - set up the same integrations programmatically with the Apify API. - [Connecting scrapers with Apify integrations](https://blog.apify.com/connecting-scrapers-apify-integration/) - a complete walkthrough on the Apify blog. diff --git a/sources/platform/integrations/actors/integration_ready_actors.md b/sources/platform/integrations/actors/integration_ready_actors.md index 2709d372f1..670ee92038 100644 --- a/sources/platform/integrations/actors/integration_ready_actors.md +++ b/sources/platform/integrations/actors/integration_ready_actors.md @@ -1,11 +1,20 @@ --- -title: Creating integration Actors -description: Build Actors designed to work as integrations with other Actors and tasks. Handle dynamic input, payload fields, and large datasets efficiently. +title: Develop integration-ready Actors +description: Learn how to develop Actors that work cleanly as integration targets, including input design, payload handling, and dataset processing patterns. +sidebar_label: Develop integration-ready Actors sidebar_position: 1 slug: /integrations/actors/integration-ready-actors --- -Any Actor can be used in integrations. In order to provide a smooth experience for its users, there are few things to keep in mind. +This page is for Actor developers. It covers the patterns to follow when building an Actor that other users will connect as an integration target - input shape, handling the implicit `payload` field, and processing dataset references rather than dataset contents. + +:::note Integration Actors + +For inspiration, browse [Integration Actors in Apify Store](https://apify.com/store/categories/integrations) - published Actors designed to be used as integration targets. + +::: + +Any Actor can be used as an integration target, but Actors designed for the role give users a smoother experience. The rest of this page assumes you are developing such an Actor. ## General guidelines From 5d5f7379bd2bcf07a385f53dc5d04445ce9d65ff Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Tue, 19 May 2026 15:34:12 +0200 Subject: [PATCH 4/4] docs(integrations): apply review fixes across Actor-to-Actor section In index.md: - Replace ambiguous pronoun "It" with explicit "The UI" on the Implementation details paragraph In integration_ready_actors.md: - Remove bold used for emphasis (dataset ID, dataset contents, "only") - bold reserved for UI elements per style guide - Drop softening "ideally try to" from the complexity-hiding rule - Replace first-person plural ("we", "we'd", "we're") with imperative/second-person voice throughout the Example section - Fix "fit to memory" -> "fit in memory" - Clean up field labels (ID instead of Id, "table or collection" instead of "table / collection") - Refresh the publishing flow to reference the new "Add integration" dialog instead of the removed "Connect Actor or task" button - Fix malformed mailto link (Actor%specific -> Actor%20specific) - Add inline TODO markers for the stale contact-support listing workflow and the outdated specific_vs_generic_integrations.png screenshot, mirroring the TODO convention from index.md Co-Authored-By: Claude Opus 4.7 (1M context) --- sources/platform/integrations/actors/index.md | 2 +- .../actors/integration_ready_actors.md | 29 ++++++++++--------- 2 files changed, 16 insertions(+), 15 deletions(-) diff --git a/sources/platform/integrations/actors/index.md b/sources/platform/integrations/actors/index.md index cc1b220729..f74dc24e1e 100644 --- a/sources/platform/integrations/actors/index.md +++ b/sources/platform/integrations/actors/index.md @@ -57,7 +57,7 @@ For a custom run or build, enter its ID - you can find it on the run's or build' Actor integrations are regular [HTTP POST webhooks](https://www.redhat.com/en/topics/automation/what-is-a-webhook) targeting the Apify API. The Integrations UI is a friendlier wrapper that lets you fill the payload template through the Actor input UI instead of plain text, and constructs the URL that starts the target Actor with the chosen options. -The UI keeps variables enclosed in strings, which means the payload template is valid JSON rather than only the interpolated result. It also adds a `payload` field with the default webhook payload, so integration-ready Actors can read run data from `payload` without users having to set variables themselves. +The UI keeps variables enclosed in strings, which means the payload template is valid JSON rather than only the interpolated result. The UI also adds a `payload` field with the default webhook payload, so integration-ready Actors can read run data from `payload` without users having to set variables themselves. ## Next steps diff --git a/sources/platform/integrations/actors/integration_ready_actors.md b/sources/platform/integrations/actors/integration_ready_actors.md index 670ee92038..c401d41f8b 100644 --- a/sources/platform/integrations/actors/integration_ready_actors.md +++ b/sources/platform/integrations/actors/integration_ready_actors.md @@ -20,19 +20,19 @@ Any Actor can be used as an integration target, but Actors designed for the role If your Actor is supposed to be used as an integration, it will most likely have an input that can be described as two groups of fields. The first group is the "static" part of the input - the fields that have the same value whenever the integration is triggered. The second, "dynamic", group are fields that are specific to the triggering event - information from the run or build that triggered the integration. -The Actor should ideally try to hide its complexity from users and take all the "dynamic" fields from the implicit `payload` field - it is attached automatically. This way, users don't have to take care of passing in variables on their own and only need to take care of the static part of the input. +The Actor should hide its complexity from users and take all the "dynamic" fields from the implicit `payload` field - it is attached automatically. This way, users don't have to take care of passing in variables on their own and only need to take care of the static part of the input. -An important thing to remember is that only the **dataset ID** is passed to the Actor as input, not the **dataset contents**. This means that the Actor needs to take care of getting the actual contents of the dataset. And, ideally, it should not load the full dataset while doing so, as it might be too large to fit to memory, but rather process it in batches. +Only the dataset ID is passed to the Actor as input, not the dataset contents. The Actor needs to fetch the contents of the dataset itself. Ideally, it should not load the full dataset at once, as it might be too large to fit in memory, but rather process it in batches. ## Example To illustrate the above, here is a simplified example of an Actor that uploads a dataset to a table/collection in some database. -We would start with an input that looks something like this: +Start with an input that looks something like this: -- `datasetId: string` - Id of dataset that should be uploaded -- `connectionString: string` - Credentials for the database connection -- `tableName: string` - Name of table / collection +- `datasetId: string` - ID of the dataset to upload +- `connectionString: string` - credentials for the database connection +- `tableName: string` - name of the table or collection With this input schema, users have to provide an input that looks like this: @@ -44,13 +44,13 @@ With this input schema, users have to provide an input that looks like this: } ``` -And in the Actor code, we'd use this to get the values: +In the Actor code, use this to get the values: ```js const { datasetId, connectionString, tableName } = await Actor.getInput(); ``` -To make the integration process smoother, it's possible to define an input that's going to be prefilled when your Actor is being used as an integration. You can do that in the Actor's **Settings** tab, on the **Integrations** form. In this example, we'd use: +To make the integration process smoother, define an input that's prefilled when your Actor is used as an integration. Set this on the Actor's **Settings** tab, in the **Integrations** form. For this example, use: ```json { @@ -62,7 +62,7 @@ This means that users will see that the `defaultDatasetId` of the triggering run Explicitly stating what is the expected input when Actor is being used as an integration is a preferred way. -However, if the Actor is **only** supposed to be used as integration, we can use a different input schema: +However, if the Actor is only supposed to be used as an integration, use a different input schema: - `connectionString: string` - Credentials for the database connection - `tableName: string` - Name of table / collection @@ -83,21 +83,22 @@ const { payload, connectionString, tableName } = await Actor.getInput(); const datasetId = payload.resource.defaultDatasetId; ``` -It's also possible to combine both approaches, which is useful for development purposes or advanced usage. It would mean keeping the `datasetId` in the input, only hidden under an "Advanced options" section, and using it like this: +You can also combine both approaches, which is useful for development or advanced usage. Keep the `datasetId` in the input, hidden under an "Advanced options" section, and use it like this: ```js const { payload, datasetId } = await Actor.getInput(); const datasetIdToProcess = datasetId || payload?.resource?.defaultDatasetId; ``` -In the above example, we're focusing on accessing a run's default dataset, but the approach would be similar for any other field. +The example above focuses on accessing a run's default dataset, but the approach is similar for any other field. ## Make your Actor available to other users -To allow other users to use your Actor as an integration, all you need to do is [publish it in Apify Store](/platform/actors/publishing), so users can then integrate it using the **Connect Actor or task** button on the **Integrations** tab of any Actor. While publishing the Actor is enough, there are two ways to make it more visible to users. +To allow other users to use your Actor as an integration, [publish it in Apify Store](/platform/actors/publishing). Users can then find it in the **Add integration** dialog on the **Integrations** tab of any Actor. While publishing is enough, there are two ways to make your Actor more visible to users. -For Actors that are generic enough to be used with most other Actors, it's possible to have them listed under **Generic integrations** in the **Integrations** tab. This includes (but is not limited to) Actors that upload datasets to databases, send notifications through various messaging systems, create issues in ticketing systems, etc. To have your Actor listed under the generic integrations, [contact support](mailto:support@apify.com?subject=Actor%20generic%20integration). +For Actors generic enough to be used with most other Actors, you can have them listed under **Generic integrations** in the **Add integration** dialog. This includes (but is not limited to) Actors that upload datasets to databases, send notifications through various messaging systems, or create issues in ticketing systems. To have your Actor listed under generic integrations, [contact support](mailto:support@apify.com?subject=Actor%20generic%20integration). -Some Actors can only be integrated with a few or even just one other Actor. Let's say that you have an Actor that's capable of scraping profiles from a social network. It makes sense to show it for Actors that produce usernames from the social network but not for Actors that produce lists of products. In this case, it's possible to have the Actor listed as **Specific to this Actor** under the Actor's **Integrations** tab. To have your Actor listed as specific to another Actor, [contact support](mailto:support@apify.com?subject=Actor%specific%20integration). +Some Actors can only be integrated with a few - or even just one - other Actor. For example, an Actor that scrapes profiles from a social network is relevant for Actors that produce usernames from that network, but not for Actors that produce product lists. In this case, you can have the Actor listed under **Suggested for this Actor** on the source Actor's **Integrations** tab. To have your Actor listed as specific to another Actor, [contact support](mailto:support@apify.com?subject=Actor%20specific%20integration). + ![Specific vs generic integrations](./images/specific_vs_generic_integrations.png)