PPM Chatbot

PPM Chatbot is a program that can imitate a human conversation with PPM users by using text chat. Through chatting with PPM Chatbot, you can automate some PPM-related activities without opening PPM.

PPM Chatbot helps save your time that could be allocated to other areas that matter more, and reduce factors of project failure.

Note: This feature is not supported if your PPM runs on a PostgreSQL database.

In this topic:

What PPM Chatbot can automate

Theoretically, PPM Chatbot can automate anything that can be performed by calling PPM Web services.

Main work categories where PPM Chatbot could be useful is the automation of routine tasks, data processing, and analysis. Such activities include but are not limited to:

  • Creating project risks
  • Creating project issues
  • Creating tasks
  • Assigning tasks
  • Submitting time sheets
  • Proposing ideas (requests)

Back to top

How PPM Chatbot works

PPM integrates with a Natural Language Processing (NLP) tool to identify intents, retrieve responses, and perform actions. PPM Chatbot acts as the message carrier between PPM and PPM users.

Process overview

  1. A PPM user sends a message to PPM Chatbot in Microsoft Teams.
  2. The NLP tool converts the natural language into structured data.

  3. PPM processes the structured data:

    • If more information is needed, it prompts PPM Chatbot to continue the conversation with the user.
    • If all required information is available, it performs the action.
  4. PPM Chatbot returns the action result to the user in natural language.

Back to top

Supported Natural Language Processing (NLP) tools

PPM Chatbot supports the following NLP tools:

  • Rasa
  • Embedded NLP model (available for 25.2 and later)

You can choose only one NLP tool to use.

  • If you start to use PPM Chatbot in 25.2 and later, the embedded NLP model is used by default.

  • If you already use PPM Chatbot in an earlier version, after the upgrade to 25.2, Rasa remains the default.

Switch to the embedded NLP model

To switch from Rasa to the embedded NLP model:

  1. Clear the values of the RASA_SERVER and RASA_JWT_SECRET parameters in the server.conf file.

  2. Update the bot endpoint address to use the one for embedded NLP. For details, see Embedded NLP.

  3. Register the bot in PPM. For details, see Register the bot in PPM (embedded NLP only) .

Back to top

Requirements to work with PPM Chatbot

To work with PPM Chatbot, the following requirements must be met:

  • PPM Chatbot only supports Microsoft Teams as the chat tool.

  • The Enable PPM Chatbot feature toggle is turned on.

  • You have the Intent Manage access grant.

  • (For Rasa only) There is a user (it can be any user) in the system that has the Rasa Webhook access grant.

  • Download the sample intents, report types, and special commands from the PPM Marketplace.

Back to top

Set up PPM Chatbot (admin task)

This section describes the tasks for admins to set up PPM Chatbot.

Set up Microsoft Teams bot

  1. Use the Microsoft Teams Developer Portal to create an app and add a Bot feature to the app. For details, see the Microsoft Learn Documentation.

  2. Note down the following bot details:

    • Bot ID: Generated automatically when you create the bot.

    • Client secret: On the bot's Client secrets page, click Add a secret to generate a client secret.

  3. On the bot's Configure page, set the Endpoint address based on the NLP tool:

    NLP tool Endpoint address
    Embedded NLP

    • Single-instance deployment:<PPM BASE_URL>/itg/ms-bot/api/messages

    • Cluster deployment:<PPM SERVICE_NODE_URL>/itg/ms-bot/api/messages

    Rasa

    <web_sever_mapped_to_rasa_server>/webhooks/botframework/webhook

    Remember to replace the Rasa server URL with the mapped web server URL.
  4. Publish the app to your organization in Microsoft Teams.

Register the bot in PPM (embedded NLP only)

To enable communication between Microsoft Teams bot and PPM, register the bot in PPM:

  1. Click the Administration button in the masthead.

  2. From the Administration menu, select Integrations > Chatbot Management.

  3. On the Chatbot Intents page, click Settings.

  4. In the Chatbot Settings dialog box, provide the following:

    • Bot ID: The ID of your Microsoft Teams bot.
    • Client Secret: The client secret of your Microsoft Teams bot.
  5. Click Save.

Map Microsoft Teams users to PPM users (RASA only)

When a user interacts with PPM Chatbot, PPM matches the their Teams account (typically an email address) to a PPM user with the same email. This mapping allows PPM to perform actions on behalf of the user.

Back to top

Customize PPM Chatbot use cases (admin task)

PPM provides these sample use cases of PPM Chatbot: create project risks, create project issues, and copy time sheets. You can customize them to automate the same actions or define new use cases.

