Watson Conversation Deployment Utilities

A set of utilities to script common Watson Conversation tasks without using the service tooling.

These are particularly useful if you need to build or apply changes to a set of Watson Conversation instances in an additive, programmatic, and repeatable way. A few examples of useful situations for these utilities:

1. You want to copy a dialog branch from one workspace to another without overwriting the entire dialog tree
2. You want to merge entity definitions from one workspace to another without overwriting existing entity components
3. You want to build a workspace as a set of modular components. (Workspace 1 uses modules A and C, but workspace 2 uses modules B and C)

Get Started

To install:

pip install wcs-deployment-utils

Then import the library into your python project and use

Included Functions

copy_dialog_branch

Module: wcs_deployment_utils.dialog.copy_dialog_branch

Copy a branch of dialog from a source workspace to a target workspace.

Default insert is 'sibling' which inserts the branch as the immediate sibling of the target node. Alternatively, 'child' or 'last_child' can be specified so that the branch is inserted as the first or last child of the node. If target_node is specified as 'root', the branch can be inserted as the first child of the dialog root

Any existing nodes with the same name or ID will be deleted.

These options are summarized below

    Root
    |
    |--Target Node
    |       |
    |       |<-(insert as child)
    |       |
    |       |--Existing Node
    |       |
    |       |<-(insert as last_child)
    |       |
    |       |--"true" node
    |
    |<-(insert as sibling)
    |
    ...

parameters:

root_node: ID or title of the root node in source

target_node: ID or title of the root node in target

target_insert_as: Default 'child'. Location of branch insertion, with respect to the target node. valid options ['child', 'last_child' or 'sibling']

source_username: Username for source WCS instance

source_password: Password for source WCS instance

source_workspace: Workspace ID for source WCS instance

target_username: Username for target WCS instance

target_password: Password for target WCS instance

target_workspace: Workspace ID for target WCS instance

version: WCS API version

target_backup_file: write a backup of target workspace to this file

returns:

target_nodes: the root node of the projected target tree

projected: a string representation of the projected tree

example:

from wcs_deployment_utils.dialog import copy_dialog_data

_, projection = copy_dialog_branch(
        root_node='order a pizza',
        target_node='root',
        target_insert_as='child',
        source_username=CONVERSATION_USERNAME, 
        source_password=CONVERSATION_PASSWORD, 
        source_workspace=WORKSPACE_ID,
        target_username=CONVERSATION_USERNAME, 
        target_password=CONVERSATION_PASSWORD, 
        target_workspace=TARGET_WORKSPACE,
        version=VERSION,
        target_backup_file='backup/ex4.json')

and the projection will look like:

root
├── order a pizza (jumps to: kind of pizza)
│   ├── response_condition - @special_type:vegetarian
│   ├── kind of pizza (jumps to: get name)
│   │   ├── event_handler - @special_type:vegetarian
│   │   ├── event_handler
│   │   ├── event_handler
│   │   ├── slot - @special_type != 'vegetarian'
│   │   │   ├── event_handler
│   │   │   ├── event_handler - @pizza_type
│   │   │   ├── event_handler - @pizza_type:deep-dish
│   │   │   ├── event_handler - @pizza_type:thin-crust
│   │   │   └── event_handler - true
│   │   ├── slot - @special_type != 'vegetarian'
│   │   │   ├── event_handler
│   │   │   ├── event_handler - @pizza_topping
│   │   │   ├── event_handler - @pizza_topping:jalapeno
│   │   │   └── event_handler - true
│   │   ├── event_handler
│   │   └── true
│   │       └── slot
│   │           ├── event_handler
│   │           └── event_handler
│   └── response_condition - true
├── welcome
├── 1
├── 2
│   ├── 2_1
│   └── 2_2
├── 3
│   ├── 3_1
│   ├── 3_2
│   └── 3_3
├── get name
│   └── name slot
│       └── slot
│           ├── event_handler - @sys-person
│           └── event_handler
└── Anything else

generate_wcs_diagram

Module: wcs_deployment_utils.dialog.generate_wcs_diagram

