SN Pro Tips

View Original

Adding a Guided Setup to Your ServiceNow Application

Tim Woodruff

Introduction

Very often, we’ll find ourselves writing a custom application (whether scoped or global) that requires some “setup” by the admin who installs it. Maybe we’re writing the app to be distributed to multiple ServiceNow customers, each with their own environments and needs; or maybe the app just requires a unique setup process in each instance we promote it to. Whatever the case, I’ve often had cause to want to build my own “guided setup”.
Unfortunately, for some reason, ServiceNow has made it difficult to create a guided setup in our own development instances.
In this article, we’re going to learn how to get around those limitations; then, we’re going to learn how to build a guided setup ourselves!

Setup

There are three important tables relating to Guided Setup:

  • Guided Setup Contents [gsw_content]

  • Guided Setup Information[gsw_content_information]

  • Guided Setup Group [gsw_content_group]

Before we can create our own Guided Setup, we first have to get “write” and “create” access to each of these tables. You could go in and, after elevating to the security_admin role, create all of the necessary ACLs to grant admins access to both operations on each of these tables, but c’mon chum, don’t worry about it. I got you. 😉
Simply download and install the Update Set linked below, and you’ll be all set to move on to the next step and begin building your guided setup.

Update Set to Access Guided Setup Records

  1. Click here to download the Update Set that’ll grant admins in your environment access to the tables related to Guided Setup.

  2. From the Application Navigator in your dev environment, navigate to Retrieved Update Sets.

  3. Scroll to the bottom of the Retrieved Update Sets list, until you see a link below the list that says Import Update Set from XML. Click that link.

  4. Click Choose File and select the XML file you just downloaded, then click the blue Upload button.

  5. Return to the Retrieved Update Sets list, and find the update set you just imported. It’ll have a name beginning with “SNG-Allow Guided Setup Access”. Open that Update Set.

  6. If there is a “Preview” button on the retrieved Update Set, click it and allow the preview to finish.

  7. Click on Commit Update Set.

Create the Guided Setup

Create Root Guided Setup Group

Now that you’ve got access to the Guided Setup tables, let’s start creating our Guided Setup. The first step in doing so, is to create a “root” Guided Setup Group. Guided Setup Groups, you may recall, live in the gsw_content_group table, so let’s begin there.

  1. Navigate to the gsw_content_group table, and click the New button (which should now be visible to you if you’ve installed the above Update Set).

    1. Note: You can also get here by going to the gsw_content table, and clicking New, then clicking on “Content that groups other content” from the interceptor page. Either way works, this way just saves you one click.

  2. Populate the “New record” form for your Guided Setup Group, like so:

    1. Title: Since we’re creating the “root content” right now, this will be the title of your overall Guided Setup. It will show up at the top of the Guided Setup form whenever a user views it. I’m calling my root Guided Setup Group “Example Application Setup”.

    2. Is root content: Set this to true.
      You’ll notice some of the fields on the form change. For example, the “Parent Content” field disappears. This is normal.

    3. Order: Since this is our root content group, set the Order field to 0.

    4. Maximum children to display: This doesn’t really matter all that much, but I set it to 10 for my Guided Setup.

    5. Roles: I recommend setting this to either admin or to your application’s administrative role.

    6. Description: Set this field to something… you know… descriptive. This will be shown below the title on your Guided Setup page.

  3. Save the new Guided Setup Group.

When you’re finished, your Guided Setup Group should look something like this:

Add a Child Group

Once the root content is created, you can follow one of two paths: either add a few steps directly to the root group (works best if you only have a few steps total), or add one or more child groups to which you’ll add the steps. For our example, we’re going to use the more common approach: creating child groups. If you’re just adding content directly to your root content group, you can simply skip this step.

