Script Deployment Using the EMSE Tool

Overview

The EMSE Tool leverages third-party Source Code Control Systems (SCCS) such as Subversion and Github to facilitate easier storage, management, and deployment of EMSE scripts. Script developers can use their choice of script editor and SCCS to edit and manage their scripts, and use the EMSE Tool to deploy them into Civic Platform. The EMSE Tool provides the following capabilities:

Connects to the SCCS via the Accela Gateway
Supports two popular SCCS: Github and Subversion (SVN)
Compares scripts between the SCCS and Civic Platform
Pushes scripts into Civic Platform from the SCCS, builds, and deploys them. Building a script consolidates multiple custom scripts within the INCLUDES_CUSTOM directory into a single script file in Civic Platform. Deploying a script replaces the current script entry in the Civic Platform database with the new script from the SCCS.
Pulls scripts from Civic Platform into the SCCS. This capability can be used to begin a new repository or refresh scripts that may have been corrupted in the SCCS.
Validates script syntax before building or deploying a script
Integrates with EMSE scripts and Expression Builder scripts
Applies Accela’s standard naming and file structure conventions when deploying scripts to Civic Platform

Configuration

An administrator must configure the EMSE Tool to connect to the appropriate SCCS repository. Although the EMSE Tool supports both Github and TortoiseSVN SCCS repositories, it only supports one SCCS per configuration.

To configure the SCCS repository and connection settings, configure the following standard choice:

EMSEToolsConfig - Specifies source code control settings.

Standard Choice Value	Value Desc	Description
`agency_repo_username`	`<aUserid>`	An agency user’s username for the SCCS repository containing agency scripts. Civic Platform connects to the SCCS repository using this username. Note: The specified username must have permission to access the agency script SCCS repository.
`agency_repo_password`	`<aPassword>`	An agency user’s password for the SCCS repository containing agency scripts. Civic Platform connects to the SCCS repository using this password.
`agency_url_svn`	`<https://svnUrl>`	For SVN: The SVN URL for the agency script repository. You can get the SVN URL from your repository’s SVN folder properties. Note: If you specified agency_url_svn, do not specify agency_url_git.
`agency_url_git`	`<https://gitUrl>`	For Github: The Github URL for the agency script repository. You can get the Github URL from the HTTPS Clone URL on your agency script repository’s Github page. Note: If you specified agency_url_git, do not specify agency_url_svn.
`master_repo_username`	`<aUserid>`	An agency user’s username for the SCCS repository containing Civic Platform master scripts. Civic Platform connects to the SCCS repository using this username. Note: The specified username must have permission to access the master script SCCS repository.
`master_repo_password`	`<aPassword>`	An agency user’s password for the SCCS repository containing Civic Platform master scripts. Civic Platform connects to the SCCS repository using this password.
`master_url_svn`	`<https://svnUrl>`	For SVN: The SVN URL for the master script repository. You can get the SVN URL from your repository’s SVN folder properties. Note: If you specified master_url_svn, do not specify master_url_git.
`master_url_git`	`<https://gitUrl>`	For Github: The Github URL for the master script repository. You can get the Github URL from the HTTPS Clone URL on your master script repository’s Github page. Note: If you specified master_url_git, do not specify master_url_svn.

Ensure that the Active checkbox is enabled for each of the Standard Choice values you entered.

The EMSE Tool Portlet

To access the EMSE Tool via Civic Platform Administration, click the EMSE Tool main link from the Civic Platform home page.

Note: To provide agency users and EMSE script developers access to the EMSE Tool within Civic Platform Administration, an administrator must configure a main link that opens the EMSE Tool portlet. For information about how to add a main link in Civic Platform, see “Adding a Main Link” in Civic Platform Administrator Guide.

The EMSE Tool portlet shows a tree structure of the Master scripts and Agency scripts from the SCCS repository which have not been synchronized with the scripts in the Civic Platform database. The following example shows the Agency scripts in the SCCS repository that have not been deployed into or synchronized with Civic Platform:

Pulling Scripts from Civic Platform

The EMSE Tool enables an agency user to initially populate or refresh an SCCS repository with the scripts stored in Civic Platform.

Pulling a repository

The EMSE Tool automatically detects if a configured master or agency repository in the SCCS is empty. When you click the EMSE Tool link while the agency or master repository is empty, the EMSE Tool manager prompts you to pull all the scripts. Click OK to confirm that you want to pull all the scripts from the Civic Platform repository into your SCCS repository. After the EMSE Tool has pulled all scripts, both repositories are synchronized.

Pulling a script

If a script has been updated within Civic Platform, you can select that script in the EMSE Tool to see the highlighted modifications on the AA script pane and pull the modified script into your SCCS repository. To pull the script from Civic Platform into your SCCS repository, click the Pull button under the AA script pane. After the EMSE Tool has pulled the script from Civic Platform into the SCCS repository, both repositories are synchronized and the script is no longer displayed under the EMSE repository tree structure.

Deploying Scripts

When you deploy one or more scripts, the EMSE Tool validates each script and uploads the script(s) to the Civic Platform database.

To deploy one or more scripts:

Select the script(s) from the EMSE Repository tree structure.
Right-click, and choose Deploy.

The EMSE Tool uses the JavaScript engine to validate script syntax such as missing keyword, incomplete loop or branch, undefined variable, unmatched symbol pairs, and others. For each script validation failure, the EMSE Tool displays the script line number where the syntax error occurred. Fix the error in your script editor, check-in your modifications in your SCCS repository, and deploy the script again in EMSE Tool. After a script has been deployed, it is stored in the Civic Platform database, and is no longer displayed in the EMSE Repository tree structure.

Deploying Custom Functions

Deploying custom functions consists of:

Building the INCLUDES_CUSTOM script by concatenating all custom function JavaScript files in the INCLUDES_CUSTOM folder into one INCLUDES_CUSTOM.js file.
Deploying the INCLUDES_CUSTOM script into Civic Platform

To build the INCLUDES_CUSTOM script:

Select the INCLUDES_CUSTOM folder from the EMSE Repository tree structure.

The left script pane lists the custom scripts in the Includes Custom folder.
Click Build.

The right script pane displays the Includes Custom script file containing all custom scripts.

To deploy the Includes Custom script into Civic Platform:

Select the INCLUDES_CUSTOM folder from the EMSE Repository tree structure.

The left script pane lists the custom scripts in the Includes Custom folder.
Click Deploy.

The right script pane displays the Includes Custom script file containing all custom scripts.

To find the INCLUDES_CUSTOM script in Civic Platform:

Go to Civic Platform Admin Tools.
Select Events > Custom Scripts.

The following shows a sample INCLUDES_CUSTOM script in Civic Platform:

Comparing Scripts

You can compare scripts in your SCCS repository with the deployed scripts in Civic Platform to determine what has been modified.

To compare a script between Civic Platform and SCCS:

Select the script in the EMSE Repository tree structure.
The EMSE Tool displays the script from the SCCS repository on the left pane and the script from Civic Platform on the right pane, counts the number of differences, and highlights the differences. For example:

Right-click, and choose Diff.