Skip to content

docs(developer): polish the Workflow Step Type articles #876

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
andrii-bodnar merged 1 commit into from
Aug 7, 2026
+22 −22
Merged

docs(developer): polish the Workflow Step Type articles #876

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions src/content/docs/developer/modules/other/workflow-step-type.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ sidebar:
import { Steps, Aside } from '@astrojs/starlight/components';
import ReadMore from '~/components/ReadMore.astro';

This module allows you to create custom workflow step types to extend the default list of workflow steps in Crowdin Enterprise. With this app installed, the new workflow step types become available in the workflow editor, where they can be added to workflows and templates, enabling greater customization and flexibility.
With this module you can create custom workflow step types that extend the default list of workflow steps in Crowdin Enterprise. Once the app is installed, the new step types become available in the workflow editor, where they can be added to workflows and templates.

A custom workflow step is an external processing stage in a workflow. Crowdin Enterprise routes the strings, tracks their status, and counts progress, while your app implements the step's condition of done: it decides when a string is complete on the step and which output it leaves through. Typical uses include AI-based review, integration with an external review or MT system, compliance gates, and delay or scheduling steps.

Expand Down Expand Up @@ -437,7 +437,7 @@ The Workflow Step Type module relies on webhooks and API methods to communicate

Crowdin Enterprise sends a batched webhook payload to the app's Webhook module whenever strings reach a custom workflow step provided by the app. When a string lands on the custom step (for example, it was just added, moved there by a previous step, or re-triggered), its status on the step becomes **Need Process** and the webhook event is queued for delivery.

This payload contains the `string.status_on_step.recalculation_triggered` event and includes all relevant strings that need external processing (e.g., AI-based proofreading).
This payload contains the `string.status_on_step.recalculation_triggered` event and includes all relevant strings that need external processing (for example, AI-based proofreading).