Note: You cannot have a mix of groups and steps in a single Content Group (including your root Content Group).

  1. Scroll to the bottom of of the form for your root Content Group. There, you should see a Guided Setup Contents related list, which - if you installed the Update Set above - should also have a blue New button. Click that button.

  2. We’ll be redirected to an “interceptor” page that asks what kind of content we want to create. Since we’re creating a new child group to live under our root Content Group, click on Content that groups other content.

  3. From here, the process is very similar to when we created the root Content Group, except we don’t check the Is root content checkbox.
    On this form, simply populate the Title and Description fields with whatever you like, and set the Order field to whatever’s appropriate.

    1. For my first Content Group, I usually use an order of 100. For the second, I use 200, and so on. That way, I have plenty of room to slot other Content Groups in-between two existing ones if I realize I need to do that later on, but without having to modify the order value of every other Content Group.

  4. If you want your users to be able to skip this entire content group, leave the Skippable field set to true. If the steps in this Content Group are mandatory, however, then un-check that box. For my application, the steps in this Content Group will be mandatory, so I’m un-checking it.

  5. Save your child Content Group by right-clicking on the gray header, and clicking Save.

Once finished, your child Content Group should look something like this.

Note that the Parent Content and Parents fields are pre-populated, and we’ve left them alone.

Create Guided Setup Content

Whether you’re adding actionable content directly to your root Content Group, or to a child Content Group, navigate to whatever Content Group you’d like to add actionable steps to, and follow the below steps.

  1. Just as in the above section, scroll to the bottom of of the form for the Content Group into which you’d like to add actionable content. There, you should see a Guided Setup Contents related list. Click the blue New button in that related list.

  2. On the Interceptor page, since we’re now adding actionable content, click on Content that navigates users to configuration pages. That should take you to the “New record” form for the gsw_content_information table.

  3. As should be old hat by now, set a meaningful Title, Order, and Article (basically just a “description”).
    If this specific step isn’t mandatory, leave Skippable checked; otherwise, un-check it.

  4. Select an End Point Type. If you just want to give the user some “instructions” and expect them to follow them and then mark the task as complete, you can leave this field set to “— None —”. However, whenever possible, it’s best to guide them straight to the content they’ll need to interact with or update.
    The options in this field are relatively self-explanatory, but feel free to experiment. When in doubt, use Custom and just specify the relative content URL. For my case, I’m having the user set a system property, so I’m setting the End Point Type field to Property.

  5. For most End Point Types, you’ll have to set the End point open mode field. I recommend setting this to Open inline, but feel free to experiment with the different behaviors!

  6. Since I selected an End Point Type of “Property”, I need to specify the Property name.

Note: Sometimes, the first time you select an End Point Type of Property, the Property value field is mandatory. It should not be.
You can work around this annoying behavior by putting anything in that field, saving the form, and then you should be able to clear the field without it being mandatory.
If that doesn’t work, press CTRL+SHIFT+J to open the client-side script executor, and copy/paste the following code. Then, click Run my code to make the field non-mandatory, and you should be able to save the form without specifying a Property value. 

g_form.setMandatory('property_value', false);

Once finished, my Guided Setup step form looked like this:

Linking/Navigating to your Guided Setup

To link to your Guided Setup, you’ll need the root Content Group’s sys_id. You can easily navigate there by clicking through the Parent Content field on any of your Guided Setup Content/Group(s) until you get to the “top”. Once on the root Content Group, right-click the header, and click Copy sys_id.

Assuming the sys_id of your root Content Group is 2319d59d0733201032f0f16c7c1ed0a6, the URL to your Guided Setup’s front-end, is: 

https://YOUR_INSTANCE.service-now.com/$guided_setup.do#/content/2319d59d0733201032f0f16c7c1ed0a6

To add a link to your Guided Setup to your Application Menu in the ServiceNow Application Navigator, simply create a new Module (in the sys_app_module table) under your application’s Application Menu, set the Link type to URL (from Arguments:), and set the Arguments field to $guided_setup.do#/content/<Root Content Group sys_id>.

See this form in the original post
See this content in the original post