The automation scenario

You are a developer at your firm who has used Moveworks to solve HR and IT tasks. They are now looking to expand into more IT use cases. ServiceNow is being used by the IT team to track assets for users and often requests fall on them when anyone needs to do a lookup. This usecase guide will walk you through the set up of looking up assets for a user in ServiceNow.

Agentic Automation fundamentals

Connectors
The Authentication mechanism used to connect to a system. Contains the system’s base URL in addition to the API Auth mechanism (OAuth, Basic, etc). Once established, connectors can be reused to create more use cases via API call.

Actions
The invocation of an API endpoint call using a connector. Actions will execute a singular API call - it defines the inputs required to make the API call as well as the expected response.

Compound actions
Controls the execution logic and data mapping of a singular action or sequential actions. Actions can be chained together to pass input and output to and from each action. Compound actions are then published as plugins to become available in the bot.

Plugins
Once a compound action is published as a plugin, the plugin gives the developer the ability to customize the behavior of the compound action in addition to prompts that would make the plugin trigger in-bot.

📘

Actions cannot be published as plugins, only compound actions can.

An action must be referenced in a compound action, and the compound action must be published as a plugin in order to be deployed to the bot

Connectors and Actions

A connector and action can be created at the same time so long as the auth is taken care of when building an action.

Let’s walk through a tutorial on building an action with ServiceNow. In this case we will build the Lookup Asset By Name action.

1. Navigate to the Plugins section on the top bar, choose Actions and select Create

   

2. If you have your own ServiceNow instance, proceed to step 4. If you want to use the Moveworks supplied ServiceNow instance, use the existing connector and proceed to step 8.

3. Click USE EXISTING CONNECTOR

   

   From the dropdown, choose servicenow\_hackathon and click Apply.

   

4. You will need a Base URL for your ServiceNow instance. To find out what this is, go to your ServiceNow instance at the login page and retrieve it from the URL. You may have to logout to retrieve this. You can also retrieve the URL from your registration email from Salesforce.

   

5. Insert the Base URL into the Base URL section of the Action. Make sure you leave the API request as a GET

   

6. Now we will set up the Authorization. Under the Authorization tab choose Basic Auth.

   

7. Then enter the Username and Password for your integration user.

   

8. We are going to be using the Table API in ServiceNow in order to retrieve the account by name. The path for this is /api/now/table/alm_asset insert that into the Endpoint URL section.

   

9. Now navigate to Params. This is where we will pass the query to the API. Add a parameter with a key of sysparm_query and the value will be:

   • assigned_to.name>={{name}}

   Note the name field in double curly brackets {{ }} - this is telling Moveworks it needs to collect the name within the conversation as a required input in order to proceed with this action. It is dynamically populated and collected within the conversation.

   

10. Now navigate to Input Variables - you should see that the name variable has been detected in the API call and it is of type string which is correct. You should also provide a Example Value so that we can finally test our API by passing an example account name to it and validate the schema is correct. You can use Zane as your example value since that name should exist in all non-prod instances of ServiceNow. If you are using your own ServiceNow instance, use a name that you know exists.

    

11. Click the TEST button. If your API call is successful you should see the output in the example below. Click GENERATE FROM RESPONSE - this will populate the Output Schema. There is no need to edit this, but it does help Moveworks understand the format of the output.

    

12. Click SAVE and you will be prompted for some information. First is the Connector Name - this is the name of the connector you will be so that you can use it going forward.

❗️

IMPORTANT Ensure you name the connector in this format `firstname_lastname_servicenow`

This will ensure you know you are using YOUR connector since there are many people at once doing the same exercise in this environment. Similarly, do the same for the API Name as firstname_lastname_lookup_assets, seen below. The API Name field will be the official name of this action.

Ensure you click the Save button again once the dialog below is completely filled out!

Create a compound action for this action

In this exercise we will include the Action in a Compound Action. This will allow us to have control over what values are being returned to the user.

