Introduction

Ever wish your guided tours had the timing of Doctor Strange and the subtlety of Black Widow? In this blog, we’ll show you how to call a guided tour on a backend form using a bit of script sorcery—and make sure it only runs once per user. No repetitive pop-ups. No UX chaos. Just a clean, one-time tour drop, like Iron Man delivering a feature update with style.

How will this work

Note: Throughout this blog, I'll be using the term status instead of disable auto launch status. They mean the same thing—just keeping it clean and readable.

• We'll begin by creating a guided tour for any table of your choice. Make sure the tour is set to disable auto launch = true to prevent it from launching automatically.

• Then, we’ll use a Script Include to check the guided tour status for the logged-in user in Guided Tour User Overrides table [sys_guided_tour_user_overrides_list] :

  • If the status is true:
    → This means the tour has already been played for the user.
    → The Script include returns true, indicating no need to launch the tour again.

  • If the status is false:
    → This means the tour hasn't been played yet.
    → The script will first update the status to false, ensuring the tour is not played again in the future for the same user, and then trigger the tour.
    → The Script Include returns false, indicating the tour should now play (just once).

  • If no record exists for the user:
    → We’ll create a new record for the user with the status set to true, ensuring the tour is not played again in the future for the same user.
    → The Script Include returns false, again meaning the tour hasn’t been played before and should play now.

• Then, we’ll use a Client Script to call the Guided Tour Using the Guided Tours API based on conditions

Let’s Get Started

Note: Since this article is about advanced guided tours, the focus will not be on creating tours and adding messages. Instead, the emphasis will be on calling a guided tour using a script and ensuring the tour plays only once for each user.

A. Create a Guided Tour

1. Navigate to Guided Tours from the Application Menu

2. Click on New to create a new Guided Tour on your table form. (Example: Incident)

3. Save the Record and Edit the Form In Designer.

4. Once opened, add your tour data and publish the record.

5. Navigate back to the Guided Tours List and copy the sys_id of the record you have just created.

B. Use Client Script to Call Guided Tours

Script Include

1. Navigate to Script Include

2. Create a new Client Callable Script Include.

3. Copy and paste the code below and save the record.

// Script Include

var guided_tour_helper = Class.create();
guided_tour_helper.prototype = Object.extendsObject(AbstractAjaxProcessor, {
    // check if tour is already played

    check_tours_auto_launch_record: function(tourID, user) { // check if a tour exists or not

        var glideman = new GlideRecord('sys_guided_tour_user_overrides');
        glideman.addEncodedQuery('tour=' + tourID + '^user=' + user);
        glideman.query();

        if (glideman.next()) { // there exists a record 
            return true;
        }

        return false;

    },

    change_tours_auto_launch_status: function(tourID, status) { // change the auto launch status

        var glideman = new GlideRecord('sys_guided_tour_user_overrides');
        glideman.addEncodedQuery('tour=' + tourID + '^user=' + gs.getUserID());
        glideman.query();

        if (glideman.next()) { // there exists a record 
            glideman.disable_autolaunch = status; // set status
            glideman.update(); // update status
        }

    },

    create_tours_auto_launch_status: function(tourID, status, user) { // create new record

        var glideman = new GlideRecord('sys_guided_tour_user_overrides');

        glideman.initialize();
        glideman.user = user;
        glideman.tour = tourID;
        glideman.disable_autolaunch = status;
        glideman.insert();

    },

    check_tours_auto_launch_status: function() {  // checks status of the auto launch of a tour
        var tour_id = this.getParameter('tour_id');

        var glideman = new GlideRecord('sys_guided_tour_user_overrides');
        glideman.addEncodedQuery('tour=' + tour_id + '^user=' + gs.getUserID() + '^disable_autolaunch=true');
        glideman.query();

        if (glideman.next()) { // if tour is already played
            return true;
        } else { // if tour is not yet played or record doesn't exists

            var recordExists = this.check_tours_auto_launch_record(tour_id, gs.getUserID());

            if (recordExists) {
                this.change_tours_auto_launch_status(tour_id, true);
            } else {
                this.create_tours_auto_launch_status(tour_id, true, gs.getUserID());
            }

        }


        return false;





    },
    type: 'guided_tour_helper'
});

Client Script

1. Navigate to the table on which your tour is created. (Example Incident)

2. Create an OnLoad Client Script On The Table.

// Client Script

function onLoad() {

    var tourId = '236e7190c30d6a50c9cebe1d05013149'; // sys_id of the tour you have just created

    var isTourAlreadyPlayed = false;

    var gax = new GlideAjax('global.guided_tour_helper');
    gax.addParam('sysparm_name', 'check_tours_auto_launch_status');
    gax.addParam('tour_id', tourId);
    gax.getXMLAnswer(function(answer) {
        isTourAlreadyPlayed = answer;
        if (isTourAlreadyPlayed == 'false') {

            try {

                var cbFunction = function(err) {
                    if (err) {
                        // console.log('Error Occurred');
                    } else {
                        // console.log('The tour with tourid=%s was successfully launched', tourId);
                    }
                }

                // Loading the player to play tour
                NOW.guided_tours.api.loadPlayer();

                //calling the startTour method
                top.NOW.guided_tours.api.startTour(tourId , 0, cbFunction);

            } catch (err) {
                // console.clear();
                // console.log(err);
            }
        } else {

            //alert('Tour was already Played');
            return false;

        }
    });

}

Output

Next Steps:

In the upcoming section, I’ll show you how to manually call guided tours on backend forms using a script.

Why would you need this? Well, imagine a user or agent accidentally skipped the tour and later wants to revisit it. We’ll cover exactly how to bring that tour back on demand—because helpful guidance should never be one and done (**Like this article 😂).