{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":401,"path":"api-reference/guided_toursAPI.md","title":"Guided Tours - Client","bundle":null,"doc_type":null,"release":"australia","body":"\n# Guided Tours- Client\n\nThe Guided Tours API provides methods for launching and stopping guided tours.\n\nThis API includes methods used in [Guided Tour Designer](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/r_RESTAPIHTTPResponseCodes.md).\n\n**Parent Topic:**[Client API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/api-client.md)\n\n## Guided Tours - applyListFilter\\(Function filter\\_func\\)\n\nSets a function to retrieve filtered tour results when the `getAllTours()` method is called.\n\nComplete signature includes `top.NOW.guided_tours.api` preceding the method name.\n\n|Name|Type|Description|\n|----|----|-----------|\n|filter\\_func|Function|Filter function that takes a single `tour` object from the `tours[]` array returned from `getAllTours()` method.|\n\n|Type|Description|\n|----|-----------|\n|None| |\n\nThe following example shows basic API usage.\n\n```\n//create a filter function\nvar filtFunction = function(tour) {\n   //only return those tours whose name starts with 'my'\n   return tour.name.indexOf('my') === 0);\n}\n\n//apply the filter \ntop.NOW.guided_tours.api.applyListFilter (filtFunction);\n\n//call the getAllTours method to observe the filtered tours\ntop.NOW.guided_tours.api.getAllTours (function(er, tours) {\n  if(!er) {\n    console.log('The filtered tours are: ');\n    console.log(tours);\n  }\n});\n\n```\n\nThe 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.\n\n```\ntop.NOW.guided_tours.api.applyListFilter(function(tour) {\n       var options = (tour.options)? JSON.parse(tour.options): null;\n       return (options && options.my_param) ? (options.my_param == my_value) : false;\n});\n```\n\n## Guided Tours - endTour\\(\\)\n\nStops a currently playing tour. This method silently exits if no tours are playing.\n\nComplete signature includes `top.NOW.guided_tours.api` preceding the method name.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|Null| |\n\n```\n//create a callback function to end the tour if it starts correctly\nvar cbFunction = function(err) {\n\tif (err) {\n   console.log('Error Occurred');\n}\n\telse {\n\t   // tour has started so we can call endTour\n\t   top.NOW.guided_tours.api.endTour();\n}\n}\n\n//calling the startTour method so that we can end the tour as soon as it starts\ntop.NOW.guided_tours.api.startTour('a297e04b732313007077edcc5ef6a780', 2, cbFunction);\n\n```\n\n## Guided Tours - events.off\\(String event\\_name, Function listener\\_function\\)\n\nRemoves an existing event listener.\n\nComplete signature includes `top.NOW.guided_tours.api` preceding the method name.\n\n<table id=\"table_iwb_kbs_xhb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nevent\\_name\n\n</td><td>\n\nString\n\n</td><td>\n\nEvent name to be removed from the listener.Valid event names:\n\n-   tourStarted\n-   tourEnded\n-   tourCompleted\n-   tourFailed\n-   tourAbandoned\n-   tourDismissed\n-   stepStarted\n\n</td></tr><tr><td>\n\nlistener\\_function\n\n</td><td>\n\nFunction\n\n</td><td>\n\nOptional. 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.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\n//create a callback function to handle the result of the api call\nvar eventListenerTourStarted = function() {\n   console.log('The tour has started'); \n}\nvar eventListenerTourEnded = function() {\n   console.log('The tour has ended'); \n}\n\n//attaching event listeners for tourStarted and tourEnded Events\ntop.NOW.guided_tours.events.on('tourStarted',eventListenerTourStarted);\ntop.NOW.guided_tours.events.on('tourEnded', eventListenerTourEnded);\n\n…\n//start a tour\ntop.NOW.guided_tours.api.startTour ('a297e04b732313007077edcc5ef6a780', 2, cbFunction);\n//As soon as the tour starts the eventListenerTourStarted gets fired\n…\ntop.NOW.guided_tours.api.endTour();\n// eventListenerTourEnded gets fired\n\n….\n\n//removing the event listeners top.NOW.guided_tours.events.off('tourStarted',eventListenerTourStarted);\ntop.NOW.guided_tours.events.off('tourEnded', eventListenerTourEnded);\n\n```\n\n## Guided Tours - events.on\\(String event\\_name, Function listener\\_function\\)\n\nAttaches an event listener to a guided tour event.\n\nComplete signature includes `top.NOW.guided_tours.api` preceding the method name.\n\n<table id=\"table_iwb_kbs_xhb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nevent\\_name\n\n</td><td>\n\nString\n\n</td><td>\n\nEvent name to be attached to the listener.Valid event names:\n\n-   stepStarted\n-   tourStarted\n-   tourEnded\n-   tourCompleted\n-   tourFailed\n-   tourAbandoned\n-   tourDismissed\n\n</td></tr><tr><td>\n\nlistener\\_function\n\n</td><td>\n\nFunction\n\n</td><td>\n\nListener to be added.**Note:** Clear any event listener after it solves its purpose.\n\n</td></tr><tr><td>\n\nlistener\\_function.obj\n\n</td><td>\n\nObject\n\n</td><td>\n\nPassed to `listener_function()` by each event in the following format:-   For stepStarted events:\n\n    ```\n{tour: '<tour_sys_id>', step: step_num}\n    ```\n\n-   For all other events:\n\n    ```\n{tour: '<tour_sys_id>'}\n    ```\n\n\n JSON parameters:\n\n-   tour\\_sys\\_id: String. Guided tour ID from the Guided Tours \\[sys\\_embedded\\_tour\\_guide\\] table\n-   step\\_num: Number. Value between 0 \\(first step\\) and `n` \\(final step\\)\n\n</td></tr></tbody>\n</table>The following example shows basic API usage.\n\n```\n//create a callback function to handle the result of the api call\nvar eventListenerTourStarted = function() {\n   console.log('The tour has started'); \n}\nvar eventListenerTourEnded = function() {\n   console.log('The tour has ended'); \n}\n\n//attaching event listeners for tourStarted and tourEnded Events\ntop.NOW.guided_tours.events.on('tourStarted',eventListenerTourStarted);\ntop.NOW.guided_tours.events.on('tourEnded', eventListenerTourEnded);\n\n…\n//start a tour\ntop.NOW.guided_tours.api.startTour ('a297e04b732313007077edcc5ef6a780', 2, cbFunction);\n//As soon as the tour starts the eventListenerTourStarted gets fired\n…\ntop.NOW.guided_tours.api.endTour();\n// eventListenerTourEnded gets fired\n\n….\n\n//removing the event listeners top.NOW.guided_tours.events.off('tourStarted',eventListenerTourStarted);\ntop.NOW.guided_tours.events.off('tourEnded', eventListenerTourEnded);\n\n```\n\nThe following example shows how to use the `listener_function` parameter with `obj` as an argument.\n\n```\ntop.NOW.guided_tours.events.on(\"tourStarted\", function (obj){console.log(obj);});\n```\n\n## Guided Tours - getAllTours\\(Function cb\\_function\\)\n\nGets 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.\n\nComplete signature includes `top.NOW.guided_tours.api` preceding the method name.\n\n<table id=\"table_nrj_bbs_xhb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\ncb\\_function\n\n</td><td>\n\nFunction\n\n</td><td>\n\nCallback function called by `getAllTours()` after attempt to fetch all tours for the current page from which `getAllTours()` method is called.\n\n</td></tr><tr><td>\n\ncb\\_function.err\n\n</td><td>\n\nObject\n\n</td><td>\n\nPoints to the error object if any occurred during the operation:`err = { success: false, message: 'string containing the error object' }`\n\n Null otherwise.\n\n</td></tr><tr><td>\n\ncb\\_function.tours\n\n</td><td>\n\nArray\n\n</td><td>\n\nList of available tours for the page.If no tours are present on the page, `cb_function.tours` returns undefined.\n\n `if(!tours) console.log('No tour present')`\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\n//create a callback function to handle the result of the API call\nvar cbFunction = function(err, tours) {\n\tif (err) {\n   console.log('Error Occurred');\n}\n\telse {\n\t    if(!tours) console.log('No tour present')\n   else {\n      tours.forEach(function(t) {\n               console.log(t);\n             });\n          }\n}\n}\n//calling the getTours method\ntop.NOW.guided_tours.api.getAllTours(cbFunction);\n\n```\n\n## Guided Tours - loadPlayer\\(\\)\n\nLoads the guided tours player on a page in which guided tours player is not present by default.\n\nComplete signature:\n\n```\nNOW.guided_tours.api.loadPlayer()\n```\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\n|Type|Description|\n|----|-----------|\n|None| |\n\n## Guided Tours - startTour\\(String tour\\_id, Number step\\_number, Function cb\\_function\\)\n\nStarts a tour. Because this method is asynchronous, you must pass a callback function to determine operation success.\n\nComplete signature includes `top.NOW.guided_tours.api` preceding the method name.\n\n<table id=\"table_wh5_w1s_xhb\" class=\"parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nType\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\ntour\\_id\n\n</td><td>\n\nString\n\n</td><td>\n\nSys ID of the tour from the Guided Tours \\[sys\\_embedded\\_tour\\_guide\\] table.\n\n</td></tr><tr><td>\n\nstep\\_number\n\n</td><td>\n\nNumber\n\n</td><td>\n\nOptional. Step at which to start the tour. If not provided \\(or step number is 0\\), tour starts from the beginning.\n\n</td></tr><tr><td>\n\ncb\\_function\n\n</td><td>\n\nFunction\n\n</td><td>\n\nOptional. Callback function called by `startTour()` method after attempt to launch the tour.\n\n</td></tr><tr><td>\n\ncb\\_function.err\n\n</td><td>\n\nObject\n\n</td><td>\n\nPoints to the error object if any occurred during the operation:`err = { success: false, message: 'string containing the error object' }`\n\n Null otherwise.\n\n</td></tr></tbody>\n</table>|Type|Description|\n|----|-----------|\n|None| |\n\n```\n//create a callback function to handle the result of the API call\nvar cbFunction = function(err) {\n\tif (err) {\n   console.log('Error Occurred');\n}\n\telse {\n   console.log('The tour with tourid=%s was successfully launched', tourId);\n}\n}\n\n//calling the startTour method\ntop.NOW.guided_tours.api.startTour('a297e04b732313007077edcc5ef6a780', 2, cbFunction);\n\n```\n\n"}}