How to Change the Recommendation Text in a Tool Workflow Definition

In this Article

• Overview
• Prerequisites
  • Step 1: Open the Workflow Definition
  • Step 2: Download a Backup
  • Step 3: Edit the Workflow Definition
  • Step 4: Locate the Required Check
  • Step 5: Update the Recommendation Text
  • Step 6: Save the Changes
  • Step 7: Validate the Changes
• Result
• Best Practices
• Troubleshooting
• Video Link

Overview

This article explains how to update the Recommendation Text in a Tool Workflow Definition.

A workflow definition is composed of multiple Checks. Each Check evaluates a specific condition and, when the condition evaluates to True, returns a response that includes:

• Issue Category
• Recommended Next Step
• Recommended Actions
• Explanation

This guide demonstrates how to locate the appropriate Check, update the Recommended Next Step, save the workflow definition, and validate the changes.

Prerequisites

Before making any changes, ensure that:

• You have access to the required Data Source and Agent.
• The appropriate Tool is configured for the Agent.
• You perform the changes in a Development or Test environment before applying them to Production.
• You create a backup of the existing workflow definition.

Note: Always create a backup before modifying a workflow definition.

Step 1: Open the Workflow Definition

1. Open the required Data Source.
2. Select the appropriate Agent.
3. Open the Definition tab.
4. Under the Tools section, select the Tool whose workflow definition you want to modify.

The selected Tool contains the workflow definition used to process troubleshooting scenarios.

Step 2: Download a Backup

Before editing the workflow definition:

1. Click Download.
2. Save the workflow definition to a secure location.

The backup can be used to restore the previous configuration if required.

Step 3: Edit the Workflow Definition

1. Click Edit.
2. Copy the existing workflow definition.
3. Paste it into your preferred text editor.

Using a text editor makes it easier to search and update the required configuration.

Step 4: Locate the Required Check

Each Check represents a specific troubleshooting scenario within the workflow.

When a Check evaluates to True, the values configured under the on_true → set section are returned.

These values typically include:

• Issue Category
• Recommended Next Step
• Recommended Actions
• Explanation

Locate the Check that contains the Recommendation Text you want to modify.

Best Practice: Search using the Check rather than the Recommendation Text. Recommendation Text may change over time, while the Check remains a more reliable identifier.

Step 5: Update the Recommendation Text

After locating the required Check, navigate to the on_true → set section.

Locate the recommended_next_step field.

Update only the value of recommended_next_step.

Example

Before

"recommended_next_step": "BBMS system data unavailable. Contact IT support immediately and use backup manual troubleshooting procedures."

After

"recommended_next_step": "BBMS system data is currently unavailable. Please contact IT Support to restore connectivity before continuing with troubleshooting."

Important

Modify only the recommended_next_step value.

Do not modify:

• issue_category
• recommended_actions
• explanation
• check
• matched_input_data
• checked_condition

unless your implementation specifically requires those changes.

Step 6: Save the Changes

1. Copy the updated workflow definition.
2. Return to the workflow editor.
3. Replace the existing workflow definition.
4. Click Done.
5. Click Save.

Wait until the confirmation message indicates that the workflow definition has been saved successfully.

Step 7: Validate the Changes

1. Return to the Agent.
2. Execute the same test scenario.
3. Verify that the updated Recommended Next Step is returned in the response.

Before:

After:

Result

The Recommendation Text has been updated successfully.

Whenever this Check evaluates to True, the Tool returns the updated Recommended Next Step while preserving the existing workflow logic.

Best Practices

• Always create a backup before modifying a workflow definition.
• Test changes in a Development or Test environment before applying them to Production.
• Locate the correct Check before making any modifications.
• Update only the recommended_next_step field when changing recommendation text.
• Avoid modifying workflow logic unless it is part of the requested change.
• Validate the updated recommendation using a representative test scenario.

Troubleshooting

Unable to Locate the Required Check

• Verify that you are editing the correct Tool.
• Search using the Check name or the existing Issue Category.
• Confirm that you are working with the correct workflow definition.

Recommendation Is Not Updated

• Verify that the workflow definition was saved successfully.
• Confirm that the recommended_next_step field was updated under the correct Check.
• Execute a new test scenario to verify the updated recommendation.

Unexpected Results

If the workflow returns unexpected results after the update:

• Restore the previously downloaded workflow definition.
• Review the changes made to the recommended_next_step field.
• Ensure that no other workflow configuration was modified unintentionally.

Video Link:

Recommendation text change.