Reuse variables across topics

  • Article

Important

Power Virtual Agents capabilities and features are now part of Microsoft Copilot Studio following significant investments in generative AI and enhanced integrations across Microsoft Copilot.

Some articles and screenshots may refer to Power Virtual Agents while we update documentation and training content.

Variables store your customers' responses to questions from your copilot. For example, you can save a customer's name in a variable called UserName. The copilot can then address the customer by name as the conversation continues.

By default, a variable's value can only be used in the topic where the variable is created. However, it's possible to reuse the same value across topics. For example, a Welcome topic asks for the customer's name and email address. In the Appointment Booking topic, you want the copilot to remember what the customer entered and not ask again.

One way to reuse a variable is to pass the variable between topics. The other way is to make the variable global in scope, and that's what this article covers. Global variables are called that because they're available in all topics across the entire copilot.

Copilot variables apply during a single user session. You specify which variables should be treated as copilot variables to distinguish them from topic-level variables.

Create a global variable

You create a global variable by changing the scope of a topic variable.

  1. Create a variable or use the Variables pane to open an existing variable.

  2. On the Variable properties pane, select Global (any topic can access).

    The variable name is given the prefix Global. to differentiate it from topic-level variables. For example, the variable UserName is displayed as Global.UserName.

    Screenshot showing the Variable Properties pane, with the Global setting highlighted.

  3. Save the topic.

    A global variable's name must be unique across all topics. If there's a conflict, you'll need to rename the variable before saving your topic.

Use global variables

When you're composing a copilot message in a Message node or a Question node, select the {x} icon to view the variables that are available to the topic. Global variables appear in the Custom tab along with any topic variables. Variables are listed in alphabetical order.

Screenshot showing selection of a global variable.

Find all topics using a global variable

You can find where a global variable is defined and what other topics are using it. This can be useful if you're working on a new copilot, or if you have multiple variables and complex topic branching.

  1. Select a global variable in the authoring canvas, or open the Variables pane and select a global variable.

  2. On the Variable properties pane, in the Reference section, select any of the topics where the variable is used to go directly to that topic and node.

    Screenshot showing the list of topics used by a variable in the Variable properties pane.

Lifecycle of global variables

By default, the value of a global variable persists until the session ends. The Clear Variable Values node resets the values of global variables and is used in the Reset Conversation system topic. That topic can be triggered either by redirection or when the user types a trigger phrase such as "Start over." In that case, all global variables are reset.

Set a global variable's value from external sources

If you want to make sure the copilot starts a conversation with some context, you can initialize a global variable with an external source. Let's say that your site requires users to sign in. Since your copilot already knows a user's name, it can greet customers by name before they start typing their first question.

  1. Select a global variable.

  2. On the Variable properties pane, select External sources can set values.

Set global variables in an embedded copilot

If you're embedding your copilot in a simple web page, you can append variables and their definitions to the copilot's URL. Or, if you'd like a little more control, you can use a <script> code block to call and use variables programmatically.

The variable name in the query string of the URL must match the name of the global variable without the Global. prefix. For example, a global variable Global.UserName would be referred to as UserName in the query.

The examples that follow provide a simple declaration for the variables. In a production scenario, you might pass in as the query parameter or variable definition another variable that has already stored the user's name (for example, if you have the user name from a sign-in script).

Append the variables and their definitions to the copilot's URL as query string parameters in the format botURL?variableName1=variableDefinition1&variableName2=variableDefinition2.

For example:

The parameter name is case-insensitive. username=Renata will also work in this example.

Add global variables to a custom canvas

You can also add the variable to a custom canvas.

  1. In the <script> section on the page where you have your copilot, define the variables as follows, substituting variableName1 for the variable name without the Global. prefix and variableDefinition1 for the definition. Separate multiple variables with commas (,).

       const store = WebChat.createStore({}, ({ dispatch }) => next => action => {
     if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
       dispatch({
          type: "WEB_CHAT/SEND_EVENT",
          payload: {
            name: "pvaSetContext",
            value: {
               "variableName1": "variableDefinition1",
               "variableName2": "variableDefinition2"
            }
          },
        });
      }
        return next(action);
    });

  2. In your <script> section, call the store when you embed your copilot, as in the following example where store is called just above where styleOptions is called (you'll need to replace the BOT_ID with your copilot's ID):

    const BOT_ID = "12345-5678";
const theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;

fetch(theURL)
    .then(response => response.json())
    .then(conversationInfo => {
        window.WebChat.renderWebChat(
            {
                directLine: window.WebChat.createDirectLine({
                    token: conversationInfo.token,
                }),
                store,
                styleOptions
            },
            document.getElementById('webchat')
        );
    })
    .catch(err => console.error("An error occurred: " + err));