REQUEST ITEM CONFIGURATION

OVERVIEW

The Request Item settings allow for the configuration of multiple Request Item types from Service Now to capture selected RITMs from Service Now to be populated into Content Manager.

WARNING

The following instructions are specific to configuring RITMs within Service2CM.

CONFIGURING A NEW RITM TYPE

To create a new RITM for Service2CM to poll, complete the following steps:

Click on the Request Tab in the Service2CM interface
The Request Menu will load as follows
Click on the Configure New RITM Type button
The RITM Type configuration page will load as follows
Configure the RITM options for polling the correct RITMs in Service Now. Please refer to the fields below for more information on each.
Click on the Save button

Note

If the form uses reference type or look-up select boxes form variables. You must have the lookup field tag enabled on the form variable as this will provide Service2CM with the correct path to obtain the display value data to the correct table.

RITM TYPE

Click on the RITM Type dropdown, select a RITM Type. You can search for a RITM type by typing in the dropdown.

The RITM type is the configuration item within Service Now. The RITM type will be prepopulated with all configuration items that can be captured by Service2CM.

RECORD CRITERIA QUERY

The Record Criteria Query is the search criteria of the Service Now API call sent to Service Now to obtain the RITM data.

Note

api/now/table/sc_req_item?sysparam_query= must be added to the start of the query. This will search for records on the sc_req_item (Service Catalog Request Item table). The search query is to be added after the =.

To create a search query please complete the following steps:

Navigate to the Service Now Instance > Requests (or the table you wish to obtain records from)
Click on the Filter button and a set of dropdowns will appear below
Use the dropdowns to create a search to obtain the records you wish to find

Note

It is required to add "Item is [Request Item Type]" to your search query as this will refine your search specifically for the request item type you require. And will allow for the search results to only bring back RITMs of that item type.

Click Run on the desired search when complete
Right-click on the end of the query created and Click Copy query
Navigate in Service Now to REST API Explorer ( this is where the API call is configured)
The REST API Explorer settings are to be set to Retrieve Records from a table (GET).

Ensure the table Name is set to sc_req_item to capture RITMs.

Paste the query into sysparm_query
Type true into sysparam_display_value
Type true into exclude_reference_link

Click on the Send button
Scroll down to Request > HTTP Method / URI
Copy the highlighted section of the URL

Warning

Do not include &sysparm_limit=1 in the query as this will allow for only one record to be returned.

Note

Scrolling down to the Response Body section will give an indication to which records will be returned from the search provided.

Paste the highlighted query into the Record Criteria Query in Service2CM

CONTENT MANAGER RECORD TITLE

The Content Manager Record title is the titling convention that all RITMs stored in Content Manager of the selected Request Item Type.

Service Now metadata can be used within the Record Title by adding placeholders into the title field. All metadata is obtained from the RITM form fields and form variables. Please refer to CONFIGURING PLACEHOLDERS for more information on how to create placeholders.

CONTAINER SEARCH STRING

The Container Search String determines which container RITMs records are to be stored into Content Manager.

The Container Search String requires a Content Manager search in the format of a string.

Containers that are static (All records go into the same container), the following search string can be used: uri:[container URI]

Dynamic containers can use the ServiceNow placeholders to add in Service Now field values to assist in creating a dynamic search string.

For example, using the Employee Number Service Now field, the value from this field can be used within the container and attachment search string to assist with finding the correct Employee container in Content Manager.

Example Container Search String: containerEx:[default:EMP/{EMPLOYEE_NUMBER} and title:Payroll] and title:Employee Payroll

ALTERNATIVELY CONTAIN ATTACHMENTS

By default, all attachments found for the RITM will be contained on the record in Content Manager.

If it is desired that the attachments should be alternatively contained on the RITM in Content Manager, enable this option.

Upon enabling, please select an attachments container search string

ATTACHMENTS CONTAINER SEARCH STRING

The Attachments Container Search String determines which container RITM attachment records are to be stored into Content Manager.

This functionality works the same way as the Container Search String, please see section for configuration.

USE REQ AS CONTAINER

If enabled, RITM's will always look for its associated REQ that has already been transferred into Content Manager and be contained within its parent REQ.

The Container Search String and Generate Container on RITM Creation will be disabled if Use REQ as Container is enabled.

The REQ must already be stored within Content Manager for this feature to successfully transfer. If the associated REQ cannot be found, the RITM will be stored within the fallback container.

REQs can be set up for transferring within the Requests (REQ) tab on the Service2CM interface.

SET RITM STATE ON SUCCESS

To indicate when a RITM has been successful in its transfer to Content Manager, the RITM's state can be updated to a new state to indicate a successful transfer has occurred.

If the RITM still contains additional workflow a custom state will allow for it to process to the next stage (i.e., Transfer Complete), if Closed Complete is not suitable.

SET RITM STATE ON FAILURE

To indicate when a RITM has been unsuccessful in its transfer to Content Manager, the RITM's state can be updated to a new state to indicate a failure has occurred.

