• Before integrating with ServiceNow, ensure that you have a valid ServiceNow user with access to tables that you want to use in the integration. We recommend setting up a unique ServiceNow user account to be used exclusively for API calls to ServiceNow.

• You can choose to send the feedback to an existing table or create a custom table.

To configure Stages to work with ServiceNow, you will need to obtain the names of the tables and columns you want to send information to, as well as the workspaces's id. Here's how you can do it:

• Log in to your ServiceNow instance and navigate to All > System Definition > Tables.
• In the top search bar, select “Label” and enter the display-name of the table you want to send records to.
• From the search results, click on the table you want to use and take note of the value in the “Name” field at the top of the page. This is the table name.
• To find the name of a specific column, click on the “Columns” tab and search for the column label. Check the “Column name” field to obtain the column's name.
• To find the workspace's id, you can check the URL of your ServiceNow instance. It should be in the following format: instancename.service-now.com/namespace/workspaceId. The workspace Id is the value after the namespace in the URL.

Once you have obtained these values, you can use them to configure the Stages integration with ServiceNow.

To enable, we need to add some XML elements to conf/config.xml. In this example we are sending our feedback to the Task table.

<?xml version="1.0" encoding="UTF-8" ?>
<stages-config>
<!-- Insert this block to your stages config.xml file -->
<feedback-systems>
   <feedback-system name="servicenow">
      <!-- Url to your ServiceNow instance -->
      <host url="https://instancename.service-now.com" ident="servicenow" displayName="Example ServiceNow">
         <!-- Credentials for a (technical) user who has write access to the target table -->
         <property name="user" value="username" />
         <property name="password" value="pass" />
         <!-- Define the workspace the target table is in  -->
         <property name="workspace" value="sow" />
         <!-- Define the table you want to send records to  -->
         <property name="tablename" value="task" />
         <!-- Define the fields you want to send information to  -->
         <!-- See common feedback documentation
        - The "ident" defines the id of the source field in Stages
        - The "target" defines the target field name in ServiceNow  -->
         <attributes>
            <!-- The summary field will always be available and is automatically mapped to "Short Description" in ServiceNow -->
            <attribute ident="description" type="text" target="description" />
            <attribute ident="assignment_group" type="string" target="assignment_group" />
            <!-- ...  -->
         </attributes>
 
        <!-- Assign static values -->
        <custom-attribute-mappings>
          <attribute value="In Progress" target="state" />
        </custom-attribute-mappings>
 
         <!-- Assign stages specific values such as a link back to stages (see common feeedback documentation)-->
         <system-attribute-mappings>
            <attribute source="elementUrl" target="business_impact" />
            <attribute source="creatorFullname" target="created_by" />
            <!-- ... -->
         </system-attribute-mappings>
      </host>
      <!-- Add more hosts of the same feedback system type here -->
   </feedback-system>
</feedback-systems>

This integration supports most String-based ServiceNow field types. Additionally, the reference-types “Reference” and “List” are supported. In case your reference-type field needs a sys_id as input, see the hint-section below.

Many other data types can be created via a String:

For Example:

• Choice will accept a String containing any of the registered Choices.
• Date/Time fields accept a String formatted as a glide_date_time (Format: yyyy-MM-dd HH:mm:ss).

Navigating to the API Explorer (All > REST API Explorer) and selecting POST can be helpful for finding the correct input format for each of the many ServiceNow field types.

To address fields of the ServiceNow Type ’reference’ you need to input a value corresponding to a clolumn that has been defined as the table's reference key. See the ServiceNow documentation for details (https://docs.servicenow.com/bundle/vancouver-platform-administration/page/administer/field-administration/task/t_DefineTheReferenceKey.html).

This section is only relevant if the usual way of working with reference fields (see previous section) doesn't meet your requirements, for example, because the referece key of your table can not be changed to the column you want to use for your feedback integration in Stages.

For columns of type reference, you might need to provide a unique record identifier (sys_id) to link to the referenced record. Since it would be tedious to let the user input a 32-digit sys_id, you can use the targetType property to define an alternative column of the referenced table that will be used to fetch the needed sys_id. (Make sure this column's values uniquely identify the referenced records.)

The targetType has the following format: reference/tablename/inputColumnname - where tablename is the table you want to reference and inputColumnname is the column the user will be inputting instead of the sys_id. Stages will then use the Table API to resolve the input to a valid sys_id. You can also use this strategy for any other field that requires a sys_id as input by defining the targetType property as described.

TargetType Example

In this example, we're using a custom field called “Stages User” (u_stages_user) which we added to the “Users” (sys_user) table in order to populate the “opened_by” field, which references a ServiceNow user.

<system-attribute-mappings>
      <attribute source="creatorUsername" target="opened_by" targetType="reference/sys_user/u_stages_user"/>
</system-attribute-mappings>

The “Stages User” field stores the username in stages, which allows us to fetch the corresponding ServiceNow user record without the need to know any ServiceNow userdata. With a setup like this, we can eliminate the need for specific information about our ServiceNow records when sending feedback from Stages.

• Fields of type List expect input as comma-separated values.

• If invalid input is provided for one or more fields, the record will usually still be created, but you should verify that the data was correctly entered.

• You can create records without providing input to mandatory fields via the API, but the record cannot be edited in ServiceNow before all mandatory fields are filled in.