Worksheet

Follow this guide to make sure you're ready to start building your first Query.

Before you build, we recommend that you have

1. a compatible REST API call in the API Client of your choice
2. a purple chat mock of your desired experience

Get a Compatible REST API

Test the API in an API Client

Every Query in Creator Studio is powered through a REST API, which is a way that systems interact with each other.

Continue once you have an API call working in the API client of your choice.

• Postman
• Microsoft PowerShell
• Linux Shell

During this phase, uncover any access needs or security scopes that are required from the relevant system admin.

Validate Compatibility

Make sure each of the following is true to ensure your API will work with Moveworks.

The API must use a support Authentication mechanism.

Moveworks currently supports

• Basic Authentication (Base64-encoded username & password)
• Header Authentication
• OAuth 2.0 Client Credentials

If you don't see your authentication mechanism, please contact support

The API must have one or fewer user-provided values

Currently, Moveworks can extract up to one value from the user's utterance. These utterances would work since they contain one or fewer user-provided values:

"Remind me what servers I currently administer. I wanted to do a quick health check."

• Here, there are no values to extract. Queries will understand this is about "looking up my servers" and trigger the appropriate API.

"Hey, I'm was trying to verify invoice #829 and wanted to double check the details on the related purchase order PO-20384, could you help me validate the Vendor's billing address?"

• Here, Queries will understand the utterance is about the purchase order (the invoice information is not relevant) and extract PO-20384 as the query.

"Our Customer Success team just got restructured and I now own the ACME Corp account. Can you remind me who our main point of contact is there, I want to send them a welcome gift like I did for Jekyll Industries."

• Here, Queries will understand "there" refers to "ACME Corp" and extract ACME Corp as the query.

The API may accept a user ID

You can use the user's email address or other system identifier. Check your User Configuration in Control Center for a list of systems whose identifiers are supported in your environment.

The API should a JSON dictionary or list

Queries workspace supports APIs that return a JSON response. JSON responses with or without envelopes are both supported.

To prevent security vulnerabilities with non-enveloped JSON responses, we recommended enveloping your APIs.

XML based API responses are not supported today.

🟢 Supported JSON

{
    "data": [
        {
            "id": 1,
            "title": "Record 1"
        }
        ...
    ]
}

✅ Supported JSON (not recommended)

[
    {
        "id": 1
        "title": "Record 1"
    }
    ...
]

❌ Unsupported XML

<data>
  <item>
    <id>1</id>
    <title>Record 1</title>
  </item>
  <!-- ... Add more items here if necessary -->
</data>

Purple Chat Mocks

We recommend producing a quick Purple Chat Mock. This will help keep you oriented as you implement your Query, and set expectations with your co-workers.

Example: Get Holiday Calendar

For the quickstart guide, you will be using a publicly available holiday API to get the holiday calendar for your region, which is a common query for many HR teams.

The relevant API call which answers this query is a POST request:

curl --location 'https://us-central1-creator-studio-demo.cloudfunctions.net/holidays' \
--header 'Content-Type: application/json' \
--data '{
    "year": 2023
}'

Note the following details about your REST API

• Base URL: https://us-central1-creator-studio-demo.cloudfunctions.net
• Endpoint Path: /holidays
• Body: Optional, if blank returns the current year.

Response

{
    "data": {
        "holidays": [
            {
                "date": "2023-01-02",
                "localName": "New Year's Day",
                "name": "New Year's Day",
                "countryCode": "US",
                "fixed": false,
                "global": true,
                "counties": null,
                "launchYear": null,
                "types": [
                    "Public"
                ]
            },
            ...
        ]
    }
}

We will be using this REST API to design a query experience that looks like this:

🎉 You're Ready to Build!

You are now all set to start configuring your Query. Follow along our tutorial in Queries quickstart guide