System Variables

SCL commands that produce output, (e.g., GET_INPUT) all support the STORE keyword that will save the result in the specified variable. However, the resulting data will also be available in a system variable specific to the command. It is important to note that the system variable is not guaranteed to contain the result data after consecutive SCL commands have executed. If this data is needed later in the bot flow, it should be saved in another local variable.

Below is a list of system variables that contain execution context data. These variables are accessible from SCL code.

AUTH

The AUTH variable captures results from the “CREATE_AUTH” command.

CREATE_AUTH "google"
LOG "Received: ${AUTH}"

CONTEXT.bot

The CONTEXT.bot variable contains context details for the current bot session. The following properties are available:

  • bot_id (string): The ID of the bot (skill) the request belongs to
  • botlet_id (string): The ID of the botlet within the bot the request belongs to
  • callers (list<string>): List of callers of the current botlet where one botlet invokes another botlet
  • share (share): Details about sharing of resources like permissions and other constraints for its use
  • is_action_link (bool): True if the botlet is invoked using an action link
LOG "The bot id is: ${CONTEXT.bot.bot_id}"

CONTEXT.conversation

The CONTEXT.conversation variable contains the context details for the current conversation. The following properties are available:

  • conversation_state (any type): State that is controlled by the conversation controller and form processor
LOG "The conversation id is: ${CONTEXT.conversation.conversation_id}"

CONTEXT.lu

The CONTEXT.lu variable contains the context details for language understanding. The following properties are available:

  • query (string): The input string from the user

  • responses (input.lu.response | list <input.lu.response>) : List of LU responses

    input.lu.response:
    • query (string): The user query
    • score (float): The overall score for intent and slot tagging - falls back to intent’s score
    • intent (intent): List of intent
    • slots (map <string, slot>): List of slots keyed on the name of the slot. It is possible to have multiple slots with the same name
    LOG "The LU score is: ${CONTEXT.lu.responses.score}"
    

CONTEXT.user

The CONTEXT.user variable contains the context details for the user. The following properties are available:

  • name (string): The user’s full name
  • first_name (string): The user’s first name
  • last_name (string): The user’s last name
  • alias (string): The user’s alias, handle or unique identifier
  • title (string): The user’s academic title etc.
  • locales (list<locale>): List of languages the user speaks, ordered by preference
  • time_zone (time_zone): The user’s time zone
  • addresses (list<location>): List of the user’s addresses
  • emails (list<email_address>): List of the user’s email addresses
  • phone_numbers (list<phone_number>): List of the user’s phone phone numbers
  • birth_date (date) : The user’s birth date
  • job_positions (list<job_position>): List of the user’s job positions
  • educations (list<education>): List of the user’s academic qualifications
  • gender (string): The user’s gender
LOG "The user's first name is: ${CONTEXT.user.first_name}"

CONTEXT.channel

The CONTEXT.channel variable contains the context details about the channel. The following properties are available:

  • canvas (string): Capailities of the channel like voice, chat etc
  • channel_type (string): Type of the channel like Cortana, Telegram etc.
  • trace_id (string): ID used for correlating logs between servers for a given request
LOG "The channel type is: ${CONTEXT.channel.channel_type}"

CALL_ERROR

The CALL_ERROR variable contains error details if an error occurred during a “CALL” request. The variable is available in the scope of the ON_ERROR statement.

CALL "com.microsoft.fandango", "get_movie", location=home_address, preferences=user.preferences
ON_ERROR
  SAY "Got an error: ${CALL_ERROR.text}"

CALL_RESULT

The CALL_RESULT variable captures results from the “CALL” command.

CALL "get_location"
RENDER CALL_RESULT.location

ENTITY

The ENTITY variable captures results from the “CREATE” command.

CREATE "$mso.person", first_name="Bart", last_name="Simpson"
SAY "Person: ${ENTITY}"

ENTITY_RESULTS

The ENTITY_RESULTS variable captures results from the “FIND” command.

FIND type_id="location", user_id="self"
SAY "Found: ${ENTITY_RESULTS}"

INPUT

The INPUT variable contains the input action parameters that was provided by the caller of this botlet.

If for example a botlet “movie_database” is defined with action “get_actors” and input parameter name “movie”, the following code would get the movie that it was invoked with:

get_actors:
SET requested_movie = INPUT.movie

The “movie_database” botlet can be invoked with:

CREATE "$mso.media.movie", title="Pulp Fiction" STORE my_movie
CALL "movie_database", "get_actors", movie=my_movie

USER_INPUT

The USER_INPUT variable captures user input from the “GET_INPUT” command.

GET_INPUT
SAY "Input was: ${USER_INPUT}