Workflow Best Practices

Last updated
Save as PDF

Workflow Best Practices

Cisco-developed content for Exchange follows strict standards for assessing both technical capability and use case quality. In addition to running successfully, a workflow or atomic action must: be relatively easy to understand, have consistent and meaningful error handling, and accomplish a well-defined outcome.

One of the many benefits of Automation is that anyone can customize a workflow to accommodate their specifc needs. Accordingly, workflows should be written with flexibility and ease of use by others in mind. For example, you can use variables wherever feasible to allow for customization. Error handling is one of the most important aspects of designing a workflow. Others using your workflow may run into issues and should receive clear error messages to guide them to the problem. In addition, if a worklflow fails to accomplish its objective, it should fail so that it is obvious that the intended action was not completed.

Workflows should have a clear, specific objective and accomplish that objective within well-defined requirements. The following best practices should be followed when building a workflow.

General

Naming and Descriptions

Use meaningful, human-readable names for workflows, variables, groups, and activities. Avoid duplication, unnecessary prefixes, and unclear naming.
All descriptions (for workflows, variables, activities, and groups) must be clear and concise. Each description should specify the purpose, intended usage, prerequisites, known limitations, external dependencies, and any relevant details such as targets used and required steps.
For activity output variables, such as Python activity or JSON Path, variable names should be written in camelCase to distinguish them from workflow names, for example, deviceID and sortByDate.
Proofread all user-facing text for grammar, spelling, and clarity.

Publishing Workflows

Do not publish workflows with an actual automation rule or a specific target assigned. Only publish with the workflow type to avoid exporting unwanted associated rules.
Before publishing, review the workflow to remove or replace all sample or test data (for example, variable defaults, API endpoints, or inline documentation) with generic placeholders or production-ready values.

Predictable Workflows

Design workflows to be predictable and make clear, quantifiable changes. For example, if a workflow attempts to add an object to a group that does not exist, it is acceptable to create that group. However, you should not attempt to create a different group, as that is not a predictable change.
Ensure users can easily understand what changes a workflow will make to their infrastructure before running it. This transparency is essential, especially for organizations that require change control or approval of standard changes.
To preserve system resources and ensure the integrity and performance of the platform, certain limits are in place around workflows and automation rules. For details, refer to the Important Notes and Limits.

Idempotency Checks for CREATE/DELETE Operations

Implementing these checks prevents failures or unexpected outcomes if the workflow is executed multiple times.

Before creating a resource, check whether it already exists and handle 'already exists' errors gracefully.
Before deleting a resource, verify that it exists and handle 'not found' errors appropriately.

Categories and Organization

Assign workflows to appropriate categories for discoverability. Avoid creating new categories if an existing one suffices.
Remove orphaned or unused groups and categories to maintain organization.
Use group activities to segment workflow sections; name and describe groups clearly for readability and maintainability.

Inputs, Variables, and Parameters

For all workflow inputs, define and validate the type (e.g., String, Integer, Boolean, SecureString) to ensure data integrity and proper handling.
To simplify the design of a workflow, consider using sub-workflows and/or atomics to use fewer variables in the workflow.
Use Secure Strings for sensitive values such as API keys, passwords, or other credentials that should be hidden from view.
All workflows must include standard output variables: Result, Status Code, Status Message, and Error Message. Provide clear guidelines on their consistent population for both success and failure paths.
Default values fields must be safe: use only generic placeholders or non-production data. Avoid hardcoding real IPs, device serials, organization IDs, or credentials in default values.
Identify and consolidate duplicate or similar inputs that serve the same purpose to reduce redundancy.
Avoid unnecessary prefixes such as 'Input -' or 'Output -' in variable names to maintain clarity and conciseness.
Ensure input variables are marked as required if the workflow will fail to function if the variables are left blank.
If a local variable is necessary for a workflow to function, check that it isn’t blank.
For numeric variables, provide an appropriate default value.
When using date-time stamps, use the actual DateTime variable type where possible, especially for input and output variables. Use Format Date and Parse Date activities to convert to/from strings.
Consider using sub-workflows or atomics to reduce the number of variables in the main workflow.

For more information on using variables to store workflow data in Automation, start with the Variables Help topic.

Target and Target Groups

Avoid hardcoding specific targets within workflow logic. If hardcoding is required for scheduled or webhook-triggered workflows where the target is inherently fixed, clearly document this exception in the workflow description.
Ensure matching_conditions within target_groups are generic and do not contain environment-specific values (e.g., specific hostnames, IPs, user IDs) unless explicitly justified and documented.
Regularly review and clean up unused targets or target groups that are defined but not referenced by any workflow activities.
Whenever possible, avoid using custom HTTP targets by utilizing existing integrations or default targets instead. Custom HTTP targets can complicate imports and increase errors. Use them only if no integration or default target exists for the product/service. Check for existing integrations on the Automations > Targets page, including the pre-built target for Workflow APIs. For more information, see the Default Targets Help topic.

Account Keys

Use the target’s default account keys for workflows and their activities whenever possible.
The account keys should be defined as part of the target’s configuration. Overriding a target’s account keys within a workflow is uncommon.

For details on managing authentication credentials for targets, see Account Keys topic.

Activities

Use short, clear, and descriptive activity names that are informative and meaningful.
Enable Continue Workflow execution on failure checkbox to continue workflow execution despite a failure of the activity. In such cases, you can handle the errors by setting the Workflow Results output property. Add a condition block underneath to check for the previous activity's Succeeded boolean property or Error Code.
When setting a single local variable, name the activity after the variable being set (for example, “Set Service Group” for a variable named Service Group). When setting two or more variables, go with "Set output variables".
Name Web Service Request activities using the prefix “Request to …” if it doesn't conflict with the way these activities are named in the existing workflows of the same provider.
To simplify the design of a workflow, consider using sub-workflows and/or atomics to use fewer actions in the workflow.
For Loop activities, ensure that break_conditions or max_iterations are explicitly defined and correctly configured to prevent infinite execution and to guarantee predictable termination. Refer to the Important notes and Limits section for guidance on maximum iteration thresholds.
For activities of type atomic_workflow, clearly explain in the activity description why you created a new atomic workflow instead of reusing an existing one. Reuse existing atomic workflows or built-in integrations, whenever possible.
Use existing atomic workflows or native integrations over generic web_service_request activities when an atomic alternative is available. When a generic API call (web_service_request) is used in place of an existing atomic workflow or integration, document the rationale in the activity description.
For all web_service_request activities, ensure the description includes:
- Expected inputs and outputs
- Known or potential error scenarios
- Notes for future improvements or potential refactoring into an atomic workflow

For more information on the core-functionality activities in Automation, start with the Activities Help topic.

Error Handling

Make sure you perform proper error checking, for instance with JSON parsing and HTTP requests. And be mindful of how you handle the errors:
- If an error occurs that prevents a workflow from continuing, it’s best to use a Completed activity to fail the workflow and return a descriptive error.
- If an error occurs that can be ignored, either make note of the error so you can inform someone at the end of the workflow, or ignore it.
At the end of your workflow, set the Workflow Result output property. For more information, see the Workflow Variables - Workflow Result Help topic.
Ensure that both success and failure paths explicitly update all standard output variables (Result, Status Code, Status Message, and Error Message) to provide comprehensive and consistent status information.
Implement error aggregation mechanisms for sub-workflows and API calls so that all relevant errors are captured and clearly surfaced in the main workflow’s outputs.
For long-running or external operations (such as API calls or sub-workflows), configure appropriate timeout settings and retry logic to improve resilience and prevent indefinite execution or cascading failures.