EC-Admin is a collection of administrative procedures to help you manage your server. Its inception was sparked by requests from customers during my Professional Services engagements. It has grown over the years to what it is now.
It contains the following modules:
- System Health
- agentMemoryConfiguration
- testResources
- performanceMetrics
- Look and Feel
- changeBannerColor
- Jobs and Workspaces management
- jobsCleanup
- jobsCleanup_byResult
- deleteWorkspaceOrphans
- deleteObjects
- Plugins
- synchronizePlugins
- createPluginFromProject (deprecated)
- projectAsCode
- Artifacts management
- artifactRepositorySynchronization
- artifactsCleanup
- artifactsCleanup_byQuantity
- Object export backup and restore
- saveProjects
- saveAllObjects
- restoreObjects
- Schedules
- schedulesDisable
- schedulesEnable
- Semaphore management
- acquireSemaphore
- releaseSemaphore
- License Logger
- postp debugger helper
- Communication
- miscellaneous
- findJobId
This collection of procedures can be found on our GitHub repository. It is available as a plugin delivered in the form of a .jar file or you can simply get the source code and recompile it yourself.
To install the plugin, use one the following methods:
- the "Install from File/URL" tab in the administration/Plugins
- the Perl "$ec->installPlugin()" API.
- the CLI client "ectool installPlugin --force 1 EC-Admin.jar
Don't forget to promote the plugin after installation.
To install on 4.0.x or or 4.1.x, import the EC_4.0.xml file. Be
aware that some features are not present as the original project
makes use of createJobStep() API which was introduced in 4.2.0:
ectool import /path_to/EC-Admin_for_EC_4.0.xml --disableSchedules 1
IMPORTANT: For all parameter descriptions below, required parameters are shown in bold italics.
This procedure allows you to change the Java heap memory setting of your agents. Electric Cloud support recommend increasing the default for agents with a heavier load like the repository server agent, gateway agent and web server agent.
| Parameter | Description |
|---|---|
| agent | The name of the resource on which the agent is located. |
| init memory | The amount of init memory to assign to the Java heap. It can be indicated in Mb or as a % of the toal memory. |
| max memory | The maximum amount of memory to assign to the Java heap. It can be indicated in Mb or as a % of the toal memory. |
| restartAgent | On Linux the agent service is restarted, on Windows the box is rebooted. |
This procedure is simply to test connection to all your resources or a specific pool. This will create simple step to run an echo command on alive resources.
| Parameter | Description |
|---|---|
| pool | Name of a pool. If empty, all resources will be tested |
This procedure returns some information about your ElectricCommander server like number of processors, total RAM, available RAM, ping times with agents, relative performance of agents, ... In addition it checks the amount of time spent running steps on the server local agents as this should be minimized as much as possible.
If you work on multiple Commander servers like a development and a production instances, this procedure is for you. It allows you to change the color of the top banner and the logo to make it easier to identify your different servers. Feel free to send me new ones if you have a more artistic touch than me. Or better push your changes to GitHub.
| Parameter | Description |
|---|---|
| color | Choose a color for your top banner |
| logo | Choose a set of pre-rendered logo to indicate if you server is of type DEV, SDK, TEST or PROD, in black or white to go along different background colors. |
| logoFile | The path on the Commander server to upload your own logo. If this value is not blank it will overwritten the logo parameter above. |
| webResource | The name of the resource running on your webserver to allow the copy of the logo and banner color files. |
Note: if you run your server and agent as different user (as recommended), the agent won't be able to modify the following files:
- INSTALL_DIR/apache/htdocs/commander/images/logo.gif
- INSTALL_DIR/apache/htdocs/commander/lib/images/frame_bannerBg.gif (version 4.x and later)
- INSTALL_DIR/apache/htdocs/commander/lib/styles/StdFrame.css (version 5.4 )
- INSTALL_DIR/apache/htdocs/commander/styles/StdFrame.css (version 6.0 and later)
Those file permissions need to be opened so the agent user can modify them.
will produce
This set of procedures will help you manage your old jobs and the associated workspaces.
A procedure to delete jobs older than a specified number of days. It will also delete associated workspace job directories.
| Parameter | Description |
|---|---|
| olderThan | Indicate the number of days after which jobs are deleted |
| jobType | Define what jobs should be deleted: Error, Warning or all. |
| jobProperty | Name of a property attached to your jobs. If this property is set, your job won't be deleted no matter how old it is. |
| jobPatternMatching | A SQL pattern matching to automatically preserve some jobs. The pattern must solve for a LIKE statement. |
| delete | If this option is not set, only report is done. No real data are deleted |
| computeUsage | Check off to skip the computation of the number of steps and the file space used for the job. This will speed up the execution. |
A procedure to delete jobs older than a specified number of days. It will also delete associated workspace job directories. It will keep the number of successful, failed and warning jobs you entered. You can also provide a property name, if this property is attached to the job, it won't be deleted no matter how old. A report only mode prevents any real deletion.
A procedure to crawl a workspace directory to find orphan jobs (directories without a matching job) on a specified resource.
A procedure to quickly delete jobs or workflows older than a specified number of days. It will not delete associated workspace job directories. This is for customers with huge job or workflow database.
This procedure synchronizes plugins between the server and a resource. Plugins are uploaded first as artifacts if it has not been done already and then downloaded on the resource if it does not already exist in the plugins directory.
Note: This procedure requires access to the jar or zip executable in the PATH.
The procedure "createPluginFromProject" allows the transformation of a project into a plugin. The parameters are the following:
| Parameter | Description |
|---|---|
| Project | The name of the project to transform into a plugin |
| Plugin | The name of the plugin. If left empty, it will default to the project name. |
| Category | The category of the plugin. It helps filter the plugin list in the Plugins page and in the picker list. |
| Version | Version of the plugin to create. A build number is automatically added (after incrementation) to ensure uniq version numbers. |
| Description | The description of the plugin to display in the main plugin page. If left empty it will default to the description of the project. |
| Author | Name of he author of the project to transform into a plugin. |
| The email of the author. | |
| Comment | if this parameter is not empty, it will be added to the CHANGELOG for traceability. |
| fixSelfReferences | Replace self references to the project in sub-prceodure calls by an empty string to be sure the plugins= created will not call the original project instead of itself. |
| createArtifact | Save the new created plugin as an artifact version. |
| installPlugin | A Boolean to install or not the plugin after creation |
| promotePlugin | A Boolean to promote or not the plugin after installation |
| moveJobs | A Boolean to move or not jobs from the previous version into the current one upon promotion. |
At the project level, you can define the following properties to alter the behavior of the plugin creation:
- ec_visibility:
- Choose all to have the plugin shows in the project list (like EC-Admin), or pickListOnly (default) to have your procedures available only through the plugin procedure picker (when you choose plugin as a step).
- help:
- This property allows you to create a Help page associated with your plugin. The page you are currently reading is created this way so feel free to explore the help property in the EC-Admin plugin/project for an example.
- promoteAction
- This property would contain some Perl code to take action
when the plugin change state. Look at the ec_setup property
in the plugins installed on your system to get a better idea
of what you can accomplish.
For example to set a property hwne the plugin is pomoted you could add the the following code to the promoteAction procedure:
if ( $promoteAction eq 'promote' ) { $batch->setProperty( "/projects/$pluginName/addedByPromote", "123" ); }
In addition each procedure can modify the behavior with the following 2 properties:
- exposeToPlugin:
- This property if set to 1 will add the procedure to ec_setup to be shown in the procedure picker list when choosing a plugin step.
- descriptionForPlugin:
- This property will be shown as the description in the picker list mentioned above. If it's empty or non-existent, the description will be description of the procedure itself.
Note: This procedure requires access to a resource with the Commander SDK installed.
This procedure is an extension of createPluginFromProject. It also
creates a plugin but instead of simply exporting the project, it
"explodes" each step in its own file for finer granularity check in
in your favorite SCM tool.
You can also add automatically a
mechanism to add credential/configuration management to you plugin.
All the properties associated with createPluginFromProject still
apply.
| Parameter | Description |
|---|---|
| Project | The name of the project to transform into a plugin |
| Plugin | The name of the plugin. If left empty, it will default to the project name. |
| Category | The category of the plugin. It helps filter the plugin list in the Plugins page and in the picker list. |
| Version | Version of the plugin to create. A build number is automatically added (after incrementation) to ensure uniq version numbers. |
| Description | The description of the plugin to display in the main plugin page. If left empty it will default to the description of the project. |
| Author | Name of he author of the project to transform into a plugin. |
| The email of the author. | |
| Comment | if this parameter is not empty, it will be added to the CHANGELOG for traceabiity. |
| Directory | The name of the directory where to create the complete file structure. Typically a directory you will check in in your SCM. |
| SDK resource | The name of an agent where the Commander SDK is installed. Required to build the plugin. |
| SDK Location | The path where the Commander SDK is installed on the above resources.. |
| fixSelfReferences | Replace self references to the project in sub-prceodure calls by an empty string to be sure the plugins= created will not call the original project instead of itself. |
| overwrite | if the ec_setup.pl already exists, it is not overwritten. Check this parameter overwrite with a content dynamically generated based on project properties. |
| disableCleanup | Prevents the exported project file to be deleted. It can be an issue when the agent and server run as different users. |
| projectAsCode | Include a bit of code to revert the plugin to a project upon promotion if this option is checked. |
| createArtifact | Save the new created plugin as an artifact version. |
| installPlugin | A Boolean to install or not the plugin after creation |
| promotePlugin | A Boolean to promote or not the plugin after installation |
| moveJobs | A Boolean to move or not jobs from the previous version into the current one upon promotion. |
At the project level, you can define the addtional following properties to alter the behavior of the plugin creation:
- configureCredentials:
- this property will indicate to EC-Admin to code to help create configuration to manage credentials for your plugin. It adds:
- A procedure name "createConfiguration". You need to modify the code of the step "createAndAttachCredential" in order to reference your own procedures and steps where you want to attach those credentials.
- Some cgi-bin scripts.
- Some java code to manage the different UI to create, edit and delete configurations.
- A "configure" link for your plugin on the pluginManager page.
- filesToCopy:
- This property will indicate to the ant plugin builder to add files and directories to your jar file. It will create an entry for the filesToCopy.extras in your build.xml. For example, EC-Admin includes lib/*.jar that is used to manage the configurations required for the credentials.
- pluginDependencies:
- This property allows you to add plugin dependencies that need to be satisfied before you ca install the plugin. Put a a line per dependency with each line being PLUGIN:VERSION
Note: EC-Admin is released on GitHub using this procedure.
Synchronize the content of a source artifact repositories to a target one. You can use pattern matching to select specific artifact versions to synchronize.
| Parameter | Description |
|---|---|
| Source Artifact Repository | The name of the artifact repository from which to synchronize. |
| Target Artifact Repository | The name of the artifact repository to which to synchronize. |
| Synchronization Resource | The name of a resource used as a buffer to download/upload the files. |
| Artifact Version Pattern | Pattern of artifact version to sync. Examples: MyGrp:MyKey:* (all artifact versions with group MyGrp and key MyKey), MyGrp:* (all artifact versions with group MyGrp), * (all artifact versions. This is the default). |
| Batch Size | Number of artifact version to process at once. A high number could overwhelm your gateways. |
A procedure to delete artifact versions older than a specified number of days. Same as for jobs above, a property allows preventing the deletion. Once the artifacts have been deleted, artifact repositories and artifact caches are cleaned as well (deleting stale artifacts). A report mode prevents any real deletion.
As "ArtifactsCleanup"", this procedure deletes artifact versions older than a specified number of days but keeps only X per Artifact. Again, a property allows preventing the deletion. Once the artifacts have been deleted, artifact repositories and artifact caches are cleaned as well (deleting stale artifacts). A report only mode prevents any real deletion.
This set of procedures is to help you export objects from ElectricCommander for a potential inclusion into your SCM for versioning.
This procedure simply exports your projects in a directory on the server. It is recommended to enable the nightly schedule associated with it to backup your projects on a regular basis.
This procedure brings a finer granularity to a full server export. For example, it may be easier to retrieve a simple project or procedure instead of the full server export or database backup to undo r a wrong action or a bad code change. By default it exports projects and each procedure individually. In addition by enabling the matching checkboxes, you can also export resources, resource pools, workspaces, users and groups, and with 5.x and later ElectricFlow Deploy objects (Applications, Components and Environments). It is recommended to enable the nightly schedule associated with it to backup your projects on a regular basis.
Note: Use saveProjects or saveAllObjects depending on the granularity you are requiring.
This procedure allows you to import all the .xml files in a directory. Typically those have been created with saveAllObjects above.
| Parameter | Description |
|---|---|
| directory | The directory where the .xml files are located. |
| force | A boolean to pass the --force 1 option to import. |
| resource | The resource on which to read the files. |
This set of procedures is to help around schedule enabling and disabling which is very useful when you want to perform maintenace on your server.
This procedure disables all the enabled schedules and optionaly saves the list in a property.
| Parameter | Description |
|---|---|
| Disable | If this option is not set, only report is done. No schedules are disabled. |
| Schedule list property | Property path used by the step to save the list of schedules disabled. Can be used by schedulesEnable. |
This procedure enables schedules passed as a list in a property, typically saved by schedulesDisable.
| Parameter | Description |
|---|---|
| Enable | If this option is not set, only report is done. No schedules are enabled. |
| Schedule list property | Property path containing the list of disabled schedules. |
Those 2 procedures are used to create a "semaphore" to control the access to
a set of steps. In order to insure the atomicity (only one step can modify
your sempahore property at any time) of the operation, you first need to create
a resource with a 1-step limit.
Then you will need to create a property with a value of 0. The location
does not matter
as long as it will be readable and writable by the plugin.
This procedure is the "gate". It checks than you have not used more tokens than allowed. If you have, it will simly wait until some become available. This procedure is called just before the steps which access you want to control.
| Parameter | Description |
|---|---|
| maxSemaphoreValue | This is the maximum number of token you allow for this semaphore. |
| semaphoreProperty | Property path containing your gate current value. |
| serializationResource | The name of the 1-step resource to access the semaphore property. |
This procedure simply "releases" of of the token for other to consume.
| Parameter | Description |
|---|---|
| semaphoreProperty | Property path containing your gate current value. |
| serializationResource | The name of the 1-step resource to access the semaphore property. |
The License Logger mechanism is intended to collect and email various license-related statistics. It is implemented as a set of schedules and procedures, along with a set of configuration properties.
The configuration properties are located under /server/EC-Admin/licenseLogger/config. The property sheet is created upon promotion if it does not already exists.The following properties can be set up:
| Parameter | Description |
|---|---|
| resource | The name of the resource on which to run the procedures. Default is "local". |
| workspace | The name of the workspace used by the procedures. Default is "default". |
| cleanOldJobs | A boolean to remove old jobs so only the last one is kept for each procedure. It keeps your job history cleaner. |
| emailConfig | The name of the mail configuration used to send report. |
| emailTo | The list of recipients (semicolon separated) to which to send the reports. |
The debugPostp is a simple procedure to help you debug with postp. Traditionally you would call postp from the command line with the jobStepId of the faulty postp and adding some additional option to see details. This new procedure does that for you on Linux and Windows, you just have to pass the jobStepId as a parameter.
The sendAlert is a simple procedure to send a message to all registered users with an email address attached to the account. You can format your email in HTML by encapsulating it in a <html> tag.
For all those procedure I'm not sure where to put
This procedure is designed for people migratimg away from ElectricCommander 4.2 to ElectricFlow 5.x or later. It will simply search in the step commands or parameters to a sub-procedure for any instance of jobId. No change will be done. It's up to the user to make any change.
| Parameter | Description |
|---|---|
| projectPattern | A SQL pattern to filter projects for the search. |
- License Logger
- Mike Westerhof
- deleteObjects
- testResources
- Tanay Nagjee
- Other
- Laurent Rochette (lrochette@electric-cloud.com)
This module is free for use. Modify it however you see fit to better your experience using ElectricCommander. Share your enhancements and fixes.
This module is not officially supported by Electric Cloud. It has undergone no formal testing and you may run into issues that have not been uncovered in the limited manual testing done so far.
Electric Cloud should not be held liable for any repercussions of using this software.