search

fruition-partners / filesync

Tool to sync local file changes to ServiceNow instances.
20 stars 52 forks source link

readme

FileSync

Overview

FileSync synchronizes local file changes to mapped records in ServiceNow instances.

This enables ServiceNow developers to use their favorite integrated development environments (IDEs) and text editors like WebStorm and Sublime for editing JavaScript, HTML, Jelly and other code - without wasting time and interrupting development workflow copying and pasting code into a browser.

When a file changes within a configured root (project) folder, the parent folder and file name are used to identify the table and record to be updated.

Adding an empty file, or clearing and saving an existing file, refreshes the local file with the latest instance version, syncing from the instance to the local file. This is an easy way to populate your project folder with existing scripts related to your project.

Quick Start

Download FileSync-v0.1.0.zip and check out the video walk-through of installing, configuring and using FileSync.

Or, continue with the steps below.

Installation

Step 1. Ensure the JSON Web Service plugin is activated for your instance.

Step 2. Download FileSync-v0.1.0.zip and unzip into your desired install path, for example:

Step 3. Create a local folder structure for your project / source files. Project folders will be mapped to root folders in the app.config.json config file. The following example folder structure is mapped in the app.config.json settings section below:

c:\dev
    \project_a
        business_rules
        script_includes
    \project_b
        script_includes
        ui_pages

Step 4. Edit app.config.json.

Usage

With installation and configuration completed, you can start filesync by executing the included batch/shell scripts:

This launches a console window where you should see log messages showing the starting configuration of FileSync. Do not close this window. This is what is watching for file changes. As you make changes to mapped files, you'll see messages logged showing the sync processing.

Verify everything works by adding an empty file corresponding to an instance record. You can do this from your editor or IDE, or open a new command shell:

On Windows, at a command prompt:

cd c:\dev\project_a
md script_includes
cd script_includes
copy nul JSUtil.js      <-- creates an empty file named JSUtil.js

On Mac, in Terminal:

cd /path/to/project_a
mkdir script_includes
cd script_includes
touch JSUtil.js

Adding the empty JSUtil.js file will cause FileSync to sync the (OOB) JSUtil script include to the file. Any changes to this local file will now be synced to the mapped instance.

The basic workflow is to initially create a script on ServiceNow (script include, business rule, ui script, etc.), then add an empty file of the same name (and mapped extension) to a mapped local folder.

FileSync does not currently support creating new records in ServiceNow by simply adding local files since there are additional fields that may need to be populated beyond mapped script fields. So, always start by creating a new record on the instance, then add the empty local file and start editing your script.

app.config.json settings

Comments are included below for documentation purposes but are not valid in JSON files. You can validate JSON at http://www.jslint.com/

{
    // maps a root (project) folder to an instance
    "roots": {
        "c:\\dev\\project_a": {                 // full path to root folder
                                                // on Windows, ensure that backslashes are doubled
                                                //    since backslash is an escape character in JSON
                                                // on Mac, remove 'c:' and use forward slashes as in
                                                //    "/path/to/project_a"
            "host": "demo001.service-now.com",  // instance host name
            "user": "admin",                    // instance credentials
            "pass": "admin"                     //    encoded to auth key and re-saved at runtime
        },
        "c:\\dev\\project_b": {                 // add additional root mappings as needed
            "host": "demo002.service-now.com",
            "auth": "YWRtaW46YWRtaW4="          // example of encoded user/pass
        }
    },
    // maps a subfolder of a root folder to a table on the configured instance
    "folders": {
        "script_includes": {                    // folder with files to sync
            "table": "sys_script_include",      // table with records to sync to
            "key": "name",                      // field to match with filename to ID unique record
            "fields": {                         // file contents are synced to a field based on filename suffix
                "js": "script"                  //   files ending in .js will sync to script field
            }
        },
        "business_rules": {
            "table": "sys_script",
            "key": "name",
            "fields": {
                "js": "script"
            }
        },
        "ui_pages": {
            "table": "sys_ui_page",
            "key": "name",
            "fields": {                         // multiple fields for the same record can be mapped to multiple
                "xhtml": "html",                //   files by using different filename suffixes
                "client.js": "client_script",   //   for ui pages, you might have three separate files:
                "server.js": "processing_script" //    mypage.xhtml, mypage.client.js, mypage.server.js
            }                                   //   to store the all script associated with the page
        }
        ...
    },
    "debug": false                              // set to true to enable debug logging
}

Architecture

FileSync was built using Node.js, a platform built on Chrome's JavaScript runtime. Zipped distribution contents: