How to use this guide
If you’re new to configuration deployment, start here to learn what it is and how to perform a deployment.
- Pre-deployment: Use the checklist below to prevent common pitfalls before pushing configurations through environments.
- Post-deployment: Use the error table to quickly diagnose issues and take corrective action based on specific error messages.
1. Preventive checklist: Best practices to minimise issues during promotion
The principles below help reduce deployment errors by ensuring the configuration and workflow are set up correctly from the start.
-
Use proper environment flow
Always make configuration changes in Development (or Sandbox), then deploy through to UAT (or Testing) before reaching Production.
Avoid skipping UAT or creating new processes directly in UAT.
Note: While the Sandbox → UAT → prod flow is considered best practice for most use cases, we understand that some clients may wish to enable direct promotions from Sandbox to Prod. This option provides additional flexibility, allowing organizations to expedite their deployment process. Please reach out to Duco Support for adjusting the configuration flow.
-
Avoid referencing specific users
Users will need to be added independently in their respective environments.
Deploying users across environments is not allowed.
Do not reference individual users (for example, in workflow rules or permissions).
Instead, use group-based references to simplify user management across environments.
-
Avoid unsupported components
The following items are not supported in configuration deployments:- Domain whitelists or processes with the Masking feature enabled
- Cash processes (handle these via the Configuration Export/Import feature instead)
- Deleting components on the target by removing them from the source (except for certain submission routing components)
- Deployment of reference data records (only table definitions supported)
-
Follow correct package creation procedure
To avoid inconsistencies during deployment:- Complete the package in one session; saving and returning to it later is not supported.
- Always recreate a package from scratch if any components have changed.
Using an old package may lead to mismatches, as it won’t reflect the latest component updates.
-
Stay within process limits
A single deployment package should include no more than 50 processes (along with their components).
-
Avoid deleting deployed components prematurely
Deleting components that were previously deployed (and still needed) can cause future promotions to fail. For example, if a process deployed earlier is deleted, redeploying it later may result in errors.
2. Error reference table: Common errors & suggested actions
Use the table below to understand and resolve common deployment errors.
| Error message | Explanation | Recommended action |
| “This reference data table or process contains user in configuration” | The configuration contains direct user references, which are unsupported. | Replace user references (e.g. in permissions, workflow rules, or notifications pages) with group-based references, then rebuild the package. |
| “This process contains email in configuration” | The source process includes a specific email address. | Replace direct email references in notifications with group-based references, then rebuild the package. |
| “Data source with name <name> and/or pattern <pattern> already exists on target environment” | For data sources, both name and pattern must be unique within the environment. **Please refer to the table at the end of the article to help you understand the uniqueness conditions and various success and failure scenarios. |
Compare the names and patterns of the relevant data sources in both the source and target environments, then update them to remove conflicts, before rebuilding the package. |
| “Group, label, or reference data table with name <name> already exists on target environment” | Groups, labels, and reference data tables must have unique names within the target environment. If the object was already promoted once, but now the target environment contains another object which uses the same name (possibly renamed or modified locally), it violates the uniqueness criteria. |
Check the target environment for a group, label or reference data table with the same name. Rename the conflicting object in the target, or change the name of the object in the source, before rebuilding the package. |
|
“Unsupported change requested” or “Unsupported attribute change requested” |
Attempted change is not allowed in the platform. Examples include: deleting columns, or changing attributes like field type and tracking key constituents. | Revert the unsupported change in the source environment before rebuilding the package. If the change is required, make it in the target environment first before promoting the package. |
| “Process <code> on target has different type than source: <type> vs <type>” | There is a mismatch of process type between the source and target environment, using the same process code. | Ensure consistent process type across environments. Package promotion automatically maps processes based on process code. Process code is a unique identifier and cannot be changed once created. |
| “Failed to apply staging copy <code>, submissions in ‘pending’ state” | The target process has pending submissions or is generating snapshots. | Clear pending submissions and wait for snapshot generation to finish, before retrying the deployment. |
| “Process <code> was deleted on target environment” | The target process with same process code has been deleted. | If a process has been deleted, create a copy of the original process and promote the copy instead. Ensure the new process has a unique process code (different from the deleted one) to prevent conflicts during promotion. |
Not seeing your error?
If the error is not listed above, please retry the deployment.
If the issue persists or the recommended actions don’t resolve it, contact Duco Support at support@du.co, with the error message and package ID.
Breakdown of scenarios for data source promotion
| Scenario | Promoted before? | Source environment | Target environment | Result |
| Data source with the same name and pattern | No | Name: ABC-Data Pattern: abc*.csv |
Name: ABC-Data No other data sources have this name or pattern |
SUCCESS |
| Data source with the same name but different pattern | No | Name: ABC-Data Pattern: abc*.csv |
Name: ABC-Data No other data sources with this name or pattern |
FAILED |
| Data source with different name but the same pattern | No | Name: ABC-Data Pattern: abc*.csv |
Name: ABCD-Data No other data sources have this name or pattern |
FAILED |
| Change name/pattern for already promoted data source | Yes | Name: New-ABC-Data Pattern: new-abc*.csv |
Name: ABC-Data No other data sources with name New-ABC-Data or pattern new-abc*.csv |
SUCCESS |
| Change name/pattern for already promoted data source | Yes | Name: New-ABC-Data Pattern: new-abc*.csv |
Name: ABC-Data Pattern: abc*.csv There is already another data source with name |
FAILED |