Generates a compact, text represation of a WCS dialog.

root
├── welcome
├── 1 (jumps to: 3)
├── 2
│   ├── 2_1
│   └── 2_2
├── 3
│   ├── 3_1
│   ├── 3_2
│   └── 3_3
└── Anything else

parameters:

conversation_username: WCS instance username

conversation_password: WCS instance password

version: WCS API version

workspace: WCS instance workspace

returns:

projection: a string representation of the WCS workspace

example:

from wcs_deployment_utils.dialog import generate_wcs_diagram

projection = generate_wcs_diagram(
    conversation_username=CONVERSATION_USERNAME,
    conversation_password=CONVERSATION_PASSWORD,
    version=VERSION,
    workspace=WORKSPACE_ID
)

copy_intent_data

Module: wcs_deployment_utils.intents.copy_intent_data

Copy intent data from a WCS workspace to a target workspace.

Copy intent data in an additive pattern from a source workspace to a target workspace. Copy is additive with existing data and will not replace existing data unless clear_existing is specified

parameters:

intent: name of intent to copy

source_username: username for source WCS instance

source_password: password for source WCS instance

source_workspace: workspace id for source WCS instance

target_username: username for target WCS instance

target_password: password for target WCS instance

target_workspace: workspace id for target WCS instance

version: version of WCS instances

clear_existing: boolean to clear existing intent data from target

target_backup_file: backup existing target workspace to this file

example:

from wcs_deployment_utils.intents import copy_intent_data

copy_intent_data(
    intent='order_pizza',
    source_username=CONVERSATION_USERNAME,
    source_password=CONVERSATION_PASSWORD,
    source_workspace=WORKSPACE_ID,
    target_username=CONVERSATION_USERNAME,
    target_password=CONVERSATION_PASSWORD,
    target_workspace=TARGET_WORKSPACE,
    version=VERSION,
    clear_existing=False,
    target_backup_file='backup/ex2.json')

copy_entity_data

wcs_deployment_utils.entities.copy_entity_data

Copy entity data from a WCS workspace to a target workspace

Copy entity data in an additive pattern from a source workspace to a target workspace. copy is additive with existing data and will not replace existing data

parameters:

entity: name of entity to copy

source_username: username for source WCS instance

source_password: password for source WCS instance

source_workspace: workspace id for source WCS instance

target_username: username for target WCS instance

target_password: password for target WCS instance

target_workspace: workspace id for target WCS instance

version: version of WCS instances

clear_existing: boolean to clear existing intent data from target

target_backup_file: backup existing target workspace to this file

example:

from wcs_deployment_utils.entities import copy_entity_data

copy_entity_data(
    entity='pizza_topping',
    source_username=CONVERSATION_USERNAME,
    source_password=CONVERSATION_PASSWORD,
    source_workspace=WORKSPACE_ID,
    target_username=CONVERSATION_USERNAME,
    target_password=CONVERSATION_PASSWORD,
    target_workspace=TARGET_WORKSPACE,
    version=VERSION,
    clear_existing=False,
    target_backup_file='backup/ex3.json')

get_and_backup_workspace

Module: wcs_deployment_utils.util.get_and_backup_workspace

Gets an export of a workspace and stores it locally

parameters:

username: WCS username

password: WCS password

workspace: WCS workspace id

version: WCS API version

export_path: store export at this path

returns:

export: dict representation of WCS workspace

example:

from wcs_deployment_utils.util import get_and_backup_workspace

export = get_and_backup_workspace(
    username=CONVERSATION_USERNAME,
    password=CONVERSATION_PASSWORD,
    workspace=TARGET_WORKSPACE,
    version=VERSION,
    export_path='backup/ex5.json')

Testing

Testing requires pytest.

To execute tests against mock data: python -m pytest -m mock -v

To execute tests against live data: python -m pytest -m live -v

To execute all tests: python -m pytest -v

Live tests will require that credentials are supplied in test/config/test_credentials.json. A sample file is provided.

Planned Roadmap

1. Add counter example functions