<Aside>
Webhook events are delivered in batches and may arrive with a short delay. Respond with a `2xx` status code as quickly as possible and process the strings asynchronously. Read more about [Delivery Guarantees](#delivery-guarantees-and-reconciliation).
Expand Down Expand Up @@ -614,7 +614,7 @@ Below are the API methods for managing string statuses on a custom workflow step
<td><code>organization_domain</code></td>
<td>Yes</td>
<td><code>string</code></td>
<td>Your Crowdin Enterprise organization’s domain.</td>
<td>Your Crowdin Enterprise organization's domain.</td>
</tr>
<tr>
<td><code>projectId</code></td>
Expand Down Expand Up @@ -665,17 +665,17 @@ Below are the API methods for managing string statuses on a custom workflow step
{
"data": {
"stringId": 1106423,
"languageId": "uk",
"stepId": 889,
"languageId": "et",
"stepId": 1035,
"status": "DONE",
"output": "translated"
}
},
{
"data": {
"stringId": 1106430,
"languageId": "uk",
"stepId": 889,
"languageId": "et",
"stepId": 1035,
"status": "DONE",
"output": "untranslated"
}
Expand Down Expand Up @@ -708,7 +708,7 @@ Below are the API methods for managing string statuses on a custom workflow step
<td><code>organization_domain</code></td>
<td>Yes</td>
<td><code>string</code></td>
<td>Your Crowdin Enterprise organization’s domain.</td>
<td>Your Crowdin Enterprise organization's domain.</td>
</tr>
<tr>
<td><code>projectId</code></td>
Expand Down Expand Up @@ -777,17 +777,17 @@ Below are the API methods for managing string statuses on a custom workflow step
{
"data": {
"stringId": 1106423,
"languageId": "uk",
"stepId": 889,
"languageId": "et",
"stepId": 1035,
"status": "DONE",
"output": "translated"
}
},
{
"data": {
"stringId": 1106430,
"languageId": "uk",
"stepId": 889,
"languageId": "et",
"stepId": 1035,
"status": "DONE",
"output": "untranslated"
}
Expand Down
20 changes: 10 additions & 10 deletions ...t/docs/enterprise/organization-management/workflows/app-based-workflow-step.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,11 @@ Unlike built-in steps, an app-based step defines its own completion rules: the a

Below are a few examples of how app-based steps can enhance your workflows. Some are drawn from existing Crowdin Store apps, while others illustrate broader possibilities:

* **Workflow Delay** – The [Workflow Delay](https://store.crowdin.com/workflow-step-delay) app adds checkpoint-style steps that pause segments until conditions are met or on a set schedule. This helps prevent incomplete or unverified segments from moving forward prematurely, improving overall translation consistency.
* **Workflow Delay** – The [Workflow Delay](https://store.crowdin.com/workflow-step-delay) app adds checkpoint-style steps that pause strings until conditions are met or on a set schedule. This helps prevent incomplete or unverified strings from moving forward prematurely, improving overall translation consistency.

* **AI Source Review** – Another possible scenario could be an app that automatically reviews and refines source text before translation, catching typos, style inconsistencies, or placeholders that might cause issues later. This approach helps ensure higher-quality translations by starting with well-polished source strings.

* **AI Labeling** – A step that could analyze your strings and automatically apply labels (e.g., “Marketing Content,” “Technical Doc,” “High Priority”), helping route content to the most appropriate translation or review paths.
* **AI Labeling** – A step that could analyze your strings and automatically apply labels (for example, "Marketing Content", "Technical Doc", "High Priority"), helping route content to the most appropriate translation or review paths.

<CardGrid>
<LinkCard
Expand All @@ -45,7 +45,7 @@ Before you can add an app-based workflow step, you need to install the correspon
Read more about [Creating Workflow Step Apps](/developer/crowdin-apps-module-workflow-step-type/).
</ReadMore>

Depending on the app, you may need specific permissions (e.g., Manager or Admin) to install it. Once installed, the new step types appear in your workflow editor or workflow template editor.
Depending on the app, you may need specific permissions (for example, Manager or Admin) to install it. Once installed, the new step types appear in your workflow editor or workflow template editor.

<ReadMore>
Read more about [Installing Crowdin Apps](/developer/crowdin-apps-installation/#installation-in-crowdin-enterprise).
Expand Down Expand Up @@ -76,16 +76,16 @@ You can add app-based workflow steps directly to a project's workflow in the wor

Depending on how the app is implemented, an app-based workflow step may offer various configuration options, or none at all. For example:

* **Configurable Steps** – Some steps allow you to adjust parameters in the workflow editor (e.g., specifying a delay for content processing). In these cases, you can modify the available options to suit your needs.
* **Configurable Steps** – Some steps allow you to adjust parameters in the workflow editor (for example, specifying a delay for content processing). In these cases, you can modify the available options to suit your needs.

* **Pre-configured Steps** – Other steps have all their settings predefined by the app (e.g., delaying content until an entire file is fully translated), so no additional fields appear in the workflow editor.
* **Pre-configured Steps** – Other steps have all their settings predefined by the app (for example, delaying content until an entire file is fully translated), so no additional fields appear in the workflow editor.

If a step provides configuration fields, they typically appear in the step's settings panel once you drag it into the workflow.

These fields can include anything from AI prompts and allowed actions (e.g., approving or deleting translations, adding translation suggestions or comments, etc.) to API tokens, delay intervals, or match conditions — whatever the app developer has enabled. If there are no visible configuration options, the app likely manages all necessary setup internally.
These fields can include anything from AI prompts and allowed actions (for example, approving or deleting translations, adding translation suggestions or comments) to API tokens, delay intervals, or match conditions, whatever the app developer has enabled. If there are no visible configuration options, the app likely manages all necessary setup internally.

<Aside type="tip">
We recommend to always explore the app's documentation for details on any available settings it may provide.
Explore the app's documentation for details on the settings it provides.
</Aside>

## Troubleshooting
Expand All @@ -94,10 +94,10 @@ When an app-based step is misconfigured, Crowdin Enterprise flags the workflow a

* **Error Banners and Inactive Steps** – If the app is removed or becomes inactive, your project's Dashboard may display a banner informing about the workflow issues with instructions on how to resolve them.
<Image src={workflowIssuesBanner} alt="Workflow Issues Banner" />
In the workflow editor, you may see steps with failed validations (e.g., *The application required for this step type is uninstalled*). To fix this, reinstall the app and reconfigure its step, or remove the step if it's no longer needed.
* **Validation Warnings** – When saving changes to the workflow, a warning might appear if the app-based step is misconfigured or has unmet dependencies (e.g., *Workflow Delay Agent requires manager permissions*). Such a warning usually means that the app's [bot user](#bot-user) lost manager access to the project – re-add the bot to the project members with the Manager role.
In the workflow editor, you may see steps with failed validations (for example, *The application required for this step type is uninstalled or not allowed for the project*). To fix this, reinstall the app and reconfigure its step, or remove the step if it's no longer needed.
* **Validation Warnings** – When saving changes to the workflow, a warning might appear if the app-based step is misconfigured or has unmet dependencies (for example, *"Workflow Delay Agent" requires manager permissions for the project*). Such a warning usually means that the app's [bot user](#bot-user) lost manager access to the project – re-add the bot to the project members with the Manager role.
* **Failed Strings on the Step** – If the app couldn't be notified about strings that reached its step (for example, the app's service was temporarily unavailable), those strings are counted as failed words on the step. The step then shows a warning with the number of failed words. Once the app is available again, a project manager can click **Resend** on the step to send those strings to the app again.
* **No Access to the App-based Step** – Occasionally, an app-based step may not appear in the workflow editor if the app was installed with limited project access or if you lack the required role (e.g., Manager). Check your project settings to confirm you have Manager or Admin rights and that the app is allowed in the intended project.
* **No Access to the App-based Step** – Occasionally, an app-based step may not appear in the workflow editor if the app was installed with limited project access or if you lack the required role (for example, Manager). Check your project settings to confirm you have Manager or Admin rights and that the app is allowed in the intended project.
* **Connectivity or External Service Errors** – If an app-based step relies on a third-party service or API, timeouts or network failures may cause the step to fail or get stuck.
* **Check Service Status**: Verify that any external service used by the app is online and functioning properly.
* **Inspect Logs**: If the app provides logs or an admin panel, review any error messages it may have generated.
Expand Down
Loading