---
sourceDocument: Xanadu API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# Guided Tours - Client

# Guided Tours - Client {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 5 minutes to read

The Guided Tours API provides methods for launching and stopping guided tours.

This API includes methods used in [Guided Tour Designer](https://servicenow-prod.fluidtopics.net/s5Wi8KMzJtYbuXCnbfDM9Q "REST messages sent to an instance return a specific HTTP response code.").

## Guided Tours - applyListFilter(Function filter_func) {#ariaid-title2}

Sets a function to retrieve filtered tour results when the
`getAllTours()` method is called.
Complete signature includes
`top.NOW.guided_tours.api` preceding the method name.
{#GT-applyListFilter_F__table_pqn_dbs_xhb__entry__3}

| Name | Type | Description |
|-|-|-|
| filter_func | Function | Filter function that takes a single `tour` object from the `tours[]` array returned from `getAllTours()` method. |
[Table 1. Parameters]

{#GT-applyListFilter_F__table_pqn_dbs_xhb} {#GT-applyListFilter_F__table_qqn_dbs_xhb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 2. Returns]

{#GT-applyListFilter_F__table_qqn_dbs_xhb}  
The following example shows basic API usage.

    //create a filter function
    var filtFunction = function(tour) {
       //only return those tours whose name starts with 'my'
       return tour.name.indexOf('my') === 0);
    }

    //apply the filter 
    top.NOW.guided_tours.api.applyListFilter (filtFunction);

    //call the getAllTours method to observe the filtered tours
    top.NOW.guided_tours.api.getAllTours (function(er, tours) {
      if(!er) {
        console.log('The filtered tours are: ');
        console.log(tours);
      }
    });

The following example shows how to use the `options` field on the tour
object to add JSON with custom tour identifiers for reading and filtering tours inside the
`filter_func()` function.

    top.NOW.guided_tours.api.applyListFilter(function(tour) {
           var options = (tour.options)? JSON.parse(tour.options): null;
           return (options && options.my_param) ? (options.my_param == my_value) : false;
    });

## Guided Tours - endTour() {#ariaid-title3}

Stops a currently playing tour. This method silently exits if no tours are
playing.
Complete signature includes
`top.NOW.guided_tours.api` preceding the method name.
{#GT-endTour__table_g5n_3cs_xhb__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 3. Parameters]

{#GT-endTour__table_g5n_3cs_xhb} {#GT-endTour__table_h5n_3cs_xhb__entry__2}

| Type | Description |
|-|-|
| Null |   |
[Table 4. Returns]

{#GT-endTour__table_h5n_3cs_xhb}  

    //create a callback function to end the tour if it starts correctly
    var cbFunction = function(err) {
    	if (err) {
       console.log('Error Occurred');
    }
    	else {
    	   // tour has started so we can call endTour
    	   top.NOW.guided_tours.api.endTour();
    }
    }

    //calling the startTour method so that we can end the tour as soon as it starts
    top.NOW.guided_tours.api.startTour('a297e04b732313007077edcc5ef6a780', 2, cbFunction);

## Guided Tours - events.off(String event_name, Function listener_function) {#ariaid-title4}

Removes an existing event listener.
Complete signature includes
`top.NOW.guided_tours.api` preceding the method name.
{#GT-events.off_S_F__table_iwb_kbs_xhb__entry__3}

| Name | Type | Description |
|-|-|-|
| event_name | String | Event name to be removed from the listener. Valid event names: * tourStarted * tourEnded * tourCompleted * tourFailed * tourAbandoned * tourDismissed * stepStarted {#GT-events.off_S_F__ul_tn1_x4t_yhb} |
| listener_function | Function | Optional. If provided, specified listener function is removed from remaining event listeners attached with that event. If not provided, all listener functions attached to that event are removed. |
[Table 5. Parameters]

{#GT-events.off_S_F__table_iwb_kbs_xhb} {#GT-events.off_S_F__table_jwb_kbs_xhb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 6. Returns]

{#GT-events.off_S_F__table_jwb_kbs_xhb}  

    //create a callback function to handle the result of the api call
    var eventListenerTourStarted = function() {
       console.log('The tour has started'); 
    }
    var eventListenerTourEnded = function() {
       console.log('The tour has ended'); 
    }

    //attaching event listeners for tourStarted and tourEnded Events
    top.NOW.guided_tours.events.on('tourStarted',eventListenerTourStarted);
    top.NOW.guided_tours.events.on('tourEnded', eventListenerTourEnded);

    ...
    //start a tour
    top.NOW.guided_tours.api.startTour ('a297e04b732313007077edcc5ef6a780', 2, cbFunction);
    //As soon as the tour starts the eventListenerTourStarted gets fired
    ...
    top.NOW.guided_tours.api.endTour();
    // eventListenerTourEnded gets fired

    ....

    //removing the event listeners top.NOW.guided_tours.events.off('tourStarted',eventListenerTourStarted);
    top.NOW.guided_tours.events.off('tourEnded', eventListenerTourEnded);

## Guided Tours - events.on(String event_name, Function listener_function) {#ariaid-title5}

Attaches an event listener to a guided tour event.
Complete signature includes
`top.NOW.guided_tours.api` preceding the method name.
{#GT-events.on_S_F__table_iwb_kbs_xhb__entry__3}

| Name | Type | Description |
|-|-|-|
| event_name | String | Event name to be attached to the listener. Valid event names: * stepStarted * tourStarted * tourEnded * tourCompleted * tourFailed * tourAbandoned * tourDismissed {#GT-events.on_S_F__ul_tn1_x4t_yhb} |
| listener_function | Function | Listener to be added. Note: Clear any event listener after it solves its purpose. |
| listener_function.obj | Object | Passed to `listener_function()` by each event in the following format: * For stepStarted events: {tour: '<tour_sys_id>', step: step_num} * For all other events: {tour: '<tour_sys_id>'} {#GT-events.on_S_F__ul_wsr_khs_g3b} JSON parameters: * tour_sys_id: String. Guided tour ID from the Guided Tours \[sys_embedded_tour_guide\] table * step_num: Number. Value between 0 (first step) and `n` (final step) {#GT-events.on_S_F__ul_qfx_nhs_g3b} |
[Table 7. Parameters]

{#GT-events.on_S_F__table_iwb_kbs_xhb}  
The following example shows basic API usage.

    //create a callback function to handle the result of the api call
    var eventListenerTourStarted = function() {
       console.log('The tour has started'); 
    }
    var eventListenerTourEnded = function() {
       console.log('The tour has ended'); 
    }

    //attaching event listeners for tourStarted and tourEnded Events
    top.NOW.guided_tours.events.on('tourStarted',eventListenerTourStarted);
    top.NOW.guided_tours.events.on('tourEnded', eventListenerTourEnded);

    ...
    //start a tour
    top.NOW.guided_tours.api.startTour ('a297e04b732313007077edcc5ef6a780', 2, cbFunction);
    //As soon as the tour starts the eventListenerTourStarted gets fired
    ...
    top.NOW.guided_tours.api.endTour();
    // eventListenerTourEnded gets fired

    ....

    //removing the event listeners top.NOW.guided_tours.events.off('tourStarted',eventListenerTourStarted);
    top.NOW.guided_tours.events.off('tourEnded', eventListenerTourEnded);

The following example shows how to use the `listener_function` parameter
with `obj` as an argument.

    top.NOW.guided_tours.events.on("tourStarted", function (obj){console.log(obj);});

## Guided Tours - getAllTours(Function cb_function) {#ariaid-title6}

Gets a list of tours on the current page from which this method is called. Because this
method is asynchronous, a callback function must be passed to determine operation success and
get a list of tours.
Complete signature includes
`top.NOW.guided_tours.api` preceding the method name.
{#GT-getAllTours_F__table_nrj_bbs_xhb__entry__3}

| Name | Type | Description |
|-|-|-|
| cb_function | Function | Callback function called by `getAllTours()` after attempt to fetch all tours for the current page from which `getAllTours()` method is called. |
| cb_function.err | Object | Points to the error object if any occurred during the operation: `err = { success: false, message: 'string containing the error object' }` Null otherwise. |
| cb_function.tours | Array | List of available tours for the page. If no tours are present on the page, `cb_function.tours` returns undefined. `if(!tours) console.log('No tour present')` |
[Table 8. Parameters]

{#GT-getAllTours_F__table_nrj_bbs_xhb} {#GT-getAllTours_F__table_orj_bbs_xhb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 9. Returns]

{#GT-getAllTours_F__table_orj_bbs_xhb}  

    //create a callback function to handle the result of the API call
    var cbFunction = function(err, tours) {
    	if (err) {
       console.log('Error Occurred');
    }
    	else {
    	    if(!tours) console.log('No tour present')
       else {
          tours.forEach(function(t) {
                   console.log(t);
                 });
              }
    }
    }
    //calling the getTours method
    top.NOW.guided_tours.api.getAllTours(cbFunction);

## Guided Tours - loadPlayer() {#ariaid-title7}

Loads the guided tours player on a page in which guided tours player is not present by
default.
Complete signature:

    NOW.guided_tours.api.loadPlayer()

{#GT-loadPlayer__table_g5n_3cs_xhb__entry__3}

| Name | Type | Description |
|-|-|-|
| None |   |   |
[Table 10. Parameters]

{#GT-loadPlayer__table_g5n_3cs_xhb} {#GT-loadPlayer__table_h5n_3cs_xhb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 11. Returns]

{#GT-loadPlayer__table_h5n_3cs_xhb}

## Guided Tours - startTour(String tour_id, Number step_number, Function cb_function) {#ariaid-title8}

Starts a tour. Because this method is asynchronous, you must pass a callback function
to determine operation success.
Complete signature includes
`top.NOW.guided_tours.api` preceding the method name.
{#GT-startTour_S_N_F__table_wh5_w1s_xhb__entry__3}

| Name | Type | Description |
|-|-|-|
| tour_id | String | Sys ID of the tour from the Guided Tours \[sys_embedded_tour_guide\] table. |
| step_number | Number | Optional. Step at which to start the tour. If not provided (or step number is 0), tour starts from the beginning. |
| cb_function | Function | Optional. Callback function called by `startTour()` method after attempt to launch the tour. |
| cb_function.err | Object | Points to the error object if any occurred during the operation: `err = { success: false, message: 'string containing the error object' }` Null otherwise. |
[Table 12. Parameters]

{#GT-startTour_S_N_F__table_wh5_w1s_xhb} {#GT-startTour_S_N_F__table_xh5_w1s_xhb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 13. Returns]

{#GT-startTour_S_N_F__table_xh5_w1s_xhb}  

    //create a callback function to handle the result of the API call
    var cbFunction = function(err) {
    	if (err) {
       console.log('Error Occurred');
    }
    	else {
       console.log('The tour with tourid=%s was successfully launched', tourId);
    }
    }

    //calling the startTour method
    top.NOW.guided_tours.api.startTour('a297e04b732313007077edcc5ef6a780', 2, cbFunction);