Start Package Activity

Overview

The Start Package (start_package) Activity has been implemented to support package nesting in Pia. With this activity, package developers can trigger a second (child) package to run within the first (parent) package so you can reuse components of different packages.

One example scenario where this activity can be used is when a staff member is on holiday and they need all of their emails forwarded to their manager. Here, engineer can first run the Setup Out of Office Package and then run Setup Mail Forwarding Package subsequently. You can implement the Start_package activity to start Setup Mail Forwarding Package right after the Setup mail Forwarding Package.

Another example where this activity may be used is when a client is having VPN issues. Pia will check if the VPN issue is related to VPN not being setup correctly. If the VPN is not setup correctly, Pia will run the VPN setup package within VPN Troubleshooter Package to correctly setup VPN.

The Start Package activity can be located by searching for "Start Package" in the list of activities in the package editor:

Below is the working sample of activity used in a basic package. More examples are available at the bottom of this article.

# Orchestrator package
conditions: 
- name: 'client_filter'
  optMode: 'OptOut'
  category: 'Test Package'

- name: 'chat'
  option_button: 'Test'
  option_text: 'This is a test package'
  option_category: 'Test Category'

steps:

- task: chat_interaction
  inputs:
    text: 'This is a first Package'

- task: start_package
  inputs:
    mode: 'detached'
    ai_class: 'Service Request|Test|Test'

Here the second package is triggered based on the ai_classification that has been defined. The ai_class should match the ai_class assigned to the second package as shown below:

# Orchestrator package
conditions: 
- name: 'client_filter' 
  optMode: 'OptOut'
  category: 'Testing'

- name: 'chat'
  option_button: 'Second Package'
  option_text: 'test'
  option_category: 'test'

- name: 'ai'
  intent: ''
  ticket_class: 'Service Request|Test|Test'

steps:
- task: chat_interaction
  inputs:
    text: 'This is a second package'

Activity Behaviour

The primary behavior of start_package activity is to allow engineers to run one package within another by linking the packages together. When the first package is executed, Pia will check if the current state of the package matches the condition defined for triggering the second package and start the second package based on that.

Once the second package is executed and completed, Pia will either return to executing the first package or complete overall package execution based on the condition defined by the package developer.

If by any chance the second package fails, Pia will fail the first package. You can set Pia to not fail the first package by defining an input property which is mentioned further down in this article. If the property has been defined, Pia will inform the user that the second package has failed or could not run and continue with the execution of first package so that any changes made through the first package is not lost.

Features of the Start Package Activity
The Start Package activity has following additional features that allows you to use the activity in more common scenarios:

1.You can start the second package in two modes: 1.1 Inline : This mode will pause the current package execution, start a second package and resume current package once second package is complete.

You can define the inline mode in the activity as below:

1.2 Detached: This mode will start the second package only after the execution of current package. if you have multiple detached packages linked to current package, only the last detached package will run after Pia completes executing the current paclage. This is because Pia only allows one package activity to be queued to run at the end of current package execution.

You can define the detached mode in the activity as below:

2. You can trigger the second package to start either by specifying the ai_classification or the package_id.

3. The activity allows error handling where you can set the activity to NOT fail if the second (child) package fails to run or is simply not available

An example of each feature above is available at the bottom of this article.

Input Properties

Use properties to modify the behaviour of the activity.

Property Name: mode
Property Options: 'detached' or 'inline'
Property Required: Yes
Property Description: Detached will start new package after current package execution. Inline will pause the current package execution, start a second package and resume current package once second package is complete.

Property Name: ai_class
Property Required: Either ai_class or package_id must be provided
Property Description: This is the ticket Classification of the second package you want to execute. The ai_classification is used in Pia to classify incoming tickets in the format Type|Subtype|Item and suggest packages to run in these tickets based on their classification.

For more information on ai_classification, you can refer to Pia ai classification

Example: Incident|Account|Password Reset

Property Name: package_id
Property Required: Either ai_class or package_id must be provided
Property Description: This is the internal id of the second package you want to execute, you can get this from the package properties popup.

Example: 0a31ab27-a347-43e6-a049-7971b8d42d3a You can find package_id in the package properties named as 'internal_id'.

Property Name: handle_errors_in_package
Property Options: 'true' or 'false'
Default Value: False
Property Required: Yes
Property Description: If this is set to 'true', if the package being started fails or the package is simply not available, the activity will not fail. If this is set to 'false',the activity/package will fail.

Output Properties

Property Name: package_available
Property Description: If this is set to true, the package was available. If this is set to false, the package was not available and could not be started or queued for execution. These values will only be useful if 'handle_errors_in_package' is set to 'true'.

Property Name: package_error
Property Description: If this is set to true, the package caused an error. If this is set to false, the package was successful. These values will only be useful if 'handle_errors_in_package' is set to 'true'.

Examples

Here's an example of the start_package activity being used to start one package from another with inline mode:

Package 1:

# Orchestrator package
conditions: 
- name: 'client_filter'
  optMode: 'OptOut'
  category: 'Test Package'

- name: 'chat'
  option_button: 'First package'
  option_text: 'This is a test package'
  option_category: 'Test Category'

steps:

- task: chat_interaction
  inputs:
    text: 'This is first Package'

- task: start_package
  inputs:
    mode: 'inline'
    ai_class: 'Service Request|Test|Test'

- task: chat_interaction
  inputs:
    text: 'Back to the first Package'

Package 2 :

# Orchestrator package
conditions: 
- name: 'client_filter' 
  optMode: 'OptOut'
  category: 'Testing'

- name: 'chat'
  option_button: 'Second Package'
  option_text: 'test'
  option_category: 'test'

- name: 'ai'
  intent: ''
  ticket_class: 'Service Request|Test|Test'

steps:
- task: chat_interaction
  inputs:
    text: 'This is a second package'

In the above example, Pia will pause Package 1 execution, start Package 2 and resume Package 1 once Package 2 is complete.

In the above example, you can choose to use package_id as an input to start_package activity instead of ai_class.

Package 1 :

# Orchestrator package
conditions: 
- name: 'client_filter'
  optMode: 'OptOut'
  category: 'Test Package'

- name: 'chat'
  option_button: 'First package'
  option_text: 'This is a test package'
  option_category: 'Test Category'

steps:

- task: chat_interaction
  inputs:
    text: 'This is first Package'

- task: start_package
  inputs:
    mode: 'detached'
    package_id: 'ea7079f1-ef95-4d38-a8d3-744ad0fb3add'

Here, the package mode has been changed to 'detached' so Pia will start Package 2 only after Package 1 has finished execution.

If the 'handle_errors_in_package' is set to 'true', Pia will not fail the entire package but only display an error in the activity log and continue with the first package as shown below:

# Orchestrator package
conditions: 
- name: 'client_filter'
  optMode: 'OptOut'
  category: 'Test Package'

- name: 'chat'
  option_button: 'First package'
  option_text: 'This is a test package'
  option_category: 'Test Category'

steps:

- task: chat_interaction
  inputs:
    text: 'This is first Package'

- task: start_package
  inputs:
    mode: 'inline'
    package_id: 'ea7079f1-ef95-4d38-a8d3-744ad0fb3ad'
    handle_errors_in_package: 'true'

- task: chat_interaction
  inputs:
    text: 'Back to the first Package'

Here, the package_id is not correct so the chatbot will display the following error in the activity log:

If the 'handle_errors_in_package' is set to 'false', Pia will fail the entire package as shown below: