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.

When creating a workflow, you can start with a blank workflow or choose the type of workflow to gain some configuration assistance according to its intent (incident response, pivot menu, automation rule) and expedite the build process. For more information, see the Workflow Intent Help topic.

Name the workflow something meaningful, and avoid duplicating names.

Provide a detailed description. For instance, include the purpose of the workflow and how it should be used. Include details such as targets used and what steps should be performed.

Workflows should have a clear purpose and a user should be able to walk through a workflow and understand what it’s doing.

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.

Do not publish the workflow with an actual automation rule assigned, just the type, as all associated rules are exported alongside the workflow, which is unwanted behavior.

Workflows should be predictable and make easily quantifiable changes. For example, if the workflow tries to add an object to a group and the group doesn’t exist, you may attempt to create that group. However, you should not attempt to create a different group, as that’s not a predictable change.

The user should always be able to understand in advance what a workflow is capable of changing in their infrastructure. Many large enterprises require change control or pre-approved standard changes and being able to explain the nature of potential changes is crucial.

To preserve system resources and ensure the integrity and performance of the platform, there are some limits put in place around workflows and automation rules. See the Important Notes and Limits in the Workflows Help topic and Thresholds and Limits in the Automation Rules Help topic.

Names of activities should be short but descriptive enough and follow the capitalization rules of sentence case.

There's an option that allows the execution of a workflow to continue despite an activity failure. To do so, check the Continue Workflow execution on failure check box 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.

To set one local variable, the name of the activity should specify the name of the variable. For example, if you are to set a value for a variable named Service Group, then the name of the activity should be Set Service Group instead of Set local variable. To set two or more variables in bulk, go with Set output variables.

Web Service Request activity names should start with "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 more information on the core-functionality activities in Automation, start with the Activities Help topic.

If in XDR an integration with associated target exists, you should use that integration target in your workflow. Check for existing integrations on the Administration > Integrations page. For more information, see the Targets Created From Integrations Help topic.

There are pre-built targets for all internal Cisco XDR APIs that you can and should also use. For more information, see the Default Targets Help topic.

Whenever you can, avoid using custom HTTP targets, by using the integration or default targets instead. Custom HTTP targets are copied during an import, which might not be desirable. It also makes the workflow more complex and thus more prone to errors. If your workflow is targeting a product or service that we do not have an integration or default target for, using a custom HTTP target is appropriate.

For more information on various types of targets in Automation, start with the Targets Help topic.

Workflows and their activities should use their targets’ default account keys 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 more information on authentication credentials with targets in Automation, start with the Account Keys Help topic.

Give all of your variables (input, output, and local) meaningful names and descriptions. They should be user-friendly and explicitly descriptive.

  • Names should be in human-readable, capitalized form, no snake or camel case.

  • Descriptions should include information about the variable’s purpose.

    Describe what the variable does in terms of the workflow, its possible values, how to obtain the values, possible outcomes, and so on.

Make input variables 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, and if it is, fail the workflow.

For numeric variables, provide an appropriate default value.

Use Secure Strings for sensitive values such as API keys, passwords, or other credentials that should be hidden from view.

When using date-time stamps, try to use the actual Date Time variable type where possible, especially for input and output variables. You can always use the Format Date and Parse Date activities to convert to/from strings.

For activity output variables, like Python activity or JSON Path, the names of the variables should be written in camelCase, as they're considered code-related. And that helps distinguish them from the workflow names. For example, deviceID vs. Device ID, and sortByDate vs. sort_by_date.

To simplify the design of a workflow, consider using sub-workflows and/or atomics to use fewer variables in the workflow.

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