Here are the general steps to customize your PPM Chatbot use cases:

  1. Define an intent for your use case. For details, see Define an intent.

  2. Define a report type to associate with the intent. For details, see Define a report type.

  3. Define a special command for the report type. For details, see PPM Chatbot.
  4. Train the intent. For details, see Train PPM Chatbot (admin task).

Define an intent

Intents represent user goals when interacting with PPM Chatbot. PPM Chatbot is triggered by the intents it receives. Intents determine how PPM Chatbot interacts with users and whether the interaction is successful.

You can:

  • Create an intent from scratch.
  • (Available for 25.2 and later) Migrate intents from another instance using the kMigratorExtract.sh and kMigratorImport.sh scripts. For details, see kMigratorExtract.sh and kMigratorImport.sh.

To create an intent:

  1. Click the Administration button in the masthead.

  2. From the Administration menu, select Integrations > Chatbot Management.

    If you have imported sample intents, they are displayed.

    You can use the greeting-type sample intents directly. You can modify them but cannot delete them.

    Other action-oriented sample intents such as "Create Project Risk" allow both modifications and direct use.

  3. Click New to create a new intent.

    You can only create action-oriented intents.

    Field Description
    Intent Name What you want PPM Chatbot to do.
    Description Give more details about the intent.
    Reference Code PPM will auto-fill the reference code based on your intent name. It is used for PPM to uniquely identify the intent.
    Enabled

    Whether or not you want to enable the intent.

    We recommend that you do not enable the intent until you are sure of everything defined by the intent.
    Sample User Expressions

    Add examples of what users that have the intent might say to PPM Chatbot.

    If Rasa finds what a user says to PPM Chatbot matches one of the examples, PPM Chatbot will recognize the intent and be triggered.

    For example, if your intent is to create project issues, you may add the sample user expressions such as:

    • Can you please create an issue for me?
    • I'd like to create an issue.
    • Submit an issue
    • I want to create a project issue.
    Report Type

    Associate a report type as the conversation template. Once triggered by the intent, PPM Chatbot will chat with users as defined by the associated report type.

    For details, see Define a report type.
  4. Click Create.

Define a report type

As the conversation template of intents, report types defined for intents are used to control how PPM Chatbot interact with users, including:

  • Which information PPM Chatbot should retrieve from users
  • The exact questions asked to obtain the information
  • The sequence of the questions

To define a report type for an intent:

  1. Create a report type. For details, see Create and configure report types.

  2. Make sure you follow the rules as below:

    Report Type Element Rule
    Fields

    • Which fields must be added?

      The fields required by the request type related to the intent must be added.

      For example, for the intent "create project issues", its related request type is Project Issue, and the request type makes the fields "Project", "Priority", "Description", and "Date Identified" required fields, then the intent's associated report type should at least add these four fields.

      Optionally, you can add other non-required request type fields as the report type fields, such as "Due Date".

    • Should a report type field have the same attributes (such as field name, token, and validation) as the corresponding request type field?

      A report type field should have the same validation as the corresponding request type field. The other attributes do not have to be the same.

    • How to define the exact questions that PPM Chatbot will ask to get the field values?

      Enter the questions as the descriptions of the report type fields.

      For example, for the request type field "Project", its counterpart report type field "Project Name" (it could be other names) can define its description as "Would you tell me your project name?" This will be exactly what PPM Chatbot will ask users.
    Layout

    The sequence of the report type fields will be the sequence of the questions that are defined as descriptions of the fields. If two fields are in the same line, it goes from the left to the right, and then to the next line.

    For example, if the field "Project Name" is on the top, the question "Would you tell me your project name?" will be asked first.
    Command

    The special command added in a report type for an intent is used to perform an action.

    For references, check the sample spacial commands.

Back to top

Train PPM Chatbot (admin task)

Train PPM Chatbot so it can understand and act on your intents correctly.

When to train

Train PPM Chatbot whenever:

  • You add, remove, or edit an intent. Your changes take effect only when PPM Chatbot is trained successfully.
  • The report type associated with an intent changes.

How to train

On the Chatbot Intents page, click Train to update PPM Chatbot with all current intents.

Back to top

Start a conversation with PPM Chatbot (end users)

Learn from your admin which tasks PPM Chatbot can automate and then chat with it to complete those tasks.

To interact with PPM Chatbot:

  1. Add PPM Chatbot to Microsoft Teams.
  2. Start to chat with PPM Chatbot.
  3. (For embedded NLP) If your Microsoft Teams account is not linked to your PPM account, PPM Chatbot prompts you to link them. Click Link Accounts in the conversation to complete the process.

  4. To end a conversation, send one of the following (case-insensitive): "restart conversation", "cancel conversation", or "quite". You can then start a new conversation.

Back to top