1. Select “Compound Actions” from the left pane and CREATE from the top right.

   

2. Provide a name the in Compound Action Name with the same naming convention we used to build an action. Additionally, add a relevant description to the compound action in Compound Action Description.

   Or copy paste from here:
   firstname_lastname_snow_lookup_asset_compound

   Give a description

   

3. In Script Editor you can type “Command-K” in MacOS or “Control-K” in Windows to bring up the sensing dropdown.

4. Under Expression Templates, choose steps as a high-level element.

   

   Then type “Command-K” / “Control-K” again to choose the action you created

   

   Once completed, you should see something like this:

   

5. We can now start to fill out the other fields. You may want to just cut and paste from the below. Make sure you update the action\_name to your own!

❗️

Note: It is very enticing to select your action from the drop down when you start typing, do not do this, you will need to type out your full action name otherwise it will insert a new action into your yaml script.

steps:
 - action:
     output_key: lookup_assets_result
     action_name: will_davis_lookup_assets
     progress_updates:
       on_complete: Found assets for {{data.name}}
       on_pending: looking up assets for {{data.name}}
     input_args:
       name: data.name
 - return:
     output_mapper:
       results:
         MAP():
           converter:
             display_name: item.display_name
             assigned_date: item.assigned
             quantity: item.quantity
             id: item.sys_id
             cost: item.cost
           items: data.lookup_assets_result.result

Notes on the above syntax:

data: This is the global mechanism to reference data within a compound action.
output_key: this is the variable that will hold the payload of the resulting action. Notice that we are referencing it in the “return” block and returning the Id and Description from the payload

action_id: The unique GUID of the action being called
progress_updates: Notifications from the bot to the user. Notice you can reference fields dynamically within “data” using curly braces ie. {{data.account_name}}

input_args: the input for the action. The input_args can come from the input the bot has collected from the user, or it can be data from a prior action.

output_key: this is the output key for the action, it is so you can call the output from subsequent sections.

return: The data to return from the action. This gives the developer fine control of relevant data to pass as a result of running this compound action.

NOTE: In the return statement the syntax is telling Moveworks that there are multiple items coming back and which items to use to fill the return variables.

6. Tab over to Input Fields. Add a variable called name, a Description of your choosing, Example of “Zane” and a type of string.

   Click Submit

   

Publish this compound action to a plugin

1. Navigate to the Compound Action you just created by finding your “firstname_lastname” naming convention. Click on the 3 dots menu on the top right and click Publish Compound Action to Plugin

   

2. For Use Case Name continue using the naming convention of “firstname_lastname_snow_lookup_asset”. For Short Description, provide a relevant description to the plugin. Leave User consent required before execution unchecked.

   All fields must be filled in in order to proceed with publication of the plugin.

   

3. Click next to the Define Triggering step. Moveworks will show you example prompts or questions a user may ask in order to trigger this. Moveworks is using GenAI here to provide you with example utterances that would trigger this plugin so that you don’t have to. Choose 5 examples that should trigger.

   ❗️

   You will need at least 5 positive examples to move on to the next step.

   You may also see "Failed to Generate Utterance Examples" on your first try - if this happens go ahead and provide your own sample utterance such as "lookup assets for Will" and hit the Refresh button on the right.

   

4. Click next to Set up launch. This determines which user(s) the use case will be launched to. Don’t worry about checking Yes, it’s ready to be launched into production.

   IMPORTANT: Make sure you select Launch to selected emails and manually enter your email in the address below. This will ensure that only you can trigger this use case and it will not be launched to anyone else.

   

5. Click Submit and wait a few minutes for the plugin to become available in the bot.

Test your plugin

1. Navigate to your bot in Teams and try an utterance that should trigger the plugin.

   

Note: some additional names to try that are in the ServiceNow developer instance “Zane”, “Waldo”, “Mac”, “Mabel”, “Lynn”, “Jarvis”, “Felipe” and “Callie”