Description
This tool allows you to populate variables on a catalog item or record producer automatically, by simply using a custom URL.
There are a number of reasons why you might want to do this - for example, imagine you have a generic access request catalog item that lets you choose a group, enter the business justification, and request access to that group.
If you then have a knowledge article like “how to get access to [some system]” which tells you to follow a process that involves filling out that access request form, and requesting to be added to a specific group, you might want to include a link that takes you directly to that catalog item, and pre-populates the relevant variable for you!
Implementation
This tool adds to your system, a Variable Set. This variable set contains a catalog client script, but no actual variables (this is expected). The variable set is called “Parse sysparm_variables URI param”.
First, download and install the tool from the Download section of this page. This will install the necessary code and a variable set to add to any catalog item that you’d like to enable this functionality on.
Once you’ve added the variable set to a given catalog item, you can populate any one or more variables in that catalog item, simply by manipulating the URL, as you can see below.
Usage
Once this Update Set is loaded into your instance, and the installed Variable Set has been added to a given Catalog Item, you simply need to add a new parameter to the URL, and the script will automatically populate any variables you specify.
This URI parameter is sysparm_variables. Its value should be set to a JSON-formatted string containing key/value pairs, wherein the key is the variable name, and the value is the value to populate that variable with.
To demonstrate how this works, see the example below.
Each of the examples below, includes two example links: one link to the portal UI, and one to the classic view. Both links use the exact same sysparm_variables URI parameter.
Note: Don’t forget to check out our free “Try in Portal” tool that gives you a quick link to try out a catalog item in the portal UI, just like the existing “Try it” button on catalog items does for the classic UI!
Example
Variables
| Variable | Variable type | Value | Description |
|---|---|---|---|
| example_user_reference | Reference | 5137153cc611227c000bbd1bd8cd2005 | Since this is a reference field, the value is a sys_id. This is the sys_id of a record in the sys_user table, which the variable references. |
| example_text | Single Line Text | That's one hell of a tomato, Steve. | The special characters in this string will be encodeed in the URI, and decoded to populate the correct value in the variable. |
| example_list_collector | List Collector | 9c573169c611228700193229fff72400, 9d385017c611228701d22104cc95c371 |
Since List Collectors contain a comma-delimited array of sys_ids, that's exactly what we'll specify here. |
Parameter value
&sysparm_variables={"example_user_reference":"5137153cc611227c000bbd1bd8cd2005","example_text":"That%27s%20one%20hell%20of%20a%20tomato%2c%20Steve.","example_list_collector":"9c573169c611228700193229fff72400,9d385017c611228701d22104cc95c371"}Note that some characters are being encoded, while others aren’t. I’ve left some characters like the curly braces un-encoded for clarity, and because most browsers will handle encoding these characters automatically, but don’t hesitate to encode them as well! I used this tool to handle encoding the unsafe characters for me.
Final URL
Portal:
https://INSTANCE.service-now.com/sp?id=sc_cat_item&sys_id=b42ad20a3738630090b68cf6c3990e5b&sysparm_variables={"example_user_reference":"5137153cc611227c000bbd1bd8cd2005","example_text":"That%27s%20one%20hell%20of%20a%20tomato%2c%20Steve.","example_list_collector":"9c573169c611228700193229fff72400,9d385017c611228701d22104cc95c371"}Classic UI:
https://INSTANCE.service-now.com/com.glideapp.servicecatalog_cat_item_view.do?sysparm_id=b42ad20a3738630090b68cf6c3990e5b&sysparm_variables={"example_user_reference":"5137153cc611227c000bbd1bd8cd2005","example_text":"That%27s%20one%20hell%20of%20a%20tomato%2c%20Steve.","example_list_collector":"9c573169c611228700193229fff72400,9d385017c611228701d22104cc95c371"}Encoding notes
The contents of the sysparm_variables object should be minimally encoded first as a JSON object, and secondly as a URL.
JSON encoding means you'll need to escape certain characters (such as backslashes) like so:
{"os_root":"C:\\windows"}Notice how I've used two backslashes after "C:" in the value above? This is the escape sequence for a single backslash.
URL encoding means that you'll need to escape certain other characters (such as spaces and ampersands) with URL-encoding sequences like so:
{"name":"Tim%20Woodruff"}Notice how I've used "%20" in place of the space between my first and last name. This is because URLs do not accept spaces (though most browsers handle that for you automatically, which we'll discuss below)
Most modern programming languages (including JavaScript) also have methods for encoding and decoding URLs, so you can take any JSON-encoded string, run it through one of those functions, and use the result in your URL. If you're URL-encoding something with backslashes in it, you'll have to double-escape them - they'll be escaped for the JSON encoding, and again for the URL encoding. For example:
encodeURIComponent('{"program_files_dir":"C:\\\\Program Files (x86)"}');
The above line of code will print the following string:
%7B%22program_files_dir%22%3A%22C%3A%5C%5CProgram%20Files%20(x86)%22%7D
If you look closely, you'll see the URL-encoded backslash character ("%5C") twice, not four times. This is because the "encodeURIComponent()" function interpreted only two escaped backslashes, rather than four unescaped backslashes. That results in the correctly encoded version of the string "C:\Program Files (x86)", because when un-encoded, the two remaining backslashes will be interpreted as, again, a single escaped backslash. If you're not pre-URL-encoding the sysparm_variables object's value, then you only need to escape backslashes once, as mentioned above.
Most browsers will automatically encode URLs with invalid characters, but it's best to be safe and at least encode certain characters. You can manually URL-encode certain characters like spaces (%20) without having to worry about all of the extra bother of double-escaping stuff like backslashes.
Example usage: Simply append the following to the URL of the catalog item in either your service portal, or the classic UI:
&sysparm_variables={"catalog_variable_name":"variable%20value","var_name_2":"second%20variable%20value"}This functionality should function identically for catalog items on both the classic, and the portal UI.