{"id":15564562,"url":"https://github.com/chovanecm/snow-run","last_synced_at":"2025-04-23T23:23:30.054Z","repository":{"id":44408115,"uuid":"173626837","full_name":"chovanecm/snow-run","owner":"chovanecm","description":"Run ServiceNow background scripts from the command line","archived":false,"fork":false,"pushed_at":"2024-02-01T16:53:12.000Z","size":89,"stargazers_count":11,"open_issues_count":2,"forks_count":13,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-30T04:31:46.141Z","etag":null,"topics":["cli","command-line-interface","command-line-tool","development","devops","javascript","service-now","servicenow","snowrun","terminal-based"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chovanecm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-03T20:36:08.000Z","updated_at":"2024-02-01T16:53:16.000Z","dependencies_parsed_at":"2024-10-02T16:41:19.454Z","dependency_job_id":null,"html_url":"https://github.com/chovanecm/snow-run","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chovanecm%2Fsnow-run","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chovanecm%2Fsnow-run/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chovanecm%2Fsnow-run/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chovanecm%2Fsnow-run/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chovanecm","download_url":"https://codeload.github.com/chovanecm/snow-run/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250530069,"owners_count":21445720,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command-line-interface","command-line-tool","development","devops","javascript","service-now","servicenow","snowrun","terminal-based"],"created_at":"2024-10-02T16:41:17.157Z","updated_at":"2025-04-23T23:23:30.033Z","avatar_url":"https://github.com/chovanecm.png","language":"Shell","readme":"# SnowRun\n\nSnowRun aims to help developers and administrators to interact with their ServiceNow instance through the command line.\nInitially started to provide a command-line interface for executing server-side scripts remotely from the command line or a local file,\nit now additionally offers a few useful commands to interact with ServiceNow without having to click around in web browser,\nincluding database search and run-time object inspection.\n\nSnowRun is extensible. You can write your own extensions using ServiceNow JavaScript API that you are already familiar with.\n\nIt is free, experimental, assumed to work with the London release, although it may work with other releases as well, and is in no way affiliated with ServiceNow Inc.\n\nVersion 0.0.1\n\nRequirements:\n - curl, bash, grep, sed, etc. (=\u003e Linux / Windows Subsystem for Linux / Cygwin / MSYS / …)\n - a running ServiceNow instance\n - an account in ServiceNow that is capable of running background scripts\n\n# Warnings\n\n- ***Never ever try running anything of this against your production instance.***\n- ***Never ever allow anyone to steal your cookies (see below).***\n- ***Exit the shell after you finish your work. Your credentials are stored in environment variables when you work. (That's bad, I know.)***\n- The tool has been written to accommodate the author's current needs; it may not correctly detect some error states, and in general, mostly expects \"happy-case\" scenarios.\n\nYOU HAVE BEEN WARNED!\n\n\n\n# Instructions\n\nThis guide assumes you have an administrator account in your ServiceNow instance. If not, some commands may not work for you.  \nScripts have been \"tested\" (=are known (more or less) to work) with Ubuntu 18.04 using Windows Subsystem for Linux as well as with MSYS shipped with Git for Windows.\n\n\n## Setting up Environment\n\n1. Set your instance (optional, you can skip to step 2)\n \n *Preferably, avoid using the tool with production instances.*\n\n ```shell\n export snow_instance=dev1234.service-now.com\n ```\n\n2. Get scripts on your PATH, enable autocompletion and enter credentials\n```shell\nsource snow-run-env.sh\n```\n\n3. Log in:\n\nSome commands require you to log in first, depending on whether they are executed through the REST interface or background script.\n\n```shell\nsnow login\n```\n\nThe will create a user session and store cookies to a directory under your `$HOME`.\n\nYou can display the path to that directory with `snow info`:\n```console\nyou@machine:~$ snow info\nSNOW RUN against dev1234.service-now.com instance.\nTemp directory: /home/you/.snow-run/tmp/dev1234.service-now.com\nProtect that directory from being read by others.\n```\n\n4. Elevate roles (if needed)\nIf your instance requires the `security_admin` role to run background scripts, you might need to elevate roles for the user:\n```shell\nsnow elevate\n```\n\n## Usage\n\n### Running arbitrary background script\n\nYou can run arbitrary background script stored on your computer as if you entered it into the background script form in ServiceNow:\n\n```shell\nsnow run FILE\n# or write the script directly in terminal (read it from the standard input):\nsnow run\n```\n\nExample:\n ```console\nyou@machine:~$ snow run example.js\nThere are 54 records in the incident table.\nCurrent user: admin\n```\n\n### Searching for script includes by name\n\n```shell\nsnow scriptinclude search STRING\n```\n\nExample:\n ```console\nyou@machine:~$ snow scriptinclude search cmdb\nDiscoveryCMDBUtil            This class contains useful utility functions for interacting with the CMDB API for identification and reconciliation.\nCMDBDuplicateRemediatorUtil  Utility  for the CMDB Duplicate Remediator\nCMDBRelationshipAjax         Returns available CMDB relationships\nCMDBHealthTaskTables         Task tables involved in CMDB Health Audit and Dashboarding\nCMDBDuplicateTaskUtils       Utility class to manually create Remediate Duplicate Task with duplicates that are of independent type\nCMDBTransformUtil            CMDB Utility class for calling Identification and Reconciliation API within transform maps\nCMDBAccessCheckUtil          Utility function for CMDB access check.\nCMDBItem                     Class for Configuration Item helper functions\n```\n\n### Inspecting a script include or another object\n\n```shell\nsnow inspect SCRIPT_INCLUDE_OR_EXPRESSION\n```\n\nExample:\n ```console\nyou@machine:~$ snow inspect GlideRecordUtil\nType:            function\nOwn keys:\nPrototype keys:\n                 initialize                 function\n                 getCIGR                    function\n                 getGR                      function\n                 getFields                  function\n                 populateFromGR             function\n                 mergeToGR                  function\n                 getTables                  function\n                 getGlideRecordByAttribute  function\n                 type                       string\n```\n***Use with caution. You can accidentaly execute code with side effects!***\n\n### Evaluating an Expression\n\n```shell\nsnow eval EXPR\n```\n\nExample:\n ```console\nyou@machine:~$ snow eval 1+1\n2\nyou@machine:~$ snow eval 'gs.getUserName()'\nadmin\n```\n\nEver wondered how certain function looks like, what arguments it takes, but too lazy to read its script include? `eval` may come in handy here too.\n\n```console\nyou@machine:~$ snow eval 'GlideRecordUtil.prototype.getGR'\n\nfunction (base_table, sys_id) {\nvar gr = new GlideRecord(base_table);\nif (!gr.get(sys_id)) {\nreturn null;\n}\nvar klass = gr.getRecordClassName();\nif (klass == base_table) {\nreturn gr;\n}\ngr = new GlideRecord(klass);\nif (!gr.get(sys_id)) {\nreturn null;\n}\nreturn gr;\n}\n```\n\n***Use with caution. You can accidentally execute code with side effects!***\n\n### Searching for Tables\n```shell\nsnow table search [-l] STRING\n```\n\nBy default, this command searches for table names containing `STRING`. The `-l` option changes the behaviour to search in table labels.\n\nExample:\n ```console\nyou@machine:~$ snow table search properties\ncmdb_properties              CMDB Properties\nsys_properties_category      System Property Category\nsys_properties               System Property\nstd_change_properties        Standard Change Properties\nsys_properties_category_m2m  Category Property\n\nyou@machine:~$ snow table search -l properties # Searching by label\ncmdb_properties        CMDB Properties\nstd_change_properties  Standard Change Properties\n```\n\n### Listing Table Fields\n```shell\nsnow table fields TABLE_NAME\n```\n\nThis will output all fields on the table (including inherited fields), their labels and data type.\n\nExample:\n```console\nyou@machine:~$ snow table fields incident\nparent                    Parent                    reference\nmade_sla                  Made SLA                  boolean\ncaused_by                 Caused by Change          reference\nwatch_list                Watch list                glide_list\nupon_reject               Upon reject               string\nsys_updated_on            Updated                   glide_date_time\nlocation                  Location                  reference        cmn_(…)\n```\n\n### Querying Records\n```shell\nsnow record search [options] TABLE_NAME\n# snow r search works as well\n```\n\nPerform a query on a table.\n\n- `-q|--query ENCODED_QUERY` limit results to those matching an encoded query (see ServiceNow)\n- `-o|--order-by FIELD` return records ordered by `FIELD`; this parameter can be specified multiple times\n- `-od|--order-by-desc FIELD` return records ordered by `FIELD` in descending order; this parameter can be specified multiple times\n- `-f|--fields FIELDS` comma-separated list of fields to return\n- `-l|--limit N` the maximum number of records to return\n- `--no-header` omit column names that would normally be printed\n- `--sys-id` shortcut for `-f sys_id --no-header`\n\nExample:\n```console\nyou@machine:~$ snow r search -l 2 cmdb_ci\nskip_sync  operational_status  sys_updated_on       discovery_source  first_discovered  \n\nfalse      1                   2010-11-25 10:31:55                                      \nfalse      1                   2010-11-25 10:57:20                                      \n```\n\nExample:\n```console\nyou@machine:~$ snow r search sys_script_include -l 2 -f name,description -q nameSTARTSWITHcmdb -o sys_created_by --order-by-desc sys_created_on\nname                         description\nCMDBDuplicateRemediatorUtil  Utility for the CMDB Duplicate Remediator\nCMDBRelationshipAjax         Returns available CMDB relationships\n```\n### Counting Records\n\n```shell\nsnow record-count [-q|--query ENCODED_QUERY] TABLE_NAME\n# note the minus between record and count\n```\n\nPerform a query on a table and count results.\n\n- `-q|--query` limit results to those matching an encoded query (see ServiceNow)\n\n\n\nExample:\n```console\nyou@machine:~$ snow record-count -q \"sys_created_on\u003e=2018-01-01\" incident\n37\n```\n\n### Deleting Records\n\n```shell\nsnow record delete TABLE_NAME SYS_IDS...\n# or\nsnow record delete TABLE_NAME -q|--query ENCODED_QUERY\n# or\nsnow record delete TABLE_NAME -a|--all\n```\n\nDelete record(s).\n\n- `TABLE_NAME` name of the table to delete records from\n- `SYS_IDS...` a whitespace-separated list of sys_ids to remove. If omitted and no other options are specified, sys_ids are read from the standard input\n- `-q|--query` encoded query to select multiple records to be deleted at once\n- `-a|--all` delete all records in that table\n\nOptions `-q` and `-a` require user confirmation.\n\n\nExample:\n```console\nyou@machine:~$ snow r search incident -q short_descriptionSTARTSWITHTest --sys-id | snow r delete incident\n```\n\n```console\nyou@machine:~$ snow r delete sys_user 6816f79cc0a8016401c5a33be04be441 abdef79cc0a8016401c5a33be04fg998\n```\n\n```console\nyou@machine:~$ snow record delete incident -q \"sys_created_on\u003e=2018-11-01\"\nThere are 8 matching records in the incident table.\nDelete them? [Y/N]: y\n```\n\n```console\nyou@machine:~$ snow r delete u_pet -a\nThere are 1 matching records in the u_pet table.\nDelete them? [Y/N]: y\n```\n\n### Creating or Updating Tables (EXPERIMENTAL)\n\n```shell\nsnow table-create TABLE_NAME field1:field_type1 field2:field_typ2 ...\n```\n\nCreate or update a ServiceNow table.\n\n- `field_name` is a database field name, e.g. `u_name` \n- `field_type` is one of: `string` `integer` `boolean` `glide_date` `glide_date_time` `currency` `price` `reference` (`reference` doesn't work properly yet)\n\nYou can specify multiple fields at once.\n\n***This command is highly experimental!***\n\nExample:\n```console\nyou@machine:~$ snow table-create u_pet u_pet_name:string u_birthdate:glide_date\nTableCreate for: u_pet\nDBTable.create() for: u_pet\nReplication is not enabled on table: u_pet, not queueing replication table create special db event\nLicensingTableCreateListener: Initializing licensing attrs for table u_pet\n[0:00:00.426] Table create for: u_pet\nBegin ResourceSupport.buildTableResources(u_pet, undefined)\nEnd ResourceSupport.buildTableResources\nOK\n```\n\nWe can check it has been created:\n\n```console\nyou@machine:~$ snow table search u_pet\nu_pet  Pet\n```\n\nand perhaps see if something is in there:\n\n```console\nyou@machine:~$ snow r search u_pet -f u_birthdate,u_pet_name,sys_created_by\nu_birthdate  u_pet_name  sys_created_by\n\n2019-02-04   Billy       admin\n```\n\n\n## Extensions\n\nBesides running arbitrary scripts with `snow run FILE`, which don't require any special modification, the tool also allows for writing custom extensions.\n\nExtensions are regular JavaScript files implementing a certain interface and stored in the `js` subdirectory of the project.  \n*All of the ServiceNow server-side script API, such as `GlideRecord`, `gs` etc. is available.*\n\nEach extension must declare and implement the following method:\n```javascript\nfunction $exec(/* any number of arguments */) {\n   // any ServiceNow-compatible JavaScript code\n}\n```\n\n#### Example 1 - File `js/hello.js` without Arguments:\n```javascript\nfunction $exec() {\n   gs.print(\"Hello!\");\n}\n```\nSuch a script can be executed in two interchangeable ways:\n```shell\nsnow exec hello\n# Or simply\nsnow hello\n```\n\n```console\nyou@machine:~$ snow hello\nHello!\n```\n\n#### Example 2 - File `js/hello-name.js` with Arguments:\n```javascript\nfunction $exec(firstname, lastname) {\n   gs.print(\"Hello \" + firstname + \" \" + lastname);\n}\n```\nAll arguments are passed as strings automatically:\n\n```console\nyou@machine:~$ snow hello-name John Doe\nHello John Doe\n```\n\n#### Example 3 - File `js/echo.js` Formatted Output:\n\nAny output produced by extensions is automatically formatted as a table with columns identified by tabulator (`\\t`).\nInstead of producing output with TABs manually, the `$echo(/* any number of arguments */)` function can be called with any number of arguments representing columns. Unless only one argument is provided, any new-lines strings are automatically converted to spaces to prevent the resulting table from being wrapped to the next line.\nIf this is not the desired behaviour, call `$echo(\"This is \\n New line\")` or `gs.print(\"This is \\n New line\")`instead.\n\n\n```javascript\nfunction $exec(firstname, lastname) {\n    $echo(1, firstname, lastname);\n    // equivalent to:\n    // gs.print(\"1\\t\" + firstname + \"\\t\" + lastname)\n    $echo(2, \"Jan\", \"Jesenius\\nNotANewLine\");\n    $echo(\"New\\nline\");\n }\n ```\n \n```console\nyou@machine:~$ snow echo John Doe\n1     John  Doe\n2     Jan   Jesenius NotANewLine\nNew\nline\n```\n\n#### Example 4 - File `js/echo.js` with Help on Usage:\n\nExtensions can define their own `$help()` function to print usage when the script is invoked with either `--help` or `-h`.\n\n*Note: The help function is also executed remotely!*\n\n```javascript\nfunction $exec(firstname, lastname) {\n    $echo(1, firstname, lastname);\n    // equivalent to:\n    // gs.print(\"1\\t\" + firstname + \"\\t\" + lastname)\n    $echo(2, \"Jan\", \"Jesenius\\nNotANewLine\");\n    $echo(\"New\\nline\");\n }\n \nfunction $help() {\n    $echo(\"Print out name and some stuff around\");\n    $echo(\"Usage: firstName, lastName\");\n}\n ```\n \n```console\nyou@machine:~$ snow echo -h\nPrint out name and some stuff around\nUsage: firstName, lastName\nNew\nline\n```\n\n\n----\n\nSNOW-RUN. Terminal interface to ServiceNow.  \nCopyright (C) 2019  Martin Chovanec [martin@chovanecm.cz](mailto:martin@chovanecm.cz)\n\nThis program is free software: you can redistribute it and/or modify  \nit under the terms of the GNU General Public License as published by  \nthe Free Software Foundation, either version 3 of the License, or  \n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,  \nbut WITHOUT ANY WARRANTY; without even the implied warranty of  \nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the  \nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License  \nalong with this program.  If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchovanecm%2Fsnow-run","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchovanecm%2Fsnow-run","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchovanecm%2Fsnow-run/lists"}