DocumentationDeveloperAcademyCommunitySupportLogin

ServiceNow Access Requirements

Suggest Edits

The Moveworks bot will directly perform actions in ServiceNow to create, update, and query information about tickets, catalog items, and knowledge base articles.

Actions taken in your ServiceNow instance (ITIL and Workflow)

The Moveworks service interacts with your ServiceNow platform so that the bot can:

  • monitor tickets for autonomous resolution;
  • reach out to an employee when a ServiceNow ticket needs the employee's attention;
  • create tickets to log issues the bot has resolved autonomously;
  • create tickets for issues that require an agent's attention;
  • triage incoming tickets;
  • load ServiceNow Catalog Items and knowledge base articles so that the bot can serve them to employees; and
  • read the ServiceNow user table so that the bot can log and assign issues appropriately.

Service account in Production Instance

To perform the actions listed above, Moveworks needs one account for the bot on your ServiceNow Production instance.

What is this account used for

A dedicated service account in ServiceNow allows the Moveworks service to read and update tickets, and read users, Catalog Items, and KB articles. Create a service account dedicated to Moveworks and share the credentials of this account with your Moveworks Customer Success Engineer. This account must have the following permissions and settings.

Service Account Requirements & Permissions

  • Account Timezone: GMT time zone (no offset)
  • Account Date Format: YYYY-MM-DD
  • Account Time Format: hh:mm:ss
  • Roles/Permissions:
    • Option 1: Use ServiceNow Out of the Box/Standard roles
      • ITIL - Used for ticket CRUD operations (file ticket, add comment, close ticket, etc.)
      • Approval Admin - Used to read approvals, notify users on ServiceNow Approvals, and allow users to approve/deny approval
      • Flow Operator - Used to view flows, flow contexts and its logs
      • Catalog Admin - Used to read ServiceNow Catalog Items system definition and UI policies
      • Ui Policy Admin - Used to read ServiceNow Catalog Items system definition and UI policies
      • Personalize Dictionary - Used to read ServiceNow Catalog Items system definition and UI policies
      • interaction_agent - Optional: Used only for Message Brokering Live Agent Chat functionality
    • Option 2: Use a custom role & Approval Admin role
      • Approval Admin Used to read approvals, notify users on ServiceNow Approvals, and allow users to approve/deny approval
      • Custom Role with access to the following tables:
        • Read/Write access:
          • incident
          • sc_request
          • sc_req_item
          • sc_task
          • sys_journal_field - used for comments
          • new_call (if call tickets are used)
        • Read-Only access:
          • sys_user - used to import user sys_id to take action on their behalf
          • kb_knowledge - used to import knowledge
          • sys_user_group - used for the bot to understand assignment groups
          • sys_choice - used to understand choice options
          • sc_cat_item - used to understand options that appear in choice lists
          • sc_cat_item_producer - used to import record producers
          • sc_catalog - used to import catalog items for Form Finding & skilling
          • sc_category - used to understand Service portal structure and properly filter catalog items
          • sc_cat_item_category - used to understand Service portal structure and properly filter catalog items
          • sc_cat_item_user_criteria_no_mtom - used to understand who cannot access a given catalog item
          • catalog_ui_policy - used to replicate the behavior of catalog item forms when presented to your users in Moveworks
          • catalog_ui_policy_action - used to replicate the behavior of catalog item forms when presented to your users in Moveworks for in-bot form filling
          • catalog_script_client - used to understand forms that have scripts associated with them for in-bot form filling qualification.
          • sys_ui_policy - used to replicate simple UI policies for for in-bot form filling
          • sys_dictionary- used to get display values for column drop downs for in-bot form filling
          • question_choice- used to pull a question and its choices for in-bot form filling
          • item_option_new- used to understand variable and variable set definition of a form for in-bot form filling
          • item_option_new_set- used to understand variable and variable set definition of a form for in-bot form filling
          • sc_item_produced_record - used to understand which tickets were submitted by a form.
          • sys_script_include - used to understand script definition to recommend alternative approaches

Along with the core needs mentioned above, provide the Moveworks service account read access for all tables used in reference field types in catalog items (Reference, Lookup Select Box, List Collector, Lookup Multiple Choice, Select Box).