This is an alternative to using the Catalog Task if you wish for the RITM's state to be updated instead of the Catalog Task.

It is recommended that custom states are added to the forms you wish to work with that have their own unique states for the transfer of RITMs into Content Manager. This will make it easier to filter within Service Now which RITMs have failed to transfer across.

SET RITM CATALOG TASK STATE ON FAILURE

To indicate when a RITM has been unsuccessful in its transfer to Content Manager, the Catalog Task state can be updated to a new state to indicate a failure has occurred.

The RITM Catalog Task requires the short description of the selected catalog task's state that will be updated on an unsuccessful transfer.

This option is to be used if there is a specific Catalog task in the RITM that requires the state to be updated, for the workflow process to continue after the transfer of the RITM into Content Manager.

Note

The Catalog task must have its state set to OPEN for it to be picked up by Service2CM.

GENERATE CONTAINER ON RITM CREATION

When a new RITM is created in Content Manager a new Container can be created to house the RITM.

This container can be housed on its own (if the containment level is correctly specified) or can be used in conjunction with the containment search string.

If the Containment Search String AND Generate Container on RITM Creation, this will allow for the newly generated container to be housed within the folder found from within the search string.

SEND PDF DOCUMENT TO SERVICE NOW

If toggled on, the PDF document generated will be sent back to Service Now as an attachment on the associated RITM.

PDF Template is the RITM metadata template. The PDF template must be a Word Document that is stored within Content Manager and will be referenced in the PDF Template input using its URI.

PDF File Name is the titling convention for all PDF Metadata documents stored in Content Manager on the selected Request Item Type and will be attached to the associated Request Item in Service Now. It accepts form field and form variable placeholders like Content Manager Record Title.

Metadata can be captured in the PDF template from both form fields and form variables on the RITM.

The PDF template is completely customisable. Using the placeholders, Service2CM will populate the placeholders when a valid value is returned.

Placeholders can be used in tables, or even within paragraphs of text like the example below.

To add in information regarding approvers, include the placeholder {APPROVERS}. This will include a list of all approvers on the RITM and their current status.

For more information in configuring placeholder, please refer to CONFIGURING PLACEHOLDERS.
Attach Updated PDFs as allows for you to select how the PDFs are handled when an updated RITM is passed through to Content Manager.

The following options are available

Set New Revision
Set New Version

SET NEW REVISION

If this option is enabled, Service2CM will create a new revision of the PDF Metadata Document and will be stored on the latest version of the record within Content Manager

SET NEW VERSION

If this option is enabled, Service2CM will create a new version of the PDF Metadata Document and will be stored on a new version of the record within Content Manager

#### SET ATTACHMENT FILENAME

Attachments that are stored on the RITM have the option to provide a unique naming convention for each RITM. If this option is toggled off, Service2CM will use the attachment's actual file name as the attachment record's title in Content Manager.

Placeholders can be used for adding metadata from the form fields and variables of the RITM apart of the attachment file name. For more information in configuring placeholder, please refer to CONFIGURING PLACEHOLDERS.

Note

To declare a placeholder within the template, Use the metadata's name in capital letters, replacing spaces with _ and surrounded in { } brackets,
Example:

{ITEM}
{SHORT_DESCRIPTION}

{SEQ_NUM} is the sequential number placeholder specific for the attachment file name, which will add a number sequence to each attachment created.

STORE RITM METADATA ON CONTENT MANAGER RECORD

If this feature is to be used, a custom additional field must be created for the specified Service Now property that is to be mapped on the RITM.

If the Store RITM Metadata on Content Manager Record is enabled the Metadata fields table will appear.

Using the Service Now Properties dropdown, select the metadata property to capture
Using the Content Manager Fields dropdown, select the matching Content Manager Additional Field
Click on the Add button to add the metadata field association
The associated fields will be added to the table

To delete an association, click Delete (rubbish bin icon) button to remove it from the table.

Click on the Save button

CONFIGURING PLACEHOLDERS

Form Fields Placeholders

To declare a placeholder, use the form field name, as specified by Service Now in capital letters, replacing spaces with _ and surrounded in { } brackets,
Example:

{ITEM}
{SHORT_DESCRIPTION}
{SUGGESTED_APPLICATION_PROCESS}

REST API Explorer and Placeholders

The REST API Explorer can also assist in displaying what information is returned from a RITM. The Response Body will display what the placeholder names used are. Service2CM uses the same placeholder names. Ensure to place all placeholders in { } and written in capital letters.

Please note that form fields and variables can sometimes have a slightly different name to their display name. Using the REST API Explorer will assist in obtaining to correct placeholder name, as Service2CM will use the API call name field name (refer to the image below).

FORM FIELDS AND VARIABLES PLACEHOLDERS

Form variables are the customisable variables added into a RITM form.

All form variables placeholders use the variable's name as shown in ServiceNow Form.
{EMPLOYEE_NUMBER}

If the form variable contains any punctuation, it must be included in the placeholder.
{DO_YOU_REQUIRE_INSTALLATION_AFTER_BUSINESS_HOURS?}