{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":606,"path":"api-reference/scripts/c_ScriptIncludes.md","title":"Script includes","bundle":null,"doc_type":null,"release":"australia","body":"\n# Script includes\n\nScript includes are used to store JavaScript that runs on the server.\n\nCreate script includes to store JavaScript functions and classes for use by server scripts. Each script include defines either an object class or a function.\n\nConsider using script includes instead of global business rules because script includes are only loaded on request. See [Privacy settings on Glide AJAX enabled script includes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/scripts/c_ScriptIncludes.md) and [Discovery script includes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/scripts/c_ScriptIncludes.md) for more information.\n\nFor additional examples of scripts, see [Useful scripts](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/scripts/usefulScripts.md).\n\n**Parent Topic:**[Server-side scripting](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/scripts/c_ServerScripting.md)\n\n## Script include form\n\nScript includes have a name, description, and, script. They also specify whether they are active or not, and whether they can be called from a client script. View existing or create a new script include using the Script Include form.\n\nTo access script includes, navigate to **All** > **System Definitions** > **Script Includes**.\n\n\n
\n\nField\n\n\n\nDescription\n\n
\n\nName\n\n\n\nThe name of the script include. If you are defining a class, this must match the name of the class, prototype, and type. If you are using a classless \\(on-demand\\) script include, the name must match the function name.\n\n
\n\nAPI Name\n\n\n\nThe internal name of the Script Include. Used to call the Script Include from out-of-scope applications.\n\n
\n\nGlide AJAX enabled \\(or Client callable\\)\n\n\n\nThe script include is available to client scripts, list/report filters, reference qualifiers, or if specified as part of the URL. Glide AJAX enabled script includes are invoked from `GlideAjax` and require that users satisfy an ACL associated with the script include. When selected, the **Access Controls** Related Link is available. See [Privacy settings on Glide AJAX enabled script includes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/scripts/c_ScriptIncludes.md) for more information.\n\n
\n\nMobile callable\n\n\n\nThe script include is available to client scripts called from mobile devices.\n\n
\n\nSandbox enabled\n\n\n\nThe script include is available to scripts invoked from the script sandbox, such as a query condition.**Important:** Script includes should only be made available to the script sandbox if necessary.\n\nFor information about the script sandbox, see [Script sandbox evaluator](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/scripts/script-sandbox.md).\n\n
\n\nApplication\n\n\n\nThe application where this script include resides.\n\n
\n\nAccessible from\n\n\n\nSets which applications can access this script include:\n\n- **All application scopes**\n\nCan be accessed from any application scope.\n\n- **This application scope only**\n\nCan be accessed only from the current application scope.\n\n\n
\n\nActive\n\n\n\nEnables the script include when selected. Deselect the active field to disable the script include.\n\n
\n\nDescription\n\n\n\nProvides descriptive content regarding the script include.\n\n
\n\nScript\n\n\n\nDefines the server side script to run when called from other scripts.The script must define a single JavaScript class or a global function. The class or function name must match the **Name** field.\n\n
\n\nPackage\n\n\n\nThe package that contains this script include.\n\n
\n\nCreated by\n\n\n\nThe user who created this script include.\n\n
\n\nUpdated by\n\n\n\nThe user who most recently updated this script include.\n\n
\n\nProtection policy\n\n\n\nSets the level of protection for the script include:\n\n- **None**\n\nAllows anyone to read and edit this downloaded or installed script include.\n\n- **Read-only**\n\nAllows anyone to read values from this downloaded or installed script include. No one can change script values on the instance on which they download or install the script include.\n\n- **Protected**\n\nProvides intellectual property protection for application developers. Customers who download the script include cannot see the contents of the script field. The script is encrypted in memory to prevent unauthorized users from seeing it in plain text.\n\n\n
\n\nRelated lists on the form view:\n\n
\n\nVersions\n\n\n\nShows all versions of the script include. Use this list to compare versions or to revert to a previous version. See [Versions](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/application-development/c_Versions.md).\n\n
\n\nAccess Controls\n\n\n\nBecomes available when the **Glide AJAX enabled** is selected and is hidden from standard script includes. Use to protect a script include against unauthorized use when public access is not granted.\n\n
## Use script includes\n\nScript includes are found under System Definition or System UI. You can call existing script includes from a script or create a new script include.\n\nTo create an entirely new script include, you can follow the format of any of the existing script includes. In this example, the name of your script include is NewInclude and there is a single function called `myFunction`. It is important that the name of the script include match the name of the class, prototype, and type. When you create a new script include and give it a name, the system provides a code snippet with the class and prototype properly set up.\n\n```javascript\nvar NewInclude =Class.create();\n \nNewInclude.prototype={\n initialize :function(){},\n \n myFunction :function(){},\n \n type :'NewInclude'};\n```\n\nYou could then use the `myFunction` line like this:\n\n```javascript\nvar foo =new NewInclude();\nfoo.myFunction();\n```\n\n## Glide AJAX enabled script includes\n\nGlide AJAX enabled Script Includes make the script include available to client scripts, list/report filters, reference qualifiers, or if specified as part of the URL.\n\n### Before you begin\n\nRole required: admin\n\n### Procedure\n\n1. Navigate to **System Definition** > **Script Includes**.\n\n2. Select **New** or select an existing script include for viewing or editing.\n\n See [Use script includes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/scripts/c_ScriptIncludes.md) for additional information on writing script includes.\n\n3. Complete the form and select the **Glide AJAX enabled** option.\n\n A role selector pops up to select a user role and automatically create an Access Control entry. Select a user role and click **OK**.\\[Omitted image \"role-selector-ccsi.png\"\\] Alt text: Select a user role window.\n\n **Note:** To disable the role selector window, set the glide.script.ccsi.enable\\_acl\\_create\\_ux to **false**.\n\n A script include record with a role-based Access Control is created. The Access Control Related Link becomes available with the selection of the **Glide AJAX enabled** check box.\n\n\n### Privacy settings on Glide AJAX enabled script includes\n\nPrivacy settings for Glide AJAX enabled script includes determine who can access a Glide AJAX enabled script include.\n\n#### Private privacy-setting\n\nThe private privacy-setting means that guests who access public pages cannot access the Glide AJAX enabled script-include. A private script cannot be executed by a non-logged-in user.\n\n#### Public privacy-setting\n\nA public privacy-setting means that the client script can be executed by non-logged-in users that create an appropriate HTTP request. This can create a security problem if the client script provides confidential information.\n\nThe following script includes remain public by default because [Make UI pages public or private](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/t_MakeAPagePublic.md) need to access them:\n\n- GlideSystemAjax\n- SysMessageAjax\n- KnowledgeMessagingAjax\n- KnowledgeAjax\n- PasswordResetAjax\n\n#### Set privacy on all Glide AJAX enabled script includes\n\nChange the privacy setting on all Glide AJAX enabled script includes.\n\nTo provide further control over all Glide AJAX enabled script includes, administrators can add the glide.script.ccsi.ispublic property. This property changes the visibility of Glide AJAX enabled script includes by making them all public or private. Configure the property as follows:\n\n|Title|Property|\n|-----|--------|\n|Name|glide.script.ccsi.ispublic|\n|Type|true\\|false|\n|Value|false|\n\n**Note:** To learn more about this property, see [Require authentication by default for client-callable script includes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/sc-privacy-on-client-callable-script-includes.md) in Instance Security Hardening Settings.\n\n#### Change privacy on a single Glide AJAX enabled script include\n\nChange the privacy setting for a single Glide AJAX enabled script include by adding the isPublic\\(\\) function.\n\nThe isPublic\\(\\) setting takes precedence over the **glide.script.ccsi.ispublic** property. For example, if the property is set to **false**, making all Glide AJAX enabled script-includes private, and a script sets isPublic\\(\\) to **true**, the script is public.\n\nTo change the privacy for a single Glide AJAX enabled script include, add the following method to the script include:\n\n```javascript\nisPublic:function(){return[true/false];},\n```\n\nMake the NewInclude client script private.\n\n```javascript\nvar NewInclude =Class.create();\n \nNewInclude.prototype={\n initialize:function(){},\n \n myFunction:function(){//Put function code here},\n isPublic:function(){return false;},\n \n type:'NewInclude'};\n```\n\n#### Security on Glide AJAX enabled script includes\n\nProtect your Glide AJAX enabled script includes against unauthorized use. For all records which are created a customer application, recommendations display that may help reduce security risk.\n\nWhen creating a Glide AJAX enabled script include, the system displays the following security recommendations if they have not yet been configured:\n\n- Add or define an Access Control, unless the script include has public access.\n- Use GlideRecordSecure instead of GlideRecord API for better security, if the script queries the database.\n\n **Note:** To disable the security recommendation messages, set the property glide.script.ccsi.customer\\_scoped.security\\_msgs\\_enabled to **false** in the sys\\_properties table. The default value is set to **true**.\n\n\nSee [Instance Security Hardening Settings](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-security/security-hardening-settings.md) for additional information on security compliance.\n\n## Discovery script includes\n\nDiscovery script includes define JavaScript classes that you can use to accomplish Discovery tasks.\n\n**Note:** Users with discovery\\_admin role can write script includes. Follow best practices for server-side and client-side scripting to prevent security issues. See knowledge article [KB0550828](https://support.servicenow.com/kb_view.do?sysparm_article=KB0550828) for more information.\n\n### Using GlideRecordUtil to Work with GlideRecords\n\nGlideRecordUtil is a utility class that provides methods that are useful for working with GlideRecords during Discovery. Refer to [GlideRecordUtil](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_GlideRecordUtilAPI.md) for descriptions of available methods.\n\n### Getting a GlideRecord Instance\n\nTo get a GlideRecord instance for a given configuration item, and of the correct class and table, use the getCIGR\\(sys\\_id\\) method. For example, the following code gets the GlideRecord of a CI with the sys\\_id of 2dfd7c8437201000deeabfc8bcbe5d56:\n\n```javascript\nvar now_GR = new GlideRecordUtil().getCIGR(\"2dfd7c8437201000deeabfc8bcbe5d56\");\n```\n\nTo retrieve any hierarchical table without knowing its class type, use the getGR\\(base\\_table, sys\\_id\\) method. For instance, to get a GlideRecord for a computer class CI, you might have to distinguish whether it is a computer class, Windows server, or Linux server class. Using this method guarantees a GlideRecord with the correct class. Different classes have different attributes. In this use case, a Windows server has attributes different from a Linux server. The following example shows how to get a GlideRecord in the correct class with its attributes.\n\n```javascript\nvar now_GR = new GlideRecordUtil().getGR( \"cmdb_ci_computer\", \"2dfd7c8437201000deeabfc8bcbe5d56\");\n```\n\n### Getting All the Fields In a GlideRecord\n\nThe getFields\\(now\\_GR\\) method returns a JavaScript object, such as a hashmap, of all the fields or attributes that exist in a given GlideRecord.\n\n```javascript\nvar now_GR = new GlideRecordUtil().getGR(\"cmdb_ci_computer\", \"2dfd7c8437201000deeabfc8bcbe5d56\");\nvar fields = new GlideRecordUtil().getFields(now_GR);\ngs.log(fields.join(\" \")); // List all the fields that are in a computer CI\n```\n\n### Populating GlideRecord Object Fields\n\nThe populateFromGR\\(hashmap, gr, ignore\\) method enables you to take a GlideRecord object and populate its fields and values into a JavaScript object. The third argument \\(*ignore*\\) is an optional JavaScript object that enables you to exclude certain fields. For example, you may not care about **sys\\_created\\_by** or **sys\\_updated\\_by** fields in a GlideRecord.\n\n```javascript\nvar objectToPopulate = { }; \nvar now_GR = new GlideRecordUtil().getGR(\"cmdb_ci_computer\", \"2dfd7c8437201000deeabfc8bcbe5d56\"); \nvar ignore = {\"sys_created_on\": true, \"sys_updated_by\": true}; \nnew GlideRecordUtil().populateFromGR(objectToPopulate, now_GR, ignore); \n// Now the objectToPopulate contains field/value pairs from the computer GlideRecord\n```\n\nThe mergeToGR\\(hashmap, gr, ignore\\) method enables you to populate a GlideRecord with a field/value-paired object. The ignore argument stops specified fields from being updated. The following code example updates a computer record's **name** and **os** fields, but does not update the **sys\\_created\\_by** field:\n\n```javascript\nvar now_GR = new GlideRecordUtil().getGR(\"cmdb_ci_computer\", \"2dfd7c8437201000deeabfc8bcbe5d56\"); \nvar obj = {\"name\": \"xyz\", \"os\": \"windows 2000\", \"sys_created_by\", \"aleck.lin\"};\nvar ignore = {\"sys_created_by\": true}; \nnew GlideRecordUtil().mergeToGR(obj, gr, ignore);\ngr.update();\n```\n\n### Getting Table Hierarchies\n\nThe getTables\\(table\\) method returns a list of table hierarchies, as shown in the following example:\n\n```javascript\nvar tables = new GlideRecordUtil().getTables(\"cmdb_ci_linux_server\");\ngs.log(tables.join(\",\")); \n// The result would be \"cmdb_ci, cmdb_ci_computer, cmdb_ci_server, cmdb_ci_linux_server\".\n```\n\n### Using DiscoveryException and AutomationException\n\nWhen writing Discovery sensors and sensor-related scripts, you may want to use DiscoveryException or AutomationException to indicate that an exception has come from Discovery.\n\nThe DiscoveryException script include extends AutomationException, which extends the GenericException class. The following example uses DiscoveryException to throw an exception:\n\n```javascript\nfunction foo() { \n if(//condition matches) throw new DiscoveryException(\"The message\", \"The cause\"); }\n```\n\nThe first argument takes the message of the exception and the second argument \\(optional\\) takes the cause of the exception. You may also want to catch the exception and log it as shown in the example below:\n\n```javascript\ntry {\n foo(); \n} \ncatch(e) { \n if(e instanceof DiscoveryException)\n gs.log(\"A DiscoveryException occurred. It is \" + e. getMessage() + \" caused by \" + e.getCause()); }\n```\n\nThe above example also applies for AutomationException. DiscoveryException is typically used to provide exception processing specifically for Discovery, while AutomationException is used for exception processing that applies to both Orchestration and Discovery.\n\n"}}