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 or Recommended Actions
  • 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 or Recommended Actions 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 or Recommended Actions, 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 name, troubleshooting condition, or existing Issue Category. For example, for a billing-related troubleshooting scenario, you can search for the condition is_billing_issue == true or the Issue Category BILLING to locate the appropriate Check.

Step 5: Update the Recommendation Text or Recommended Actions

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

Update the Recommendation Text

Locate the recommended_next_step field and update its value with the required recommendation text.

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."

Update the Recommended Actions

If the troubleshooting workflow requires a different action, you can also update the recommended_actions field.

The recommended action should be selected based on the applicable Issue Category and troubleshooting condition.

Example: Adding a Recommended Action

Suppose a Check has the Issue Category set to ERROR_GETTING_DATA, but no recommended_actions are currently configured.

Before:

"issue_category": "ERROR_GETTING_DATA",
"recommended_actions": []

If you want to add a recommended action for this Check, update the recommended_actions field with the appropriate action, such as CREATE_TICKET.

After:

"issue_category": "ERROR_GETTING_DATA",
"recommended_actions": ["CREATE_TICKET"]

This provides the CREATE_TICKET recommended action when the Check evaluates to True.

Similarly, other appropriate action keywords, such as TRANSFER_TO_AGENT or RESET_MODEM, can be added based on the troubleshooting requirement.

Important

• When changing only the recommendation text, update only the recommended_next_step value.
• If the troubleshooting workflow requires a change in the recommended action, you can update recommended_actions as well.
• Ensure that the selected action is appropriate for the corresponding Issue Category and troubleshooting condition.
• Do not modify other workflow fields unless the change is specifically required.

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 or Recommended Action are returned in the response.

Recommended Next Step

Before:

After:

Recommended Action:

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.