💡

Note: It is recommended to create a user criteria for the service account that gets assigned to all catalog items. Moveworks will be able to respect user criteria for individuals using the bot, so they can only see resources that they have access to in the service portal. See below for more information.

Additional Read-Only API Access Required

Access to these APIs will allow the Moveworks bot to support filling of Catalog Items within the Moveworks bot and/or Moveworks Web interface.

  • /api/sn_sc/v1/servicecatalog/items/<form_id>
    • Attributes needed: sys_id, variables, picture, categories, catalogs, visible_standalone, sys_class_name, ui_policy, client_script, title, name, short_description, description
  • /api/now/v2/table/sc_cat_item
    • Attributes needed: sys_id, active, hide_sp
  • /api/now/v2/table/item_option_new
    • Attributes needed: default_value, sys_id, question_text, description, mandatory, active, type, choices, lookup_table, lookup_value, reference_qual_condition, variable_set
  • /api/now/v2/table/sc_catalog
    • Attributes needed: sys_id, active, title
  • /api/now/v2/table/sc_category
    • Attributes needed: sys_id, active, title
  • /api/now/v2/table/sys_dictionary
    • Attributes needed: element, display, name
  • /api/now/v2/table/catalog_ui_policy
    • Attributes needed: sys_id, active, catalog_item, variable_set, catalog_conditions, reverse_if_false, order, applies_catalog, global
  • /api/now/v2/table/catalog_ui_policy_action
    • Attributes needed: sys_id, catalog_item, variable_set, mandatory, cleared, disabled, visible, order, ui_policy
  • /api/now/v2/table/sys_db_object
    • Attributes needed: sys_id, name, super_class

Additional Access Required for ServiceNow Message Brokering (Optional)

The APIs below allow the Moveworks bot to support Message Brokering for Live Agent Chat within the Moveworks bot and/or Moveworks Web interface.

Pre-requisites: The Virtual Agent API plugin should be installed.

  • /api/now/table/awa_agent_presence_capacity
    • Permission needed to get the number of Live Agents available in a queue
  • /api/now/table/interaction
    • Permission needed to be able to transfer attachments between an agent and a user.

Service account in Non-Production Instance

A dedicated service account in ServiceNow will need to be created with the same permissions as for the Production service account in the closest clone of the Production instance. Typically this is a non-production Staging or Test instance. This Service account should be a clone of the account in production and have the same sys_id and same name. Ideally, the service account name should resemble the bot name.

🚧

Please clone the following tables from your Production to the Non-Production instances to ensure accurate configuration and testing:

  • sc_cat_item
  • kb_knowledge

What is this account used for

This account is used when the bot is being configured during the IT Testing phase. After launch to all employees, this account is used for testing purposes. The Moveworks Team tests all changes in our platform using this account against the Test/Staging instance before they are deployed.

Moveworks Contact Type

It’s recommended to add a Moveworks-specific contact type so all Incident tickets created by the bot will have the same contact type. This can be called “Moveworks” and later on renamed to be the finalized bot name.

Setting Up OAuth Access

Along with the username & password of the service account, you will need to create an OAuth application to enable OAuth for the Moveworks service account.

  1. Navigate to System OAuth -> Application Registry and select New to create a new OAuth application.

  2. Select Create an OAuth API endpoint for external clients

  3. Name the token as moveworks and then select Submit.

    1. Note: By Default the token will be auto generated when left blank, and be valid for 100 days. Redirect URL and Logo URL are not used, and can be left as https://moveworks.com

  4. Once the OAuth application is created, navigate back to its settings and click on the lock on the right side of Client Secret to view the Client Secret value that was auto-generated.

  5. Securely send the service account Username, Password, Client ID, and Client Secret to your Moveworks Team.

Installing Update Sets

Click here to download and install the Moveworks ServiceNow update sets.

The Moveworks bot can respect user criteria for knowledge articles and catalog items.

To set this up, please install the Moveworks update sets into your ServiceNow non-production and production instances.

After installing the update sets, a new role called moveworks_user is added to your instance. This role will need to be assigned to the Moveworks service account.

For more information on what the update sets contain, see this document.

Updated 3 months ago