Anda di halaman 1dari 1519

ElectricCommander 5.

Electric Cloud, Inc.


www.electric-cloud.com

ElectricCommander 5.4
Copyright 2002 2015 Electric Cloud, Inc. All rights reserved.
Published 5/21/2015
Electric Cloud believes the information in this publication is accurate as of its publication date. The information
is subject to change without notice and does not represent a commitment from the vendor.
THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. ELECTRIC CLOUD, INCORPORATED
MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION
IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE.
Use, copying, and distribution of any ELECTRIC CLOUD software described in this publication requires an
applicable software license.
Copyright protection includes all forms and matters of copyrightable material and information now allowed by
statutory or judicial law or hereinafter granted, including without limitation, material generated from software
programs displayed on the screen such as icons, screen display appearance, and so on.
The software and/or databases described in this document are furnished under a license agreement or
nondisclosure agreement. The software and/or databases may be used or copied only in accordance with terms
of the agreement. It is against the law to copy the software on any medium except as specifically allowed in the
license or nondisclosure agreement.
Trademarks
Electric Cloud, ElectricAccelerator, ElectricCommander, ElectricInsight, and Electric Make are registered
trademarks or trademarks of Electric Cloud, Incorporated.
Electric Cloud productsElectricAccelerator, ElectricCommander, ElectricInsight, and Electric Makeare
commonly referred to by their short namesAccelerator, Commander, Insight, and eMakethroughout
various types of Electric Cloud product-specific documentation.
Other product names mentioned in this guide may be trademarks or registered trademarks of their respective
owners and are hereby acknowledged.

Contents

Welcome to ElectricCommander

Overview

What makes ElectricCommander unique?

What you do

What Commander does

Schedules

Workflows

Projects

Procedures and Steps

Jobs

Resources

Commander architecture

Simple architectural overview

Expanded remote configurations

Getting Started

Overview

Basic Commander terminology

Getting Started Scenarios help topic series

10

Navigating the Commander user interface

10

The Home tab

11

Projects, Jobs, and Workflow tabs

13

Cloud tab

14

Artifacts and Search tabs

15

Search tab

16

Administration tab

16

Getting Started - Scenario 1 - Creating a simple procedure

18

Overview

19

Begin Scenario 1

19

Scenario extension - Adding another step

25

Finding a Commander web page...

26

Summary

27

Getting Started - Scenario 2 - Creating a procedure that uses an SCM


Overview

29

Begin Scenario 2

30

Scenario extension - Add a step to show workspace contents

38

Summary

39

Getting Started - Scenario 3 - Notification, scheduling, and reporting

40

Overview

41

Begin Scenario 3

41

Scenario extension - Add a thumbnail report to your Home page

52

Summary

53

Getting Started - Scenario 4 - Multi-agent build and test

54

Overview

55

Begin Scenario 4

55

Scenario extension - Using postp

61

Summary

63

Configuring ElectricCommander

64

The table below provides a brief description of Commander configuration tasks

64

Web Interface Online Help System

65

Setting Up Resources

66

What is a resource?

66

Commander supports two resource types

66

Standard Resources

66

Proxy Resources

66

Setting up SSH keys

67

To create a new resource

67

Gateways and zones

68

What is a zone?

68

Cross-zone communication

68

What is a gateway?

69

Support for gateways

69

Setting Up Workspaces
To create a new workspace

Setting Up Email Configurations


To create an email configuration

70
70

71
71

Setting Up a Source Control Configuration

72

Setting Up Directory Providers

73

To specify a directory provider

ii

28

73

Enable/Disable Local Commander Users


wrapper.conf Properties

The Home Page

73
73

74

Overview

74

Job Configurations

74

Create Job Configurations three ways


Shortcuts
Create Shortcuts two ways
Jobs Quick View
Create a job category
Reports

Using ElectricCommander in Your Environment

74
75
75
75
75
76

77

What's in a step?

77

Where's the script for a step?

78

Environment variables

79

When do you use subprocedures?

79

How do you evolve procedures?

79

Porting existing scripts

80

Commander project version control

81

Using ectool and the Commander API

82

Using ectool

82

Logging in

82

Global Arguments (optional)

83

Passing Lists as Arguments

83

Using Perl

83

Perl API structure

84

Common Global Options

86

The Batch API

89

Using the Batch API

89

Installing Commander Perl modules into Your Perl Distribution

91

Installing Perl Modules into the Commander Perl Distribution

91

When Upgrading Commander

API Commands - listed by group and in alphabetical order


API commands listed by group

92

93
93

ACL Management (access control list)

93

Artifact Management

94

Credential Management

96

Database Configuration

96

iii

Directory Provider Management

96

Email Configuration and Management

97

Email Notifiers Management

97

Gateway/Zone Management

98

Job Management

98

Parameter Management

100

Plugin Management

101

Procedure Management

101

Project Management

102

Property Management

102

Resource Management

103

Schedule Management

104

Server Management

104

User/Group Management

105

Workflow Definition Management

106

Workflow Management

107

Workspace Management

107

Miscellaneous

108

API commands listed in alphabetical order

API commands - ACL Management

122

API commands - Applications

164

API commands - Application Tier

169

API commands - Artifact Management

176

API commands - Component

213

API Commands - Credential Management

223

API Commands - Database Configuration

234

API Commands - Directory Provider Management

239

API Commands -Dynamic Enviroment

255

API Commands - Email Configuration Management

302

API Commands - Email Notifier Management

308

API Commands - Environment

339

API Commands - Environment Tier

352

API Commands - Gateways and Zones Management

357

API Commands - Job Management

368

External Job APIs

API Commands - Parameter Management

iv

109

391

417

API Commands - Plugin Management

445

API Commands - Procedure Management

453

API Commands - Process

479

API Commands - Process Dependency

489

API Commands - Process Step

495

API Commands - Project Management

505

API Commands - Property Management

512

API Commands- Resource Management

564

API Commands - Schedule Management

588

API Commands - Server Management

601

API Commands - Snapshots

613

API Commands - Tier Map

622

API Commands - User/Group Management

628

API Commands - Workflow Management

642

API Commands - Workflow Definition Management

651

API Commands - Workspace Management

670

API Commands - Miscellaneous Management

678

API Response and Element Glossary

717

Element Glossary

740

API Access in Javascript

775

How to Use the RESTful API

776

Accessing the RESTful API

777

Using the RESTfulAPI

782

RESTful API Examples

785

POST Operations Without Special Arguments

785

POSTOperations with Special Arguments

787

Access Control

789

Overview

789

Privileges

789

Users and Groups

790

Special Users and Groups

790

Access Control Lists (ACLs) - allow and deny

790

Inheritance

791

System Objects

792

Access Control and Jobs

793

Examples for Increased Security


Example 1 - Basic ACL Setup

794

Example 2 - Team ACL Setup

798

Optional: Restricting Resources and Workspaces by Team

804

Artifact Management

806

Overview

806

Artifact objects

806

Artifact

807

Artifact version

807

Repository

810

Access control

813

Publishing artifact versions

815

Enable compression

815

Include / Exclude patterns

816

Retrieving artifact versions

816

Entering filters during a retrieve operation

818

Dependent artifact version(s)

819

Artifact cache

820

Cleaning up repositories and caches

822

Authenticating Users for LDAP and Active Directory


Configuring LDAP

823
823

Determining LDAP Mapping

825

Sample LDAP User Record

825

Sample LDAP Group Record

826

Sample Active Directory Configuration File

826

Change Tracking
Configuring Change Tracking

vi

794

828
829

Enabling Change Tracking Globally

829

Enabling Change Tracking on a Per-Project Basis

829

Upgrading to ElectricCommander 5.4

830

Customizing the Change History Page

830

Usage Guidelines

830

Change History Search Form

830

Change History Page

833

Paths to Objects

835

Detailed Object Changes

835

Viewing the Change History

836

Viewing the Change History for Artifacts, Jobs, Projects, and Workflows

836

Artifacts

837

Jobs

837

Projects

840

Workflows

840

Modifying the Change History

841

Change History Time Line

841

Change History Filters

847

Reverting and Exporting Changes to Objects

848

Searching Through the Change History

851

Running a New Search Through the Change History

851

Searching Through the Change History From an Existing Change History

858

Credentials and User Impersonation

860

What is a credential?

860

Defining a credential

860

Why use credentials?

860

Credential access control

861

Using credentials for impersonation

861

Setting the impersonation credential


Accessing credentials from a step

862
863

Attaching a credential to a step

863

Passing credentials as parameters

863

Credential references

864

Best Practices for retrieving credentials

864

Customizing the Commander UI


Customizing parameters

866
866

How do you customize parameters?

866

Custom parameter form contents

866

Customizing the tab layout

868

Overview

868

View definition syntax

868

Storing views

871

Default views

871

Developing and troubleshooting

871

Home page configuration

872

User settings

872

Location

872

Installing the Home page

872

Reconfigure Contact Support link

872

vii

Defect Tracking
Example: Enabling the JIRA integration in your procedure

Defect Tracking
Example: Enabling the JIRA integration in your procedure

ElectricSentry

874

877
877

880

How ElectricSentry works

880

Configuring ElectricSentry

880

Quiet time

880

Resource

881

Polling frequency

881

Time-of-day and day-of-week

881

Configuring a build for continuous integration

881

Source Control Management SCM) configurations

882

Create a procedure

882

Create a schedule

882

Optional - running ElectricSentry on multiple resources

882

Overview

883

Configuring ElectricSentry to use multiple resources

883

The Job Step Execution Environment


Terms and definitions

Preflight Builds

viii

874

885
885

888

Why use Preflight Builds?

888

Preflight Build Solution

888

Preflights with Commander

888

Workflow

888

Components

889

Installation

889

Configuration

889

Samples

891

Default SCMs

896

Perforce

896

Subversion

897

AccuRev

898

ClearCase

898

Bazaar

899

Git

899

CVS

900

Mercurial

900

Repo

900

StarTeam

901

TFS

901

Vault

901

Troubleshooting

902

Client

902

Agent

902

Properties

903

Overview

903

Creating or modifying properties

904

Using property values

905

Property sheets and intrinsic properties

905

Property names and paths

906

Absolute property paths

906

Relative property paths

908

Context-relative "shortcuts" to property paths

909

Property path shortcuts in ElectricCommander 5.0 and later

913

Property name substitutions

914

Expandable properties

914

Custom property names and values

915

The property hierarchy

915

Special property references

917

increment

917

timestamp

917

javascript

918

Commander Intrinsic Properties listed by object type


Commander Property Type definitions

919
920

Commander Object / Property tables

921

Property error codes

983

Postprocessors: Collecting Data for Reports

986

Overview

986

Postp

987

Extending postp: matchers

987

Postp functions

988

Integration with the Commander user interface

990

Custom property names and values

990

Diagnostic information

991

Postp integration with Java Tools

992

ix

The process...

992

Java Tool matcher examples

993

Artifacts directory

994

Reports
Run reports on a non-local resource
Real-time reports

995
995

Home page

995

Jobs

995

Job details / Step details

996

Resources

996

Build reports using ecreport

996

Example 1

998

Example 2

998

Default Batch reports (Run Reports)


Report types

1000
1000

Default Batch Reports

1000

Tip...

1001

Advanced reporting information - ecrptdata

1002

How are default batch reports generated?

1002

Filtering

1004

Adding additional data columns to the report

1004

Secure login

Optional Batch reports

1005

1006

Creating a report job

1006

Viewing the report

1008

Optional Batch report examples

1008

Category sample report

1008

Procedure Usage sample report

1010

Count Over Time sample report

1011

Multiple Series report

1014

Optional Batch reports

995

1018

Creating a report job

1018

Viewing the report

1020

Optional Batch report examples

1020

Category sample report

1020

Procedure Usage sample report

1022

Count Over Time sample report

1023

Multiple Series report

1026

Creating Custom reports

1030

Data extraction

1031

Using ecextract.pl for data extraction

1031

Examples

1034

BIRT Report Designer

1037

Understanding additional report components

1038

Packaging reports for Commander

1038

Helper functions provided in ElectricCommander::ReportUtils.pm

1041

Custom Report Examples


Example 1: modifying an existing report - adding a "banner" heading

1043
1043

To copy an existing Commander report

1043

To modify the copied report design

1045

Test your new report

1047

Example 2: complete end-to-end example

1048

Planning this report example

1048

Creating a new BIRT rptdesign file

1049

Deploy your custom report

1059

Test your new report

1060

System Health Monitoring

1063

Workflow Overview

1064

Workflow objects

1065

Workflow Definition

1065

State Definition

1066

Transition Definition

1066

Workflow

1067

State

1067

Transition

1067

Access Control

1068

Property Search Paths

1068

Parameters

1069

Sending Notifications

1069

Workflow Logs

1069

Visualizing a Workflow

1069

Building a Workflow - a Tutorial

1070

To begin...Calling a job from within a workflow

1071

Collecting a parameter when a workflow is launched and passing its value to a job

1073

Retrying a state

1075

Automatically transitioning to different states based on the outcome of a job

1077

xi

Invoking another workflow

1080

Running jobs in parallel

1081

Automatically transitioning to different states based on the outcome of jobs in another workflow

1082

Waiting for manual intervention

1085

Restricting who can take a manual transition

1089

Sending email notifiers

1092

Adding a global parameter to use later in the workflow

1094

Setting the name of your workflow

1096

Workflow List

1098

Another workflow example

Workspaces and Disk Space Management

1101

Overview

1101

Defining Workspaces

1101

Using Workspaces

1102

Workspace Directory Names

1103

Working Directories

1103

Workspace Accessibility

1103

Local Workspaces (Disconnected Workspaces)

1104

Access control

1105

Impersonation and workspaces

1105

Commander managed files

1106

Disk space management

1106

Job Name Template and Workflow Name Template Best Practices

1106

Actions that Will Affect the Counter

1107

Commander 5.0 Name Template Defaults

1107

Commander Installed Tools

1108

Examples

1111

Examples

1116

ecproxy Algorithm

1119

ecproxy Operations

1119

Available Helper Functions

1123

Examples

1126

"Real World" Examples

1127

ClusterExec

1127

MySQL

1127

Android

1128

Copying Other Files from the Workspace

1131

Web Interface Help

xii

1100

1134

Access Control

1135

Reading and Using This Page

1135

Access Control - defining entries

1137

Privileges - create new or edit existing privileges

1138

Artifacts

1139

Artifact Details

1140

General Information section


The "tabbed" sections

1140
1140

Artifact Versions table

1140

Properties table

1141

Artifact - create new or edit existing artifact

1142

To create a new artifact

1142

To edit an artifact

1142

Artifact Versions

1144

Artifact Version Details

1145

General Information section


The "tabbed" sections

1145
1145

Files

1145

Retrievers table

1146

Dependent Artifact Versions table

1146

Properties table

1146

Artifact Version - edit an existing artifact version


To edit an artifact version

1147
1147

Repositories

1148

Repository - create new or edit existing repository

1149

To create a new repository

1149

To edit a repository

1149

Database Configuration

1150

Defect Tracking Configurations

1151

Defect Tracking - create new or edit existing configuration

1152

To create a defect tracking configuration

1152

Using the defect tracking integration

1153

To edit an existing defect tracking configuration

1153

Defect Tracking Reports

1154

Email Notifier - create new or edit existing email notifier

1155

To create a new email notifier

1155

xiii

To edit an existing email notifier

1158

Email notifier templates

1158

Email Configurations

1161

Email Configuration - create new or edit existing email configuration

1162

To create a new email configuration

1162

To edit an existing email configuration

1163

Email Notifier - create new or edit existing email notifier


To create a new email notifier

1164

To edit an existing email notifier

1167

Email notifier templates

1167

Email Notifier Template - Html_JobStepTempl_AllSteps.txt

1170

Email Notifier Template - Html_JobStepTempl_SingleStep.txt

1171

Email Notifier Template - Html_JobTempl.txt

1172

Email Notifier Template - Html_StateTemplate_ApproveWorkflow.txt

1173

Email Notifier Template - Html_StateTemplate_FullWorkflow.txt

1174

Email Notifier Template - JobStepTempl_FullProps.txt

1175

Email Notifier Template - JobTempl_FullProps.txt

1176

Email Notifier Template - StateTemplate_FullPropertyPaths.txt

1177

Event Log

1178

Configuring the Event Log

1178

Jobs

1180

Jobs

1182

Job Details

1184

Summary section (at the top of the page)


The "tabbed" sections

1184
1186

Steps table

1186

Diagnostics table

1187

Parameters table

1188

Properties table

1188

Notifiers table

1189

Published Artifact Versions table

1189

Retrieved Artifact Versions table

1190

Job Step Details


Summary section (at the top of the page)
The "tabbed" Sections

xiv

1164

1191
1191
1192

Child Steps table

1193

General table

1193

Diagnostics table

1194

Parameters table

1194

Properties table

1194

Notifiers table

1194

Job Step Time and WaitTime Properties Explained

1195

Licenses

1197

All Licenses

1197

Current Usage

1197

License Types

1199

Concurrent Resource License

1199

Concurrent User License

1199

Concurrent Step License

1199

Registered Host License

1200

View License

1201

Import License

1203

Plugin Manager

1204

Using a plugin

1206

Configuring the plugins directory

1207

Procedure Details

1208

Procedure Steps

1208

Creating a new step

1208

Parameters

1209

Email Notifiers

1209

Custom Procedure Properties

1209

Procedure - create new or edit existing procedure

1210

To create a new procedure

1210

To edit an existing procedure

1211

Step - create new or edit existing step

1212

To create a new command or subprocedure step

1212

To edit an existing command or subprocedure step

1218

Publish Artifact Version Step

1220

Retrieve Artifact Version Step

1221

Artifact Retrieval Dependency Order Explained

1222

Send Email Step

1224

New Extract Preflight Sources Step

1225

xv

Parameter - create new or edit existing parameter


To create a new parameter

1226

To edit an existing parameter

1228

Projects

1230

Projects have two purposes

1230

ElectricCommander includes default projects

1230

ElectricCommander solutions

1231

Project - Create New or Edit Existing Project

1233

Creating a New Project

1233

Editing an Existing Project

1234

Project Details

1235

The "tabbed" sections

1235

Procedures tab

1235

Workflow Definitions tab

1236

Jobs tab

1236

Workflows tab

1237

Schedules tab

1238

Credentials tab

1239

Properties tab

1239

Reports tab

1239

Run Procedure
Using the Run Procedure page

Schedule - create new or edit existing schedule

1241
1241

1243

To create a new standard schedule

1243

To create a new continuous integration "schedule"

1246

To edit an existing schedule

1246

Credentials - create new or modify existing credential

1247

To create a new credential

1247

To edit a credential

1247

Properties

xvi

1226

1248

Overview

1248

Creating or modifying properties

1249

Using property values

1250

Property sheets and intrinsic properties

1250

Property names and paths

1251

Absolute property paths

1251

Relative property paths

1253

Context-relative "shortcuts" to property paths

1254

Property path shortcuts in ElectricCommander 5.0 and later

1258

Property name substitutions

1259

Expandable properties

1259

Custom property names and values

1260

The property hierarchy

1260

Special property references

1262

increment

1262

timestamp

1262

javascript

1263

Commander Intrinsic Properties listed by object type


Commander Property Type definitions

1264
1265

Commander Object / Property tables

1266

Property error codes

1328

Property - create new or edit existing property

1331

Nested Property Sheet

1332

Reports

1333

Create a new report

1334

Multiple Series Report

1334

Category Report

1335

Count Over Time Report

1336

Procedure Usage Report

1337

Resources
Supported Resource Types
Resource Page Information and Functions

1339
1339
1340

New Resource panel

1347

New Proxy Resource panel

1351

Edit Resource panel

1355

Edit Proxy Resource panel

1355

Resource Details panel

1355

Switching a non-trusted agent to trusted

1356

Install or Upgrade Remote Agents

1356

Prerequisites:

1357

Using the Install or Upgrade Remote Agents dialog

1357

Resource Pools

1366

Resource Pool - create new or edit existing pool

1367

To create a new resource pool

1367

xvii

To edit an existing resource pool

1369

Unusable resources

1369

Resource Pool Details

1370

The "tabbed" sections

1370

Properties tab

1371

Zones

1373

Zone Details panel

1374

Creating a new zone

1374

Access Control notes

1374

Gateways

1376

Gateway Details panel

1377

Create Gateway panel

1377

Edit Gateway panel

1378

Access Control note

1378

Accessing the Resource Templates

1380

Define Search

1382

Search Results

1383

Server

1384

Settings - edit existing property settings

1385

Source Control Configurations

1388

Source Control Configurations - create new or edit existing configuration

1389

AccuRev

1389

ClearCase

1390

File

1390

Git

1390

Perforce

1390

Property

1391

Subversion

1391

Checking out code from a source control system

1392

To edit an existing source control configuration

1392

The Home Page


Overview

1393

Job Configurations

1393

Create Job Configurations three ways


Shortcuts
Create Shortcuts two ways

xviii

1393

1393
1394
1394

Jobs Quick View


Create a job category
Reports

The Home Page

1394
1394
1395

1396

Overview

1396

Job Configurations

1396

Create Job Configurations three ways


Shortcuts
Create Shortcuts two ways
Jobs Quick View
Create a job category
Reports

Job Configuration

1396
1397
1397
1397
1397
1398

1399

To create a new job configuration

1399

To edit an existing job configuration

1400

Shortcuts

1401

Jobs Quick View

1402

To create a new jobs quick view category

1402

To edit an existing jobs quick view category

1403

New Report
To populate the drop-down menu...

1404
1404

Active Users

1405

Users and Groups

1406

User - create new or edit existing local user

1408

To create a new local user

1408

To edit an existing local user

1408

User Details

1409

Edit User Settings

1410

Groups

1411

Group - create new or edit existing local group

1412

To create a new local group

1412

To edit a local group

1412

Group Details

1413

Directory Providers

1414

Directory Providers - create new or edit existing directory providers

1415

Commander supports Active Directory and LDAP directory providers

1415

xix

To create a new Active Directory provider

1415

To create a new LDAP directory provider

1418

Examples for directory provider field descriptions

1421

To edit an existing directory provider

1422

Test Directory Provider

1424

Workflows

1425

Workflow Definition - create new or edit existing workflow definition

1426

To create a new workflow definition

1426

To edit an existing workflow definition

1426

Workflow Definition Details


Graph view

1429

To create a new state

1430

To create a new State Definition

1431

To create a Transition Definition

1435

Using the graph's "quick-access" features

1437

Show Legend

1438

List view

1439

Properties view

1442

Run Workflow

1443

Workflow Details

1444

Summary section - at the top of a running workflow page

1445

When the workflow is complete...

1446

Graph tab

1447

Show Legend tab

1447

Using the graph's "quick-access" features

1448

Show History

1448

States tab

1450

State Details panel

1451

Parameters tab

1454

Properties tab

1454

Workflow Log

1456

Transition Workflow

1458

Workspaces

1459

Workspace - create new or modify existing workspace

1461

To create a new workspace

1461

To edit an existing workspace

1462

Workspace file

xx

1428

1463

Tutorials

1464

Adding a link to a job

1465

Implementation

1465

Related information

1466

Calling a subprocedure

1467

Implementation

1467

Related information

1468

Checking outcome of preceding step

1469

Implementation

1469

Related information

1470

Conditional execution

1471

Implementation

1471

Related information

1472

Custom parameter layouts

1473

Implementation

1474

Related information

1474

Email notifications

1475

Implementation

1475

Related information

1477

Executing tasks on all resources in a pool

1478

Implementation

1478

Related information

1478

Factory procedures

1480

Implementation

1481

Related information

1482

Postp extension

1483

Implementation

1484

Related information

1484

Publishing and retrieving an artifact

1485

Implementation

1486

Related information

1486

Reserving a resource for job step duration

1487

Implementation

1487

Related information

1487

Running steps in parallel

1489

Implementation

1489

xxi

Related information

Step timeouts and steps that always run

1491

Implementation

1491

Related information

1491

Storing and retrieving properties in a job

1492

Implementation

1492

Related information

1492

Working with properties stored in a procedure

xxii

1490

1494

Implementation

1495

Related information

1495

Welcome to ElectricCommander
What makes Commander unique?
Commander architecture

Overview
ElectricCommander is an enterprise-class solution for automating the software build, test, and release process.
Commander helps teams make software build, package, test, and deployment tasks more repeatable, more
visible, and more efficient.
At its core, ElectricCommander is a web-based system for automating and managing the build, test, and release
process. It provides a scalable solution, solving some of the biggest challenges of managing these "back end"
software development tasks, including these challenges:
l

Time wasted on script-intensive, manual, home-grown systems that


o Are error prone
o Do not scale well
o Have little or no management visibility or reporting

Multiple, disconnected build and test systems across locations, resulting in:
o Redundant work
o Inability to share or reuse code files across teams
o Hard to manage build and test data

Slow overall build and release cycles that directly impact:


o Release predictability
o Time-to-market

Commander tackles these problems with a three tier architecture, AJAX-powered web interface, and first-of-itskind build and release analytic capabilities for reporting and compliance. With this solution, your developers,
release engineers, build managers, QA teams, and managers gain:
l

Shared platform for disseminating best practices and reusing common procedures

Ability to support geographically distributed teams

Continuous integration and greater agility

Faster throughput and more efficient hardware utilization

Visibility and reporting for better project predictability

Better software quality by integrating and validating against all target platforms and configurations

ElectricCommander

What makes ElectricCommander unique?


Only ElectricCommander provides enterprise-class speed and scalability for software build and release
management. It is easy to install and use on a simple build, yet scales to support the largest and most complex
build and test processes. Commander distributes jobs in parallel across multiple resources for faster overall
cycle time.
Commander supports multiple teams, working in multiple locations, programming in multiple languages in an
environment that can be centrally controlled and managed. Shared assets and reuse make individual teams
more efficient by eliminating duplicate work, and gives organizations the power to deploy cross-company
standards.
Commander's unique analytics provide visibility into one of the best indicators of project success: compiled,
tested, working code. Commander's analytics database stores all build and test information for real-time and
trend reporting giving your organization the power to collect pinpoint statistics and to gain visibility into
important productivity metrics such as trends in error rates. Additionally, out-of-the-box reports provide
information about cross-project status and build trends by project and resource utilization. Commander's
integration with virtual lab automation (VLA) solutions also allows you to snapshot or reproduce a specific build
for auditing or troubleshooting purposes.
Commander provides unified process automation across the entire build/test/deploy lifecycle and across
heterogeneous tools via integrations with leading ALM tools. Integrations with SCM tools enable continuous
integration, triggering builds whenever code is checked into the specified repository/branch. When used with
VMware Lab Manager, Commander can dynamically provision either physical or virtual resources without
manual intervention. This feature delivers efficient, dynamic resource provisioning and reduces development
and QA dependence on IT operations.

What you do
To use Commander, you need to:
l

Configure resourcesThese are machines Commander can use to run jobs.

Define proceduresThese are the tasks you want to automate and contain one or more steps.

Create schedulesThese define when each procedure will run.

What Commander does


After setting up resources, procedures, and schedules, Commander takes over to run the procedure that you
created. Here are some of the facilities ElectricCommander provides:
l

Zones and GatewaysA zone (or top-level network) that you create is a way to partition a collection of
agents to secure them from use by other groups. A gateway is a secured connection between two zones
when you want to share or transfer information between the zones. For example, you might want a
developers zone and a test zone. The Commander server is a member of the default zone, created
during Commander installation.

Welcome to ElectricCommander

Continuous Integration Builds and other schedulesRun jobs according to schedules that you define.
Scheduled jobs can run at specific times or when source code changes are checked in to your source
control system. Commander integrates with major source control systems. The Continuous Integration
Dashboard allows you to add more projects easily and create build configurations quickly so you can
visually see running builds, build status, and so on.

Artifact Management functionalityUsing artifacts can improve performance across builds, provide better
reusability of components, and improve cross-team collaboration with greater tractability. For example,
instead of developers repeatedly downloading third-party packages from external sources, these
components can be published and versioned as an artifact. Developesr then simply retrieves a specific
artifact version from a local repository, guaranteeing a consistent package from build to build.

Preflight build functionalityUsed by developers to build and test code changes in isolation on their local
machines before those changes are committed to a production build.

Plugin capabilityCommander is built with an extensible UI, enabling easy development of plugins that
include integrations with other tools, custom dashboards, and unique user experiences based on roles.
"Bundled" plugins, installed during Commander installation, provide easy integration with your SCM
systems, defect tracking applications, and so on.

Workflow functionalityUse a workflow to design and manage processes at a higher level than
individual jobs. You can use workflows to combine procedures into processes to create build-test-deploy
lifecycles (for example). A workflow contains states and transitions that you define to provide complete
control over your workflow process. The Commander Workflow feature allows you to define an unlimited
range of large or small lifecycle combinations to meet your needs.

Resource managementIf a resource is overcommitted, Commander delays some jobs until others are
finished with the resource. You can define pools of equivalent resources, and ElectricCommander
spreads usage across the pool.

Recording a variety of information about each job, such as the running time and the success or failure of
each step. A set of reports is available to provide even more information.

Powerful and flexible reporting facilitiesVarious statistics such as number of compiles or test errors are
collected after each step and recorded in the ElectricCommander database. A variety of reports can be
generated from this information.

Allowing you to observe jobs as they run and to cancel jobs or change their priorities.

Workspace for each job, which is a disk area a job uses for storageCommander also provides a facility
for reclaiming space occupied by workspaces.

Powerful data model based on propertiesProperties are used to store job input data such as the source
code branch to use for the build, to collect data during a job (such as number of errors or warnings), and
to annotate the job after it completes (for example, a build has passed QA).

Access control for users logged into the systemCommander uses this information to control their
activities and integrates with Active Directory and LDAP repositories.

Search, sort, and filter functions to minimize viewing or "wading" through information that is of no interest
to you, allowing you to access to the information you need quickly.

Email notifications to get important information or data to individuals or groups immediately and on a
regular basis for a particular job or a specific job aspect.

All Commander operations and features are available from a command-line application tool, ectool, and
a web interface.

ElectricCommander

Schedules
Schedules are used to execute procedures and determine when specific procedures run. A schedule can
trigger at defined times, for example, every 2 hours from 10:00 pm to 6:00 am on Mondays, Wednesdays, and
Fridays, or when modifications are checked into a particular branch of your source code control system. It is also
possible to create a schedule that runs immediately and disappears after the job runs. When you create a
schedule, you must provide the parameters required by the procedure that you want to invoke.
The Continuous Integration Dashboard works with your source code management (SCM) system and provides
visibility into running builds, the ability to add a project to continuous integration quickly, and easily accessed
configuration pages to setup or modify a continuous integration schedule.

Workflows
Managing a build-test-deploy product lifecycle spanning multiple procedures and projects requires a significant
amount of "meta-programming" and a heavy use of properties, and the workflow feature simplifies this process.
Using the Commander workflow object, you can create build-test-deploy lifecycles by defining a set of states
and transitions. Any Commander project can contain a workflow.

Projects
A project is an object used in Commander to organize information. A project is a container object for
procedures, steps, schedules, workflows, and properties. If you use Commander for different purposes, you can
use a separate project for each purpose so different projects do not interfere with each other. When you work in
one project, you do not normally see information in other projects. At the same time, a project can use
information defined in other projects, which allows you to create shared library projects.

Procedures and Steps


Procedures and steps define tasks that you want Commander to execute. A procedure consists of one or more
steps. A step includes a command or script executed on a single resource and is the smallest unit of work that
Commander understands. Each step specifies a resource on which it should run (either the name of a specific
machine or the name of a resource pool of equivalent machines, in which case Commander picks a machine
from the pool). A step can be given a time limit, and if the step does not complete within the specified time,
Commander automatically aborts it.
Steps are ordered within a procedure and normally execute sequentially. However, it is possible to mark a
consecutive range of steps for parallel execution, so all steps in that range run concurrently.
You can define parameters for procedures. Parameter values are assigned when procedures are scheduled.
Parameters can be required, optional, or have default values. Parameters are used for a variety of purposes
such as specifying the branch to build or the set of platforms on which to run tests. Parameter values can be
used in step commands and many other places.
Procedures can be nested. A step in one procedure can invoke another procedure instead of running a
command. The invoking step provides parameters needed by the nested procedure, also referred to as a
subprocedure.

Welcome to ElectricCommander

Jobs
A job is a Commander object that is created each time a procedure begins to execute or run. The job keeps
track of all data associated with the procedure's execution, such as the running time of each step and any errors
that may occur during the step. Commander retains job information after the job completes so you can examine
what occurred.

Resources
A resource is a server machine available to Commander for running steps. A resource has a logical name and a
host name. In some situations, it is convenient to have multiple logical resources associated with the same host.
A resource can also be associated with one or more pools. Each resource has a step limit that determines the
maximum number of steps that can execute simultaneously on the resource. Resources can be grouped into
resource pools.

Commander architecture
ElectricCommander was designed to support small, mid-range, or enterprise scale software production. Based
on a three-tier architecture, Commander scales to handle complex environments. The Commander multithreaded Java server provides efficient synchronization even under high job volume.
l

The Commander server manages resources, issues commands, and generates reports.

An underlying database stores commands, metadata, and log files.

Agents execute commands, monitor status, and collect results in parallel across a cluster of servers for
rapid throughput.

ElectricCommander

Simple architectural overview

Expanded remote configurations


ElectricCommander is not limited by only the components illustrated above. The following screen example
illustrates a remote web server configuration.
The next illustration is an example for how you might set up a remote web server installation.

Welcome to ElectricCommander

This type of remote web server configuration helps prevent network latency. If you have multiple sites,
Commander can be configured to help you work more efficiently.

Other possible configurations


l

Proxy (universal) resources

Remote database

Multiple remote web servers

Multiple remote repository servers

Configurations designed specifically for failover

ElectricCommander

Getting Started
Basic Commander terminology
Getting Started Scenarios help topic series
Navigating the Commander user interface

Overview
ElectricCommander is an application for automating and managing your development lifecycle, the software
build, test, and deployment process. Commander helps development teams make these tasks repeatable,
visible, and efficient.
Commander creates an environment where IT and Development organizations can work together to connect
physical and virtual environments, processes, and tools already in use to create a private development cloud,
also known as a smart development cloud. Commander is a scalable solution, solving some of the biggest
challenges of managing "back-end" software development tasks.

Basic Commander terminology


Understanding Commander terminology will helps you understand the Commander concepts and processes,
providing an overview of how Commander works for you.
Object
Project

Description
Commander uses a project as a container for related procedures or any
procedures you choose to group together. Your project can contain as many
procedures as you decide are necessary.

Procedure

A procedure contains a group of steps, each performing a task to do the work


you define. You can define as many steps as you need for each procedure.
Procedures are reusable indefinitely or can be modified whenever you choose.

Step

Using almost any kind of script, you can define a specific task for a step to
perform. Steps can run in parallel for faster processing. Steps can be modified or
copied to other procedures whenever you choose.

Getting Started

Object
Plugins

Description
Commander is built with an extensible architecture, allowing easy development
of plugins that include integrations with other tools, custom dashboards, and
unique user experiences based on roles. Numerous plugins are installed during
the Commander installation, which makes them transparent to the user. For
example, in the Scenario 1 and Scenario 2 Help topics, you will configure a
source control system and build an Ant step, both of which use plugin
technology.

Parameter

This is a value that Commander passes to a procedure to control the procedure


operation.

Schedule

A standard schedule defines when your procedure will run. You can control the
hour and day that your procedure runs or use a trigger to run a procedure each
time a particular event occurs.

Continuous integration

The Continuous Integration Manager (CI Manager) provides a front-end user


interface (dashboard) for creating, managing, and monitoring continuous
integration builds. For example, using your preferred SCM, you can run a
procedure to build your software every time you check in code.

Resource

A resource is an agent machine configured to communicate with Commander.


Your steps can run on any resource or resource pool that you define. Resources
can be grouped into a pool to increase the processing speed by assigning steps
to less loaded members of the pool. Pools can also be used to ensure the
resources you need are available only to a specific group of developers.

Job

This records the results of running a procedure. Each time you run a procedure,
a job is created. You can view the results of running the procedure and each
step within the procedure. Tables are on the Job Details page to view or manage
your results or to use for future reference.

Report

Reports display your information graphically for review or to show trends and
other information.

ElectricCommander

Object
Workspace

Description
Commander provides a default area on the disk that it can use for working files
and results. This disk area is called a job workspace. A job step can create
whatever files it needs in its workspace, such as step logs, and Commander
automatically places these files in the workspace. A single workspace can be
shared by all steps in a job, but it is possible for different steps in a job to use
different workspaces. The location of the job step workspace is displayed on the
Job Details page for the job under the "Details" for the step.

Zones

A zone is a way to partition a collection of agents to secure them from use by


other groups. For example, you might choose to create a developers zone, a
production zone, and a test zone. The agents in one zone cannot directly
communicate with agents in another zone.

Gateways

To communicate with a resource, workspace, or artifact repository server in


another zone, a gateway must be created. A gateway object contains two
resource (agent) machines. For example, GatewayResource1 and
GatewayResource2 are configured to communicate with the other. One gateway
resource resides in the source zone and the other in the target zone. A gateway
is bidirectional and informs the Commander server that each gateway machine
is configured to communicate with a gateway machine in another zone.

Getting Started Scenarios help topic series


The series of scenario Help topics are designed to help you learn to use Commander quickly. Follow the stepby-step scenario format to learn Commander basics:
l

Creating a simple procedureScenario 1

Creating a procedure that uses a Source Code Management (SCM) system Scenario 2

Setting up email notifications, reporting, and schedulingScenario 3

Creating a multi-agent build procedureScenario 4

Each scenario builds on what you learned in the previous scenario, and each scenario ends with one or more
scenario extensions to introduce you to other related Commander functionality.

Navigating the Commander user interface


To quickly link to task pages, view running or completed jobs, configure resources and so on, the Commander
web interface displays tabs across the top of the page. These tabs remain available at the top of all Commander
web pages.
When you select some of the main tabs, subtabs are provided. For example (see the next screen example),
when the Home tab is selected, notice that the Overview tab is in bold font, which means you are looking at the

10

Getting Started

Overview page. This page can be customized to show the information that you want to see quickly. You can use
this page for shortcuts, quick links to jobs, "thumbnail" report views, and so on.
Selecting the Continuous Integration subtab takes you to the Continuous Integration Dashboard, which is place
to configure your projects for continuous integration builds.

In addition to the main set of tabs, the top bar includes:


l

Logged in as clearly shows the name of the logged-in user.

LogoutUse this link to logout between Commander sessions if necessary.

HelpThis link provides a help topic for the current page you are viewing, but if you select the downarrow adjacent to the Help link, you have access to the following:
o TutorialsUse this link to display the Table of Contents for all currently available tutorial examples

you may find useful as you become familiar with Commander.


o Welcome ScreenThis link displays the Welcome Screen again when you would like to revisit

available Commander videos or other product information.


o DocumentationUse this link to access the entire Commander online help system, which is fully

searchable in the event you do not quickly see what you are looking for in the left-pane Table of
Contents.
The Help Table of Contents contains feature overview/concept user-guide style help topics, which
are not linked to a particular web page. These topics are listed in the Table of Contents above the
"Web Interface Help" section. The Web Interface Help section contains all of the page-specific help
topics.
Note: To print a Help topic Right-click your mouse in the Help topic pane or go to your browser File
menu.
o Visit the Community SiteThis link takes you to the Electric Cloud Knowledge Base, all product

documentation, and so on.


o Contact SupportUse this link to access the Electric Cloud Technical support phone number and

email address. At a later time, you may choose to reconfigure this link to redirect it to your internal
support time. See the "Reconfigure Contact Support" section in the "Customizing the Commander UI"
Help topic.
o About-Use this link to display the current version of Commander you are using.

The Home tab


You can customize the Home page to see the information you need at-a-glance or add Shortcuts to quickly
return to a Commander pages you visit frequently. The Home page provides four categories:
l

Job Configurations
Commander procedures can contain complex sets of parameters, making it difficult to remember the
correct parameters for a particular situation and tedious to re-enter those parameters every time the
procedure is invoked. Job Configurations provide a one-click solution to this problem.

Shortcuts
Use shortcuts to save frequently visited Commander web pages, so those pages are immediately
accessible. You can also create a shortcut to any page on the web.

11

ElectricCommander

Jobs Quick View


The Jobs Quick View allows you to define job categories that are interesting to you. You may be
interested in a few jobs on this server. For example, you want only information about jobs that you
launch manually and official builds for the products you work on. You do not want information about
production builds for other products or personal jobs for other users.

Reports
You can configure reports you would like to see on a regular basis and display a thumbnail"report
graphic in this section.

In the following Home page example, there are additional links. This page allows you to create, edit, and delete
objects you see so that you can easily keep the page updated and current.
For more information about Home page functionality, see the Home Page Help topic.

The Continuous Integration subtab


The Continuous Integration Manager (CI Manager) provides a front-end user interface (the Continuous
Integration Dashboard) for creating, managing, and monitoring continuous integration builds.
The Continuous Integration Dashboard provides:

12

Visually seeing your running builds, build progress, build status, and accumulated build status.

Easily accessed "Actions" to configure a continuous integration build.

Quick configuration of your preferred SCM system.

A project that contains any number of continuous integration builds, depending on the work you have
already setup for your procedures and steps to perform.

Getting Started

The following is an example of the dashboard. Your initial view will be blank until you add configurations (using
your preferred SCM) to run your build procedures continuously. When this tab is opened to view the dashboard,
click the Help link in the upper-right corner of the page for instructions to begin using the dashboard.

Projects, Jobs, and Workflow tabs


Selecting the Projects, Jobs, or Workflows tab displays a table listing all previously configured projects, all
completed jobs, or all previously configured workflows, respectively. Each table contains links in the table and
links in the section above the table.
For example, selecting the Projects tab displays a table (see the next screen example), which has the projects
you created and Commander default projects, which were added during Commander installation.
l

Links at the top of the table include:


o A "star" iconClick this icon to add this page to your Home page.
o A drop-down menu to choose which projects you want to see.
o Create Project link to go to the New Project page to define and add a new project.
o New Search link to find a project whose name you may not remember or projects of the same type.

Links within the table include:


o Click on a Project name (first column) to go to the Projects Details page for that project.
o Actions columnThis column usually contains links to Edit, Copy, or Delete the object, which is a

project in this example.


Each table, Projects, Jobs, or Workflows, has similar links to help you get more information, modify existing
information, or create a new object. For more information on any of these Commander pages, see these Help
topics: Projects, Jobs, or Workflows.

13

ElectricCommander

Cloud tab
This tab opens to the Resources page and provides several other subtabsPools, Workspaces, Zones,
Gateways, and the Cloud Manager plugin if it is installed.

The Resources page


The following example displays all resources that you configured Commander to use.
l

In the information immediately after the Resources title at the top of the table, you can see how many
licensed resources are in use.

Use the row of buttons at the top of the page to perform resource management tasks.

A resource name, in the Name column in the table, is a link to open the Resource Details panel for
more information about the resource, and to access the Edit Resource panel to change or add access
control privileges.

See the Resources Help topic for more information.

The Pools subtab


Click this subtab to display a list of all resource pools available to Commander. You may find it useful to group
resources, creating one or more resource pools. For example, you can have resource pools for specific
purposes, development teams, or other groups in your organization.
Similar to the Resources page, this page provides:

14

Getting Started

A link to create a new resource pool.

A Search link to find an existing resource pool.

Summary information for each resource pool in the list.

Clicking the resource Pool Name takes you to the Resource Pool Details page for more information
about that pool.

And the Action column contains Copy and Delete links.

For more information about pools, see the Resource Pools or Resource Pool - create new or edit existing pool
Help topics.

The Workspaces subtab


Similar to the Resources and Pools pages, the Workspaces page displays a table all available workspaces and
summary information for each workspace.
Available links are:
l

Create Workspace for adding another workspace.

New Search to find an existing workspace.

Clicking the Workspace Name takes you to the Edit Workspace page to make modifications.

And the Action column contains Copy and Delete links.

For more information about workspaces, see the Workspaces and Disk Space Management, Workspaces, or
Workspaces - create new or edit existing workspace Help topics.

The Zones and Gateways subtabs


Similar to the other subtabs under the Cloud tab, the Zones and Gateways subtabs each have a table, listing all
available zone or gateways, respectively.
l

Selecting an object in the Name column takes you to the "Detail" page for more information.

These pages are your management centers for zones or gateways, respectively.

For more information, see the Zones and Gateways Help topics.

Artifacts and Search tabs


This page displays all artifacts available on this Commander server. It has Projects, Jobs, and Workflows pages,
Create, Edit, and Delete links for the artifact. Clicking on an artifact Name (first column) takes you to the Artifact
Details page. For more information, see the Artifact Management Help topic.

15

ElectricCommander

The Artifact Versions subtab


The Artifact Versions page displays all artifact versions available on the Commander server. Links in the table
are the similar to other Commander pages. For more information, see the Artifact Versions Help topic.

The Repositories subtab


The Repositories page displays all artifact repositories available to the Commander server. For more
information about repositories, see the Artifact Management and Repositories Help topics.

Search tab
While many Commander web pages have a Search link, some do not. The Search page is always available.
You can search any Commander supported object type on this page. For more information, see the Define
Search Help topic.

Administration tab
The next screen example shows all the current subtabs available when you select the Administration tab. Lessfrequently used tasks are grouped for you as subtabs under the Administration tab. For example, after users and
groups are set up, you do not need these pages unless a user or group configuration changes.

Administration subtab descriptions:

16

Event LogThis page displays a log of events generated anywhere in the system, including jobs and
workflows.

GroupsUse this page to view a filtered list of Commander local users or groups.

UsersUse this page to view a filtered list of Commander local users or groups.

Getting Started

LicensesThis page displays all license information known to the Commander server. Typically, a single
license is displayed, which describes the usage to which you are entitled. The license on the server may
be based on concurrent resources, concurrent users, concurrent steps, registered hosts, or any
combination of these licenses.

Directory ProvidersCommander uses account information from multiple sources. In most cases, the
primary account information source is an external LDAP or Active Directory repository: both user and
group information is retrieved from the repository. Local users and groups are defined in Commander.

Email ConfigurationsThis page displays all previously configured email configurations. You must
create an email configuration so Commander can communicate with your mail server to send email
notifications

Database ConfigurationIf you do not use the Commander-supplied default database, use this page to
configure another database to communicate with Commander. See the ElectricCommander Installation
Guide for a list of approved databases for use with Commander.

PluginsThis subtab displays the Plugin Manager page. A plugin is a collection of one or more features
that can be added to Commander. Numerous plugins are bundled and installed with Commander,
integrating third-party products seamlessly with Commander. For example, Source Code Management
plugins are installed and so that you can configure your preferred SCM to communicate with
Commander.

ServerThis page displays overall information about the Commander server. Use the Settings or Access
Control links to make changes.

Source ControlThis page displays all SCM (source code management) configurations you have
created to communicate with Commander.

Defect Tracking - This page displays previously configured Defect Tracking systems known to the
Commander server.Use plugins to integrate Commander, with numerous defect tracking systems.

Go to Scenario 1

17

ElectricCommander

Getting Started - Scenario 1 - Creating a simple


procedure
To begin, select the Projects tab, then the Create Project link at the top of the table. You need to create a
project to contain the procedures you create.
On the New Project page, enter information in the fields as follows:
Field Name

Description
Type a unique project name. You may want your project names to reflect the
work groups or teams that will be using them. For example, you might set

Name

project names based on the products they support.


For our scenario examples, we will use "FirstNewProject" for our project name.

Description

Default Resource

Default Workspace

Enter a text description for your reference if you choose. ElectricCommander


does not use or interpret this information.
(optional) For the purpose of "getting started", leave this field blank to use the
Default resource already created during the Commander installation.
(optional) For the purpose of "getting started", leave this field blank to use the
Default workspace already created during the Commander installation.

Click OK to save the information you entered.


After clicking OK, you see the Project Details page and the name of the new project adjacent to the page title.

18

For our scenarios, the project name is FirstNewProject.

Your new project name will appear on the Projects page also.

Getting Started - Scenario 1 - Creating a simple procedure

Scenario requirement: No additional requirements for this scenario. This scenario uses the local agent
(resource) that was included on your local machine when Commander was installed.

Overview
This scenario establishes that Commander and its components were installed successfully and guides you
through creating a simple procedure with a parameter that will echo Hello World. After you create this
procedure, you will run the procedure and review the results.
At the end of this scenario, you will be familiar with the following Commander concepts and features:
l

Projects

Procedures

Steps

Parameters

Jobs

Navigating the Job Details web page

Begin Scenario 1
Step1. Select the Projects tab
On the Projects page, you can see the default projects installed during the Commander installation and the new
project you just created.
Select your new project name to go to its Project Details page, then click the Create Procedure link.

Step 2. Create a procedure


On the New Procedure page, you need to be concerned with the section of the page illustrated below only.
Enter the following information:

19

ElectricCommander

Field Name

Description
For this scenario, Hello World is the procedure name.

Name

At a later time when you are creating your own procedures, you can choose
any unique name that is most meaningful for procedures in your project.

Description

(optional) Enter a text description for your procedure if you choose to do so.
Use the Browse link and choose local.

Default Resource

Using local accesses the agent installed during the Commander installation.
At a later time after you have configured other resources, your Browse list
could contain many choices.

Your New Procedure page will look similar to the following:

Before leaving this page, notice the "breadcrumb" in the top-left corner. Most Commander web pages
contain a breadcrumb for easy return to the previous page.
Click OK to continue.
After clicking OK, Commander takes you to the Procedure Details pagethis is the page you use to add
important information to your procedure. When your procedure contains steps, parameters, or email notifiers,
and so on, those objects will be displayed here for your reference.

Step 3. Create a parameter


A Commander procedure can define one or more parameters. These parameters are similar to the parameters
of a subroutine in a programming language. Parameters allow you to define a "re-usable" procedure by using

20

Getting Started - Scenario 1 - Creating a simple procedure

symbolic variable names in place of a single, fixed value. When you run the procedure, you can type in a value
to use for that particular job. You can refer to the parameter in a step for a procedure, using the standard
Commander "property reference syntax" - $[...].
For example, see Step 4, specifically the text in the Command(s) text box.
On the Procedure Details page, click the Create Parameter link to go to the New Parameter page.
Enter the following information:
Field Name

Description

Name

Enter the parameter name message for this scenario.

Type

Use the default Text entry for the parameter type.

Default Value

Type-in Hello World for the default parameter value.

Your New Parameter entries will look like the following:

Click OK after filling in the fields and Commander returns you to the Procedure Details page.
On the Procedure Details page:
Notice the Parameters table is populated with your parameter entry.

21

ElectricCommander

Also notice the name of the procedure we created (Hello World) is shown adjacent to the page title for your
reference.

Step 4. Create a step


Now we can create a step on this procedure. On the Procedure Details page, to create a New Step for our
current purpose, click the Command link to go to the New Step page.
On the New Step page:
The following screen displays the portion of the New Step page you need for this scenario.
Notice this version of the New Step page contains a Command text box to enter the information you need.
At a later time, when you choose to create a different step type, the New Step page will be populated with
the appropriate fields required for that step type.
Enter the following information:
Field Name

Step Name

Description

22

Description
Use Print message for the step name. For work outside this scenario, you
can enter any unique name of your choice for the step name.
(optional) Add a text description about this step if you need one.

Getting Started - Scenario 1 - Creating a simple procedure

Field Name

Description
Type echo $[message]
In this command, message refers to the parameter we created.
Note: The Commander Server does not actually interpret (or even understand)
the contents of this field. Commander simply expands all property references

Command(s) box

and then passes the resulting text block to the Commander Agent. The Agent
copies the text block to a temporary file and then invokes the Agent's native
shell command, passing the name of the temporary file as a parameter to the
shell command. The overall result is the same as if you had created this block
of text as a BAT file (on Windows) or a shell script (on Linux). The operating
system of the Agent machine takes over from that point to actually run your
commands.
For this scenario, leave this field blank to use the default resource you set on

Resource(s)

the procedure. If multiple resources are configured, you have the option to
change the resource for each step if you prefer.

Your New Step page will look like the following example:

Click OK to create the step and Commander returns you to the Procedure Details page to see its entry as
displayed in the next screen example.

23

ElectricCommander

Step 5. Run the procedure


Notice the green-circle-arrow Run icon among the links at the top of the tables. If you click the Run link, the
procedure will run as-is immediately.
For this scenario, hover your mouse over the adjacent down-arrow and select the Run... option.
Selecting this option provides the Run Procedure page where you can add or modify the parameter value(s) as
necessary.

The Run Procedure page has the information we want for this scenario, so click the Run button.
When a procedure runs, it creates a "job".

After clicking Run, Commander takes you to the Job Details page to see the status of the "job" and watch its
running progress.
This web page supplies a wealth of other information.

24

Getting Started - Scenario 1 - Creating a simple procedure

The Job Details page contains two sections. The section at the top of the page is the jobs summary, displaying
the jobs status and other general information:
l

The "green check" icon is displayed to show the job completed successfully.

The "Completed with Success" section displays the result of the procedure that ran.

The General Information section displays the project and procedure names and who launched the job.

The section below the summary area displays detailed job information, including tabs to expand information
and links to access various other Commander web pages.
l

Notice the "Success" entry in the Status columnthis is your step result.

In the Log column, click the icon in the Print message row to see the outcome/result of your Hello World
Print message step. Your file will look similar to the following:

Select the Parameters tab to see the parameter you created and its value.

For complete information about the Job Details page functions and available information, click the Help link in
the top-right corner of this Commander web page.

Scenario extension - Adding another step


Each procedure you create can contain as many steps as you need. We created only one step in this scenario.
This example shows how to modify a procedure by adding additional steps. You can always add more steps or
edit an existing step before you run a procedure again.
To add a step to an existing procedure:

25

ElectricCommander

1. On the Job Details page, select your procedure name (at the top of the page) to go to the Procedure
Details page.
2. On the Procedure Details page, click the Command New Step link again.
3. On the New Step page, enter information in the fields as follows:
o NamePrint Step Info
o Command(s)Enter the following text:

print "This step was launched by $[launchedByUser] on the resource


$[/myResource/resourceName].\n";
o Shellec-perl
o Click OK to save the step and return to the Procedure Details page.

Note: You can move this new step to the top of the procedure by hovering your mouse over the icon
next to the step name, then drag-and-drop the step to the top of the list. This is a useful function
particularly if you find you have created steps in a different order in which you need them.
Click Run (from the Procedure Details page).

Finding a Commander web page...


If you "lose" the Job Details page or any other Commander web page, several navigation methods are
available:
l

Use your browsers Back button if you were recently on a page you want to revisit.

Use Commander "breadcrumbs." On some pages you see breadcrumbs on the left-side of the page that
note your current position/level within the project.

Use the tabs at the top of the page to drill-down to the page you need.
For example:
o To find the Job Details page:

Select the Jobs tab and notice that your procedure name is now listed in the Job column,
accompanied by a date, job number, and other related job information on the same row. When you
run a procedure, it becomes a job. Select the job you want to see and you will go to the Job Details
page for that job.
o To find the Procedure Details page:

Select the Projects tab, then select your project to go to the Project Details page to see a list of
procedures in that project. Click on a procedure to go to the Procedure Details page for that
procedure.
Note: A "project" is a container for all related procedures you create. You can create as many projects as you
need, using the Create Projects link on the Projects page.
As you use Commander, you will quickly learn other navigation paths for your particular interests. In addition,
most Commander web pages contain a "star" icon in the upper-right corner. Click this icon to add that page to
your Home page for quick "one-click" access in the future.

26

Getting Started - Scenario 1 - Creating a simple procedure

Summary
This simple Hello World procedure demonstrated how to quickly create a procedure and how any command
can be wrapped and parameterized using a Commander procedure. If you have an existing script you want to
automate, you can call that script within a step command block. This scenario also introduced you to running a
job, entering parameters for the job, and viewing results for the job you ran.
Go to Scenario 2

27

ElectricCommander

Getting Started - Scenario 2 - Creating a procedure


that uses an SCM
Scenario requirements: Before you begin this scenario, Commander needs to be able to access your Source
Control Management (SCM) system.

To set up a Source Control system (SCM) to use with Commander, you


need:
l

a running SCM system

an active source depot in your SCM system

a Commander agent that can communicate with your SCM server


Note: If the machine where you installed Commander can communicate with your Source Control (SCM)
server, this requirement is met. If not, return to the installation executable file and run the Commander
Agent install program on a machine that has access to your SCM system.

To install Commander agent software on another machine, copy the installation executable file to that
machine, then double-click on the file to run the installation program. Select Express Agent when the install
window opens.
When installation is complete, configure this new agent as a Commander Resource. See the beginning of
Scenario 4 for more information.
o Configure Commander to communicate with your SCM system.
o Select the Administration tab, then the Source Control subtab.
o The Source Control Configurations page displays a table listing Source Control configurations after

you create them. Click the Create Configuration link and the following web page is displayed.

o On the New Source Control Configuration web page, use the drop-down menu to choose your SCM

type.
For our example, we chose Perforce.
o Depending on which SCM you choose, the page expands to display appropriate fields for entering

values to configure your SCM.


See the next screen example.
Enter information in the fields as follows:

28

Getting Started - Scenario 2 - Creating a procedure that uses an SCM

Configuration Name - For our example, we use the name, "p4". You can choose any name for your
SCM Configuration.
Note: You will need this name later, so remember the name you choose for your SCM configuration. A
configuration name is important because you may want to create more than one source control
configuration.

P4PORT - For our example, we use p4:3710 to designate the P4PORT. Your specification will be
different.

Important: Other fields remain blank to use the defaults, but you may need to specify some or all
information in the remaining fields depending on how your internal systems and access are set up for
access to your SCM system.

Click OK after filling-in the fields.


For additional help with this Commander web page, click the Help link in the top-right corner of the web
page.

Overview
This scenario guides you through creating a common build process integrated with your SCM system and build
utility. And you will learn how to navigate and modify the procedure definition using the Commander Procedure
Details web page.
At the end of this scenario, you will be familiar with the following Commander concepts and features:
l

Source control configuration

Creating more complex steps

Creating a build process

29

ElectricCommander

Navigating the Procedure Details web page

Begin Scenario 2
Step 1. Select the Projects tab
On the Projects page, select the project name you created in Scenario 1 (in the first column) to go to the Project
Details page, then select the Create Procedure link to begin.

Step 2. Create a procedure


On the New Procedure page, enter a Procedure Name - it is required.
You can use any unique name you choosedo not use the same procedure name you chose for Scenario 1.
Procedure names within the same project must be unique.
l

Name - For this scenario, we use Basic Build for the procedure name.

Default Resource - Use local for the resource name.

Click OK to go to the Procedure Details page.

Step 3. Create a parameter


On the Procedure Details page (illustrated above), click the Create Parameter link to go to the New Parameter
page.

30

Getting Started - Scenario 2 - Creating a procedure that uses an SCM

Name - For our example, the parameter name is target. You can choose any unique name of your
choice for your parameter nameparameter names must be unique within a procedure.

Default Value - We chose jar for this value.

Click OK to continue and to return to the Procedure Details page to see the parameter you just created.

Step 4. Create a step to checkout source files from your SCM system
From the same Procedure Details page, click the Plugin link to create a New Step.
l

In the Choose Step dialog, select Source Code Management from the left pane.

Next, select ECSCM-Perforce from the list, then select "ECSCM-Perforce - Checkout" from the right
pane.

Click Close to go to the New Step page, which will be populated with the fields you need to enter for the
Perforce SCM.
o Both the Subprocedure and the Parameters sections are populated with fields to enter information so

Commander can communicate with your Perforce SCM system, using the Commander Perforce
plugin.
Note: Depending on the SCM you chose to work with, including Perforce, the New Step screen you see
may be different than the following example. If you need additional help configuring your SCM, see the
corresponding SCM plugin on the Plugin Manager page. Each plugin has its own Help topic.

31

ElectricCommander

Enter information in the fields as follows:


Field Name

Name

Description

32

Description
Enter a unique name for your subprocedure step. For this scenario, the step
name we supplied is checkout.
(O ptional) Enter a text description for this step.

Getting Started - Scenario 2 - Creating a procedure that uses an SCM

Field Name

Description

In the Subprocedure section:


This section displays the subprocedure name or a plugin name because the plugin is being called as
subprocedure.
Note: The plugin name defined: "EC" is for Electric Cloud, "SCM" identifies the plugin as belonging to the
Source Control Management category, and "Perforce" identifies the name of the source control system.
Our example illustrates the fields for the Perforce SCM plugin. Your fields will be different if you are using a
different SCM. These parameter fields request some of the same values you already specified when you
created the Source Control Configuration.
Clicking this link takes you to the Project Details page for the plugin. Generally,
ECSCM-Perforce

and for this scenario, you do not need to access this page to make changesit
is for your reference only.
Clicking this link takes you to the Procedure Details page for this procedure.

CheckoutCode

Generally, and for this scenario, you do not need to access this page to make
changesit is for your reference only.
Clicking this link displays a dialog that allows you to change the project,
plugin, or subprocedure. If you make a change in the Change Subprocedure

Change

dialog, the Subprocedure and Parameters sections on the New Step page will
update automatically with corresponding fields for your new choice.
Note: All SCM plugins that can checkout code contain the checkoutCode
procedure.

Resource

The local resource was specified earlier. If this field remains blank, the
local resource is used.

Note: The following two parameter fields are common among all SCM plugins:
config

The name of your Source Control Configuration.


The destination where you want to put your checked-out codeit is the

dest

directory within your job workspace. Each job adds a new directory to the
workspace. At this point, you have not defined multiple workspaces, so the
Commander default workspace is used.

For more information about workspaces, see the "Workspaces and Disk Space Management" Help topic.
Click OK after entering values and to continue to the Procedure Details page, which should now look similar to
the following example:

33

ElectricCommander

The Procedure Details page now displays the name of our new procedure, Basic Build, and its new
checkout step using the Perforce SCM, and the target parameter with the jar value.

Step 5. Create a step to run the build


This step can be another subprocedure step, a command step, or a custom step. Any procedure can contain
multiple types of steps, any of which may be either simple or complex.
Steps can contain or use:
l

parameters and/or properties

many of your existing scripts, including shell scripts

For this step example (to run the build), we will create an Ant step. To invoke Ant, you could write a script that
calls Ant directly, or you could call the Commander Ant plugin to invoke the runAnt procedure. For this
example, we will use the Commander Ant plugin.

34

From the Procedure Details page, click the Plugin link to see the Choose Step dialog and select the
Build category.

Select the EC-Ant plugin to see and select the "Ant - Run Ant" step.

When the New Step page is displayed, notice the Subprocedure section is populated with the chosen
EC-Ant plugin, and the Parameters section provides the appropriate fields for this Ant step.

Getting Started - Scenario 2 - Creating a procedure that uses an SCM

Enter information in the fields as follows:


Field Name

Name

Description
For this example, we specified AntBuild for the step name. You can use any
unique name you choose for this step.

Subprocedure section:
Note the EC-Ant plugin project name and the runAnt procedure name.
Resource

Leave this field blank to continue using the local resource.

Parameters section:

35

ElectricCommander

Field Name

Description

Build File

Use build.xml.

Target

For this example, we used $[target].

Working Directory

For this example, we used project.

For this scenario, we leave the remaining fields blank, but you may need to enter additional information
depending on your Ant invocation.
Click OK to continue and return to the Procedure Details page.
The following screen example illustrates the two steps we created for this scenario.

Step 6. Running the procedure


On the Procedure Details page, hover your mouse over the small down-arrow on the right-side of the Run link,
choosing Run...
l

Run Immediately - This option runs the procedure immediately as set.

Run... - This option displays the Run Procedure web page where you may alter any existing parameters
for this procedure, or set an existing credential.
Note: This scenario does not introduce you to the Advanced section of the Run Procedure page.
For more information on these topics, click the Help link in the top-right corner of the Run Procedure
page.

36

Getting Started - Scenario 2 - Creating a procedure that uses an SCM

Click Run to run the procedure and continue to the Job Details page to see the status of your running job.

Step 7. On the Job Details page


The Job Details page now displays the status and results of running the Basic Build procedure.
Your Job Details page will look somewhat different if you supplied other values in this scenario.

More about the Job Details page


l

The General Information section at the top of the table provides links back to the Project > Procedure
that was launched to create this job.

Click on a Step Name to go to the Job Step Details page.

Click the Parameters tab to see parameters in this job.

If there are errors, the Diagnostics tab has specific information.

37

ElectricCommander

More about the Procedure Details page


To go to the Procedure Details page at any time:
l

Select the Projects tab.

Select the Project name (that contains the procedures you want to see) to go to the Project Details page.

Select a Procedure name to go to the Procedure Details page.

You may want to review to the Procedure Details page frequently because it displays the steps that make up
your procedure, the parameters contained in the procedure, email notifiers, and so on. Full edit capabilities are
available by selecting any object (step, parameter, and so on).
Also, you can run this procedure again on demand by clicking the Run link at the top of the page.
For more information about the Procedure Details page functions, click the Help link in the top-right corner of the
Procedure Details page.

Scenario extension - Add a step to show workspace contents


If you are curious about what your current default workspace contains at this point, you can create a step to see
the workspace.
l

Select the Projects tab, select FirstNewProject (or your project name if you used something different),
select the Basic Build procedure name.

Click the Command link to create a New Stepa new command step.

The New Step page is displayed with a Command text box.


o For Name, use seeWorkspace.
o In the Command(s) text box:
l

for Windows - type dir /s

for Linux - type ls -r

Click OK to create the step and go to the Procedure Details page.

Click Run to create the job and to go to the Job Details page.

When the job is completed, click the log icon in the Log column to see the contents of the current workspace for
this procedure. Your Workspace File will be similar to the following example:

38

Getting Started - Scenario 2 - Creating a procedure that uses an SCM

Summary
This scenario demonstrated how easily Commander can integrate with your SCM system and build utilities.
Go to Scenario 3

39

ElectricCommander

Getting Started - Scenario 3 - Notification, scheduling,


and reporting
Scenario requirements: For this scenario, you need to set up an Email Configuration to use the email
notification feature.

To set up an Email Configuration:


l

Select the Administration tab, then select the Email Configurations subtab.
You will see a blank Email Configurations page. As you create one or more email configurations, they
will be listed in table format on this page.

Click the Add Configuration link.

On the New Email Configuration page, enter information in the fields to define your mail system.

Field Name

Description

Name

Enter a unique name for your email configuration.

Description

(Optional) Enter a text description for your reference.

Mail Protocol

Use the drop-down arrow to make a selection.

Mail Host

Enter the name of your mail host.

Enter information in the remaining fields according to the specifications you need.
Your New Email Configuration page should look similar to the following example:

40

Getting Started - Scenario 3 - Notification, scheduling, and reporting

Click Save after filling-in the fields or click the Test button first if you want to make sure your email
configuration works.
Enter an email address in the pop-up box and click Send.
Note: For additional help with this Commander page, click the Help link in the top-right corner of the page.

Overview
This scenario guides you through creating an email notification, invoking your build process with a timed
(standard) schedule, invoking your build process using a continuous build integration trigger, and introduces
Commander reporting features.
At the end of this scenario, you will be familiar with the following Commander concepts and features:
l

Creating an email configuration

Creating an email notifier

Creating schedules

Creating reports

Begin Scenario 3
Step 1. Creating an email notifier
On the Procedure Details page for the Basic Build procedure, click the Create On Completion Email Notifier
link to begin. This link takes you to the New On Completion Email Notifier page.

41

ElectricCommander

Two email notifier types for jobs or job steps:


l

On Start NotifierSends an email when a job or job step starts.

On Completion NotifierSends an email when a job or job step completes.

The fields for each of these notifiers are similar, but we chose the On Completion notifier because you may find
you use this one more frequently.
On the New On Completion Email Notifier page:
Enter information in the fields as follows:
Field Name

Name

Description

Description
For this example, we use BuildTeam. This name can be an arbitrary text
string.
(Optional) Enter a text description for your reference. Commander does not
use or interpret this information.
Use the pull-down menu to select the type of condition you need for this email
notifier. Edit the auto-supplied condition in the text box or add a completely

Condition

new script for your purpose. The condition specifies whether the notifier should
send a message depending on the result of a property expansion. If the result
is empty, non-zero, or "true", the message is sent. If the result is "0" or "false",
the message is not sent.

42

Getting Started - Scenario 3 - Notification, scheduling, and reporting

Field Name

Description
For this example, choose the "Job summary HTML" notification template, or
you can use the drop-down menu to select from a list of global, ready-to-use
formatting templates. Depending on the type of email notifier you are creating,
the available template choices in the drop-down menu will be different.

Formatting Template

To customize your template, edit the auto-supplied text in the Formatting


Template text box, or you can add a completely new template for your
purpose. Note: Any edits made in this text box will not be saved to the global
template, and the template will appear as a Custom template when you return
to this notifier definition. Additionally, make sure the content is formatted
correctly, i.e., no illegal characters or spacing.

Email Configuration

Use TestEmailConfig, the email configuration we created.


This is a space-separated list of valid email addresses, email aliases, or

Destinations

ElectricCommander user names, or a property reference that expands into


such a list.

After filling-in the fields, your page may look similar to the following example:

Click OK to create your email notifier and to return to the Procedure Details page, where you can now see
the Email Notifier you created.

43

ElectricCommander

Note: For more information, see the Email Notifiers help topic.

Step 2. Creating a standard schedule


To create a standard "timed" schedule:
l

Select the Projects tab.

Select your project name to go to the Project Details page.

Select the Schedules subtab, then select the down-arrow to the right of the " Schedule" link, and choose
"Standard Schedule" to go to the New Schedule page.

On the New Schedule page:


The following is an example of the New Schedule page.
l

Notice the "breadcrumb" above the New Schedule page titlethis entry displays the name of the project
that will contain this schedule.

After entering a name (unique within your project) for your schedule (we chose "Sentry-MainBuild"),
choose the procedure your schedule will run.
o Click the Change link adjacent to the Procedure field.
o In the pop-up menu, leave the Current project selected.
o Place your cursor in the Procedure field to see a list of procedures in your project.
o Select the procedure you want this schedule to run. We chose "Basic Build".

44

Getting Started - Scenario 3 - Notification, scheduling, and reporting

Enter information in the remaining fields as follows:


Field Name

Description
(optional) A plain text or HTML description for this object. If using HTML, you
must surround your text with <html> ... </html> tags. The only HTML tags

Description

allowed in the text are: <a> <b> <br> <div> <dl> <font> <i> <li>
<ol> <p> <pre> <span> <style> <table> <tc> <td> <th> <tr>
<ul>

Parameters section
If the procedure has parameters, enter their values in this section. The procedure cannot execute unless all
required parameters are provided.
Frequency section
"Run at" is a summary section: As you make selections for the following Days and Repetition sections, a
summary of what you selected appears here.

45

ElectricCommander

Field Name

Description
Select weekdays, month days, or create a custom frequency when you want

Days

the schedule to run.


Note: The "day" applies to the start time if the time range spans two days, that
is, if the time range crosses the midnight boundary.
If Run Once - the schedule will run once per selected day, at the time you
specify.
If Run Every - the procedure will execute repeatedly during the specified time

Repetition

range. For example, if you select a time range from 11:00-14:00 and an
interval of 40 minutes, the procedure will execute 5 times on each of the
selected days: at 11:00 am, 11:40 am, 12:20 pm, 1:00 pm, and 1:40 pm.
If Run Continuously - as soon as one job ends, the scheduler will trigger
immediately to run the job again.

Advanced section

Enabled

If this box is "checked," the schedule will run. You can disable this schedule
whenever necessary.

Note: For this scenario, you do not need to enter information for any remaining fields. Later, when creating an
actual timed schedule for one of your procedures, refer to the help topic for this page for more information.
Click OK to save your information and create this schedule.
At any time, you can return to the Project Details page for this project, select the Schedules subtab, and then
select the Schedule Name from the table to go to the Edit Schedule page to modify this schedule.

Step 2a. Creating a continuous integration build trigger


At a later time when you have procedures and steps created to do the work you need, you may prefer
implementing continuous integration build configurations for your software builds. Unlike a standard schedule
that runs on days and times you specify, a continuous integration build can be triggered to run each time code is
checked into your source code management (SCM) system.
Adding a project to the Continuous Integration Dashboard is quick and easy. Each project can have one or
more CI configurations, depending on the number of source branches you want to monitor. After the simple
configuration process, you can visually see status and other information about your continuous integration jobs
as builds are triggered to run.
To find the Continuous Integration Dashboard, select the Home tab, then select the Continuous Integration
subtab. The dashboard will be empty until you start adding projects. For help using the Continuous Integration

46

Getting Started - Scenario 3 - Notification, scheduling, and reporting

Manager and Dashboard, click the Help link in the upper-right corner of the dashboard web page.

Step 3. Creating a report


Commander provides multiple reports and custom report capabilities to help you manage your build
environment.
Summary of available report types:
l

Real-time reports - filtered view of your Commander data in real-time

Build reports - summary reports produced at the end of a build and attached to the job

Batch reports - summaries of your build environment with trends over time, two types:
o Default Batch reports - automatically installed during ElectricCommander installation and scheduled

to run daily (Cross Project Summary, Variant Trend, Daily Summary, Resource Summary, Resource
Detail)
o Optional Batch reports - you can configure and schedule these reports to fit your requirements

(Category, Procedure Usage, Count Over Time, or Multiple Series reports)


l

Custom reports - your choice to create and add at any time

Note: Batch and Custom reports must be run on the Commander server agent (local agent) only. These
reports use the BIRT report engine, which is installed only on the Commander server.
Defining a saved search
Before you create a report, you need to define a "search" to focus the report on the information you want to see.
l

Select the Search tab to go to the Define Search page.

Enter information in the fields as follows:


Field Name
Number of results
Results Per Page
Object Type

Description

For this example, do not alter the default settings in these fields as you see
them. These fields do not affect the search you are creating.

For this example, choose Job for this search.


Click the Add Intrinsic Filter link one or more times as needed to further

Intrinsic Filters section

define the sort criteria for your search. We selected Project Name from the
drop-down menu and typed-in our project name, then selected Procedure
Name and typed-in our Basic Build procedure name.

Custom Filters section

Not needed for this scenario.

Your Define Search page will look similar to the following example:

47

ElectricCommander

Click OK after filling-in the fields and to go to the Search Results page.

Click Save Filter to see the Save Filter dialog box.

In this dialog box, use the drop-down arrow to select the project name for your report, then enter a name of
your choice for the filter. We used BasicBuildFilter for the filter name to tie the filter name to the Basic
Build procedure for which we are creating a filter.

48

Getting Started - Scenario 3 - Notification, scheduling, and reporting

Click OK to return to the Job Search Results pagenow we are ready to define the report we want to see.

Define the report


For this scenario, we will create an Optional Batch report. Select the Projects tab, select your project name to go
to the Project Details page, then select the Reports subtab.
Click the Create Report link.

On the Optional Batch Reports page:


For this scenario, select the Multiple Series report tab.
Enter information in the fields or select the appropriate values as follows:
Field Name

Description
This is your report title. Type over the default report name, choosing any

Report Title

unique name for your report. We supplied Basic Build Report for our
report name.
Project - Click your mouse inside this field to see a list of projects from which to

Saved Filter

make a selection. We select our FirstNewProject project name.


Filter - Use the BasicBuildFilter we created earlier.

Time Period

Use the drop-down menu to select the time period.


Check this box so you can view this report on your Home page.

Create thumbnail?

(We will create a thumbnail report view on your Home page at the end of this
scenario.)

49

ElectricCommander

Field Name

Description

Object Type

Use the drop-down menu to select Job for this example.

Table column choices


Chart Type

Use the drop-down menu to choose the chart type.

Function

Use the drop-down menu to choose the function you need.


Use the default property value or delete the text and click your mouse in the

Property Name

blank field to see a list of possible properties. We chose "outcome" for this
example.

Display Name

You can choose a different unique Display Name if you prefer to do so.

Stacked

Select this checkbox to see your report results "stacked" versus overlaid.

The "X" icon

Click this icon to delete any row you no longer need.

Add Series button

Chart Options

Select this button if you would like to create additional table entries for
additional report information.
Use the down-arrow to adjust the Time Grouping and see the defaults for the X
and Y axis.

Your Multiple Series report page will be similar to the following example:

50

Getting Started - Scenario 3 - Notification, scheduling, and reporting

Run Report button - (information only for this scenario) this button takes you to the Job Details page to
run the report immediatelyone time only.

Click the Create Schedule button - this button displays a box with a default schedule name you can
change.

Enter a name for the scheduleagain, we tied the schedule name to the procedure name for which we
want the report.

Click OK to go to the Project Details page.

Now you can see the report you just created listed in the Schedules table.
Click the Run link in the Actions column to run this report and then go to the Job Details page.

On the Job Details page , you will see your report running.
When the report is generated, you will see a Links section in the summary section at the top of the Job
Details page.
This section contains a link to the report you generated.
Click this link to see your report.

51

ElectricCommander

For more information about the Job Details page, click here.
For more information about Commander reports, see the Reports, Creating Custom Reports, and other
report Help topics.

Scenario extension - Add a thumbnail report to your Home


page
When we created a report, we "checked" the Create thumbnail? checkbox, so we are ready to activate the
thumbnail report view on the Home page.
Note: Viewing an interesting report assumes there is ample data to report. While you can see a report after
running one job, it is not very interesting unless you can see trends or comparisons after running numerous
jobs.
To see a thumbnail report on the Home page:
l

Select the Home tab.

Click the Add Report link and a New Report page is displayed.

On the New Reports page:

52

Getting Started - Scenario 3 - Notification, scheduling, and reporting

Project - Use the down-arrow to select the project containing the report you want to view
FirstNewProject.

Report - This is the report name you entered in the Report Title field when you configured this report
Basic Build Report.

Title - This is the report title you want to see on your Home page to identify this report. We used the same
Basic Build Report name.

Click OK to generate the thumbnail report view and to go to the Home page.

The following screen example illustrates how your Home page may look with the thumbnail report.

For more information about how to use the Home page, see The Home Page Help topic.

Summary
This scenario demonstrated how to create an Email Configuration so you could use an email notifier, how to
create a continuous integration schedule, and how to set up a basic report with a "thumbnail" report view on
your Home page.
Go to Scenario 4

53

ElectricCommander

Getting Started - Scenario 4 - Multi-agent build and


test
Scenario requirements: For this scenario, you can use the configurations you created for Scenario 2 and 3.
However, before you begin this scenario, you need to configure an additional agent machine. If you have a
firewall running on the Commander server machine, disable it now or allow access to ports 8000, 8443, 61613,
80, and 443.

Installing Commander Agent software:


Install Commander Agent software on the machine you intend to use as an agent to run builds. For the simple
purpose of getting started, install this agent on a different machine with the same operating system as the
Commander server.
l

Copy the ElectricCommander installation executable file to the machine you intend to use as a
Commander agent.

Double-click the executable file to begin the installation program.

When the installation program opens, select the Express Agent installation.
Note: During the agent installation, you will have the opportunity to create a resource and provide a
resource name. Enter any name you choose for your new resource. For this scenario, we will name our
new resource, Resource2.

After agent installation, verify that your new resource information is included in the Commander resource
table.
o Select the Cloud tab to go to the Resources page.

Note: At a later time when you are more familiar with Commander, you can use the Resources page to
install additional agents. See the Resources page Help topic, then specifically review the "Install or
Upgrade Remotes Agents" section. Currently, with Commander v4.2, this new functionality available on the
Resources page is available only for Linux agents.

54

Getting Started - Scenario 4 - Multi-agent build and test

To configure a shared workspace:


For Linux
If your agents are installed on Linux, change the default workspace to point to a network location accessible to
both machines:
l

Select the Cloud tab, then select the Workspaces subtab, to see a list of workspaces.

Select the workspace named default to edit the default workspace.

Change the value of the UNIX Path to a network location accessible to the Commander server and
agent machines.

Make sure this location is readable and writable by the users chosen during the server and agent
installations.

After fulfilling these scenario prerequisites, you are ready to proceed.

For Windows
If using a Windows environment, the shared workspace is created for you already.

Overview
This scenario guides you through creating a multi-agent build and test process integrated with your SCM
system, build utility, and unit/system tests. You can invoke this build using a schedule, Continuous Integration
(CI), or "on demand". At the end of this scenario you will be familiar with the following ElectricCommander
concepts and features:
l

Agent-only installation

Copying a procedure to create a new procedure

Running steps in parallel

Pools

Post processor

Search

Begin Scenario 4
Step 1. Create a new procedure
This time, we are going to copy an existing procedure, rename it, and add another step.
l

Select the Projects tab, then select the FirstNewProject project name.

On the Project Details page, click the Copy link to copy the Basic Build procedure.

55

ElectricCommander

When the Basic Build copy procedure is displayed, you can click its name to go to the Procedure Details
page to verify it contains the same contents of the Basic Build procedure.

Return to the Project Details page.

Select the Edit link for the Basic Build copy procedure.

On the Edit Procedure page:


l

NameEnter a new procedure name, MultiAgentBuild.

DescriptionAdd a description noting this procedure was copied from the Basic Build procedure.

Default ResourceSelect your new resource, Recource2, for this procedure.

Click OK after entering your information and Commander will take you back to the Project Details page.
Your Project Details page should now look similar to the following example:

56

Getting Started - Scenario 4 - Multi-agent build and test

This page now displays the new MultiAgentBuild procedure with a description, and a new resource is
designated for this procedure to use.

Step 2. Create two new Ant steps


l

Beginning on the Project Details page, click the MultiAgentBuild procedure name to go to the Procedure
Details page.

Click the AntBuild step Copy link, twice.

Now you see two additional steps names: AntBuild copy and AntBuild copy 2.

Click the AntBuild copy step name to go to the Edit Step page.

Notice the AntBuild copy step name is adjacent to the page title because this is the step we are going to
edit.

Modifications for creating the new Ant steps:


Because this is an "Edit" page, some of the fields already contain the information we originally supplied to
create the first Ant step. The following list contains the fields we need to edit or add new information:
l

NameFor this example, we chose unittest for the step name. Type over the existing text to edit the
text.

ResourceEnter the name, TestPool, because we will be creating a resource pool for testing. At this
point, you need to enter a pool name only (no spaces in the name).

TargetEdit this field to: unittest

In the Advanced section:


l

Run in ParallelClick the check box to select this option. You are designating that you want this step to
run in parallel with one or more other steps.

Click OK to create the first of two new Ant steps and Commander returns you to the Procedure Details page.

57

ElectricCommander

From the Procedure Details page, click the AntBuild copy two step name to go to the Edit Step page again.
To create the next Ant step, make the same edits (above) as you did to create the unittest step, except:

58

Getting Started - Scenario 4 - Multi-agent build and test

NameChange the step name to systemtest.

targetChange this field to: systemtest

Click OK to create the second of two new Ant steps and to return to the Procedure Details page. You now have
three Ant steps, including two new Ant steps, unittest and systemtest, with TestPool as the designated
resource.

Also notice, the Parallel column now contains "checkmarks" for the 2 steps we want to run in parallel.

Step 3. Create a resource pool


Select the Cloud tab to see the following Resources page with a table listing the currently available resources.

To put these two resources in a resource pool that we previously "named" when we created the new Ant steps,
we need to edit each resource.
Click the local resource name to go to the Resource Details panel, then click the Edit link at the top of the
panel.
On the Edit Resource panel:
The only change we need to make is to add the TestPool pool name to the Pool(s) field.

59

ElectricCommander

Click OK to save your change and return to the Resources page.


l

Notice the Pool(s) column now has TestPool specified as a resource pool where the local resource is a
member.

Repeat this process to put Resource2 in the TestPool resource pool.

A resource can belong to one or more pools. If any resource belongs to multiple pools, all pools would be listed
in this column. For more information about the Resources page, click here or click the Help link in the top-right
corner of the web page.
The following screen example should be similar to your Resources page.

60

Getting Started - Scenario 4 - Multi-agent build and test

Step 4. Run the procedure


To run the new MultiAgentBuild procedure, select the Projects tab > FirstNewProject project name >
MultiAgentBuild procedure.
On the Procedure Details page:
l

Click the Run link at the top of the page.

Click Run on the Run Procedure page.

Your Job Details page should be similar to the following example.

Note: The screen example above illustrates a job that is still runningnotice the green circular-arrow icon
at the top of the page. This icon changes to a "checkmark" if this job completes successfully.

Scenario extension - Using postp


ElectricCommander implements data collection with a postprocessor. The postprocessor is a command
associated with a particular procedure step. If the postprocessor is specified for a step, it executes concurrently
with the main step command. The postprocessor runs on the same machine as the main command and in the
same working directory, and it retrieves the log file from the step as its standard input.

61

ElectricCommander

The standard Commander postprocessor is called postp. postp scans the step's log file looking for interesting
output such as error messages and then sets properties on the job step to describe what it found. For example,
postp might create a property named "errors" whose value is the number of error messages in the log file, or a
property named "tests" that counts the number of tests the step executes. Also, postp can extract portions of the
step log that contain useful diagnostic information and save this information for reporting.
When you create a step, you can specify postp. If you already have a step and want to add postp reporting, you
just have to edit the step to include postp.
l

From the previous Job Details page screen example, click the Edit link for the AntBuild step.

On the Edit Step - AntBuild page, in the Parameters section, add postp to Postp Line field.

Click OK to save your edit and return to the Job Details page.
Run this job again to see the postp resultclick the Run/Run Again link.

62

Getting Started - Scenario 4 - Multi-agent build and test

On the next screen example, notice the AntBuild step now shows "3 compiles" in the Status column. Using postp
supplies additional information.

For more information about using postp, see the "Postprocessors" Help topic.

Summary
This scenario demonstrated how ElectricCommander can drive a complete build and test processincluding
building steps to run in parallel and creating a resource pool. This scenario also provided a brief look at how
you can use Commander to execute rapid root cause analysis by reviewing postp diagnostics.

63

ElectricCommander

Configuring ElectricCommander
Use this page for quick access to configuring resources, workspaces, email configurations, your source control
system, and defect tracking to communicate with ElectricCommander.
Note: If you are viewing this help topic from the "Configuring ElectricCommander" web page, use these
instructions:
Click the Add link for any object you want to configure and that objects configuration page is displayed.
l

Each item you configure will be listed in this table for your easy reference.

Configure objects listed in this table are linked to their respective "Edit..." page in the event you
need to modify any values previously supplied. Select a configured object to edit its values.

The table below provides a brief description of Commander


configuration tasks
Click on one of the "Setting Up..." links to see more information about that topic.
Setting Up Resources

Before resources can be set up, you need to know which agent machines
are available to allocate to jobs. The Commander Resource web page
displays all resources currently available to the ElectricCommander
server.

Setting Up Workspaces

ElectricCommander provides each job step with an area on the disk it can
use for "working files" and results. This disk area is called a job
workspace.
A job step can create whatever files it needs within its workspace and
Commander automatically places files, such as step logs, in the
workspace. The location of the job step workspace is displayed on the
Job Details web page.

Setting Up Email

If you do not create an Email Configuration, you will be unable to send

Configurations

email notifications to individuals or groups.


If you have multiple users or groups in remote locations who use a
different mail server, you will want to create additional email
configurations to accommodate those locations if they need to receive
notifications.

64

Configuring ElectricCommander

Setting Up a Source

Commander needs to communicate with your Source Control system

Control Configuration

(SCM) if you intend to use the CI Dashboard for continuous integration


schedules to start a new build based on new/modified source control
checkins, or if you plan to configure Preflight builds (to build and test code
changes before those changes are "committed").

Setting Up Directory

Commander uses account information from multiple sources. In most

Providers

cases, the primary account information source is an external LDAP or


Active Directory repository: both user and group information is retrieved
from the repository. Local users and groups can be defined within
Commander.

Setting Up Defect

Commander uses plugins to integrate with numerous defect tracking

Tracking

systems. If the plugin you need for your defect tracking system is not
automatically installed with Commander, see the Plugin Catalog to find
the integration you need.

Web Interface Online Help System


Use ElectricCommanders online help system for more information. Click the Help link in the top-right corner of
any product web page to see a specific help topic for that page.
When the help system opens, Electric Cloud recommends reviewing the Help table of contents. All Help folders
above the Web Interface Help folder are user-guide style help topics that provide more detailed information on
each of their topics. If you generally prefer to use a command line rather than the Commander web interface,
you will find complete ectool (the Commander command-line tool) commands and arguments here too.

65

ElectricCommander

Setting Up Resources
Before resources can be configured, you need to know which agent machines are available for allocation to
jobs. The Resources page displays all resources currently available to the ElectricCommander server. This
page is your Resources management centeryou to create, modify, or delete resources, see resource status,
pools or zones where resources reside, and much more.
Selecting the Cloud tab displays the Resources page.

What is a resource?
A resource specifies an agent machine where steps can execute and...
l

each resource has a logical name

each resource refers to an agent machine by its host name

several resources can correspond to the same physical host

each resource can be assigned to one or more pools, or one zone

A pool is a group of interchangeable resources. For example, you might have a pool of Windows servers.
Naming a pool in a procedure step allows Commander to assign that step to any resource in the pool, which
means Commander can choose a lightly-loaded resource and a pool makes it easy for you to change your
server configuration.
l

you can specify a resource or a pool name in a procedure step to execute that step on that resource/pool

you can define custom properties for your resources or resource pools

For example, if configuration information varies from resource to resource, you can use custom properties to
hold this information and then reference it from procedure steps where it is needed. Suppose you have a pool of
test machines where the test hardware is in a different location on each machine. You could define a property
named "testLocation" on each resource, then pass this property to procedure steps using a reference such as
$[/myResource/testLocation]. This approach allows you to define procedure steps to run on any resource
and automatically handle configuration differences.

Commander supports two resource types


l

Standard

Proxy

Standard Resources
This resource type specifies a machine running an installed Commander agent on one of the supported agent
platforms, as specified in the ElectricCommander Installation Guide, chapter 2, "System Requirements and
Supported Platforms."

Proxy Resources
This resource type requires SSH keys for authentication. You can create proxy resources (agents and targets)
for Commander to use on numerous other remote platforms/hosts that exist in your environment. A proxy agent

66

Setting Up Resources

is a Commander agent, channeling to a proxy target.


l

Proxy agent - This is an agent on a supported Linux or Windows platform, used to proxy commands to
an otherwise unsupported platform. A proxy agent is a Commander agent, channeling to a proxy target.
Proxy agents have limitations, such as the inability to work with plugins or communicate with ectool
commands.???

Proxy target - This is a machine on an unsupported platform that can run commands via an SSH server.

When a step is running on a proxy resource, the proxy agent performs the following tasks:
o Uploads the commandFile to the Working Directory on the proxy target via SSH
l

Working Directory - the step runs in this directory on the proxy target, which defaults to the UNIX
path to the workspace

o Creates a wrapper sh shell script to:


l

CD to the Working Directory

set COMMANDER_environment variables that exist in the proxy agents environment

run the commandFile that was uploaded earlier

o Uploads the wrapper script to the Working Directory on the proxy target
o Runs the wrapper script on the proxy target
o Cleans up script files on the agent and proxy target

Setting up SSH keys


If you are not familiar with setting up SSH keys, go to the knowledge-based article called "Setting up SSH Keys
in preparation to use a Proxy Agent" in the Electric Cloud Support Web Site:
1. Go to https://electriccloud.zendesk.com/hc/en-us/categories/200176553-ElectricCommander.
2. In the Commander KBsection, enter KBEC-00049 in the Search field.
3. Click Search.
4. Click the link to the knowledge-based article called "KBEC-00049 - Setting up SSH Keys in preparation
to use a Proxy Agent" to open it.
On UNIX, the Commander agent looks in the ~/.ssh directory for the private and public key files to set up the
SSH connection to the proxy target. Therefore, Electric Cloud recommends generating your key files in that
directory.
On Windows, the Commander agent does not presume a default location. Therefore, in the proxy resource
definition you must specify the key file location. Enter the following line in the resource Proxy Customizations
field:
setSSHKeyFiles('c:\ foo\priv.key');

To create a new resource


Click the Cloud tab in the Commander web interface to go to the Resources page.

67

ElectricCommander

At the top right-side of the table, click the


icon to select the Create Resource or Create Proxy
Resource link to see the New Resource or New Proxy Resource panel.
From either panel, New Resource or New Proxy Resource, click the Help link in the upper-right corner of the
page to access the Resources Help topic to see descriptions and other information to assist with filling-in the
fields.

Gateways and zones


ElectricCommander provides the capability of establishing security zones for agents and repository servers.

What is a zone?
A zone consists of a collection of resources that can directly communicate with each other. Within a large
corporation, a zone may encapsulate a physical site, and communication between the two sites occurs through
firewalls.

Cross-zone communication
The following figure shows an example gateway and zone configuration with two zones and three machines.

Cross-zone communication is managed by proxying requests through specially marked resources called
gateway resources. In the previous example, if the Commander server wants to run a command block process
step on an agent in Zone B, it issues its request through GatewayAgent1. The request includes extra metadata
that instructs GatewayAgent1 to forward the request to the target agent. The firewall is configured to allow
connections from GatewayAgent1 to GatewayAgent2. It is also configured to allow connections from
GatewayAgent2 to GatewayAgent1. This is necessary because API communication (CLI commands and the
step completion message) is sent from GatewayAgent2 on its own outbound connection to the server (through
GatewayAgent1).

68

Setting Up Resources

Because the firewall separates two private networks, there's no guarantee that IP address ranges in one
network do not overlap with those of the other. When either gateway agent wants to connect to the other, the
gateway agent uses an IP address to the firewall that is valid for its side of the firewall.

What is a gateway?
The details of this connection information are recorded in a gateway object in Commander. Using the previous
example as a reference, a gateway object consists of the following information:
l

Name of a gateway resource in one zone (GatewayAgent1)

Name of a gateway resource in another zone (GatewayAgent2)

Host/port GatewayAgent2 uses to communicate with GatewayAgent1 (e.g. the firewall IP address in
ZoneB)

Host/port GatewayAgent1 uses to communicate with GatewayAgent2 (e.g. the firewall IP address in
ZoneA)

Support for gateways


The previous example shows two zones for simplicity, but Commander supports an unlimited number of zones,
including chained zones. For example, if a third zone called Zone C is only accessible from Zone B via
GatewayAgent3 (in Zone B) and GatewayAgent4 (in Zone C), the server could issue a request to
GatewayAgent1, which forwards the request to GatewayAgent2, which forwards it to GatewayAgent3, which
forwards it to GatewayAgent4.
Also, for resiliency, Commander supports having multiple gateway agents between two zones. If one gateway
agent goes down, the system will detect the failure and route all requests through the other gateway agent.

69

ElectricCommander

Setting Up Workspaces
ElectricCommander provides each job step with an area on the disk it can use for "working files" and results.
This disk area is called a job workspace.
A job step can create whatever files it needs within its workspace, and Commander automatically places files in
the workspace, such as step logs. Normally, a single workspace is shared by all steps in a job, but it is possible
for different steps within a job to use different workspaces. The location of the job step workspace is displayed
on the Job Details page for the job under "Details" for the step.

To create a new workspace


Commander can handle any number of workspaces.
l

To define a workspace from the web interface, click the Cloud > Workspaces tabs.

On the Workspaces page, click the Create Workspace link at the top right-side of the table and the New
Workspace web page is displayed.

Click the Help link in the top-right corner of the web page for assistance with filling in the fields to create a
workspace.
To see the Workspaces Help topic now, click Workspace - create new or edit existing workspace.
After you create a workspace specification, you will see it listed on the Workspaces page.

70

Setting Up Email Configurations

Setting Up Email Configurations


If you do not create an Email Configuration, you cannot send Email Notifications to individuals or groups.
If you have multiple users or groups in remote locations who use a different mail server, you will want to create
additional Email Configurations to accommodate those locations if they need to receive Commander
notifications.

To create an email configuration


To create an Email Configuration, click on the Administration > Email Configurations tabs, then click the Add
Configuration link to see the New Email Configuration page. Click the Help link in the upper-right corner of the
page to see descriptions and other information to assist with filling-in the fields.
To see the Email Configurations Help topic now, click Email Configuration - create new or edit existing email
configuration.
After creating an Email Configuration, you will see it listed in the table on the Email Configurations web page.

71

ElectricCommander

Setting Up a Source Control Configuration


You must configure your source control system to communicate with the ElectricCommander server if you plan
to takes advantage of the Commander Continuous Integration Dashboard and associated functionality and
Preflight functionalityboth of these features are designed to work with a number of source control (SCM)
systems.
l

Continuous Integration Dashboard - use this feature to create continuous integration schedules for your
build environment. The Continuous Integration Manager is the front-end user interface for the
ElectricSentry Continuous Integration engine.

Preflight - use this feature to build and test developer code before it is committed to the code base for
your product.

Commander installs (bundles) and supports numerous source control types. After creating a source control
configuration, your entry will appear in the table on the Source Control Configurations web pageto see this
web page, select the Administration > Source Control tabs.
Note: If the SCM you prefer is not listed here, see the Plugin Manager page (Administration > Plugins) for a list
of all currently available SCM plugin integrations available for Commander. To configure a different SCM, see
the help topic associated with that plugin.
Select one of the following links to go to the source control configuration page to configure your SCM system:
AccuRev
ClearCase
File
Git
Perforce
Property
Subversion

The Continuous Integration Dashboard has its own help topic. For more information on ElectricSentry or
Preflights builds, see their respective help topics: ElectricSentry , Preflight Builds.

72

Setting Up Directory Providers

Setting Up Directory Providers


ElectricCommander uses account information from multiple sources. In most cases, the primary account
information source is an external LDAP or Active Directory repository: both user and group information is
retrieved from the repository. Local users and groups can be defined within Commander.

To specify a directory provider


ElectricCommander includes a web page to facilitate adding your existing LDAP or Active Directory users and
groups to Commander.
l

To access the Directory Providers web page, select the Administration > Directory Providers tabs.

Click the Add Active Directory Provider or the Add LDAP Provider link to add a new provider.

Depending on which Add... Provider link you choose, you will see either the New Active Directory Provider or
the New LDAP Provider web page. From either page, click the Help link in the upper-right corner of the page.
The Help topic describes each field on either web page so you can easily enter information in the forms to have
Commander use your existing user or group account information.
To see the Directory Provider Help topic now, click Directory Providers - create new or edit existing directory
providers.
After adding a provider, you will see it listed in the table on the Directory Providers web page.

Enable/Disable Local Commander Users


Two server settings properties are supplied for local Commander users (both are "on" by default):
l

enableAdminUser - if set to '0', attempts to log in as the 'admin' user are denied as if the user did not
exist

enableLocalUsers - if set to '0', attempts by a non-admin local user to log in are denied as if the user
did not exist

These settings are stored in properties in the '/server/settings' property sheet and can be set from ectool
by calling:
ectool setProperty /server/settings/enableAdminUser 0
Or, these settings can be set from the Commander web interface:
l

Select the Administration > Server tabs.

At the top of the page, select the Settings link.

Note: Disabling these properties takes effect only for new sessions. Existing sessions continue to function "asis" until the user logs out and attempts to log in again.

wrapper.conf Properties
If you need to edit the wrapper.conf file, see http://wrapper.tanukisoftware.com/doc/english/properties.html for
complete information about property formats.

73

ElectricCommander

The Home Page


Job Configurations
Shortcuts
Jobs Quick View
Reports

Overview
This page provides a convenient console for running jobs and viewing results.
l

This web page is your Commander Dashboard for tracking project health.

You can customize the page to display only the jobs that interest you and to provide one-click access to
the jobs you run frequently. Each of the Home page sections can be customized.

The Reports section allows you to see thumbnail report images that are updated each time the report is
generated.

This page provides shortcuts for quick access to pages you use most frequently in ElectricCommander
or anywhere on the web.

IMPORTANT: If you are using or plan to use the EC-Homepage plugin to share your Home page sections,
you will not see some links normally available to you. For example, if a particular Jobs Quick View category
is shared, you cannot Delete or Modify that category. You can perform these functions only if the category
belongs to you alone.
For information on sharing your Home page configuration, see the "Home page configurations" section in
the "Customizing the Commander UI" help topic.

Job Configurations
Procedures in ElectricCommander can contain complex sets of parameters making it difficult to remember the
correct parameters for a particular situation and tedious to re-enter those parameters every time the procedure
is invoked. Job Configurations provide a one-click solution to this problem. When you create a job configuration,
you enter all the information needed to run a procedure, including parameters and/or a credential. All job
configurations are displayed here on the Home page. Invoke a particular configuration by clicking its name in
the Job Configurations section.

Create Job Configurations three ways


l

On the Home page, create a job configuration from "scratch" by clicking the Create link in the Job
Configurations section.
o In the Create Configuration pop-up menu, select the project and procedure you want to use for

creating this configuration.

74

The Home Page

From the Job Details page for a previously invoked job, click the Save Configuration link at the top of
the page.
Your saved job configuration is displayed on your Home page.

From the Edit Schedule page, click the Save Configuration link at the top of the page.
Your saved configuration is displayed on your Home page.

Shortcuts
Use shortcuts to save frequently visited Commander web pages, so those pages are immediately accessible.
You can create a shortcut to any page on the web also.

Create Shortcuts two ways


l

Mouse-over the "star" icon at the top of any ElectricCommander page and click "Add current page" to
add that page to the shortcut list. Mouse-over the star icon again and click "Remove current page" to
remove the shortcut for that page. The star icon is yellow for pages saved as a shortcut and gray for
those pages not saved as a shortcut.

Click the Create link in the Shortcut section and provide a name and URL to create a shortcut.

To modify or update a shortcut, click the Edit link adjacent to the shortcut you want to change.
Shortcuts can be accessed conveniently from any ElectricCommander web page. Mousing-over the star
icon displays a list of shortcuts saved by the current user. Click on a shortcut name to view the page.
Note: The Shortcut section may contain static entries that cannot be deleted. And if you "share" your Home
page, the Edit link will not be available for shared items.

Jobs Quick View


Perhaps only a few jobs on this server are of interest to you. For example, you may care about jobs you launch
manually and official builds for the products you work on, but you may not care about production builds for other
products or personal jobs for other users.
The Jobs Quick View allows you to define job categories that are interesting to you.
The Home page displays the most recent jobs in each category, and you can easily click-through to get more
details about any of those jobs. For example, clicking on a job name takes you to that job's Job Details page.

Create a job category


l

Click the Add Category link in the Jobs Quick View section.
After creating a category, results are displayed on the Home page. Clicking the Details link displays a
summary to the right of the category. In addition to job status and other diagnostic information, the
summary displays running steps and failed steps (containing errors and warnings).

Click the Modify link to edit the Jobs Quick View category or the Delete link to remove that job from the
Jobs Quick View category.

Click on the Details link to see job summary informationthe summary remains visible, regardless of
mouse location, until you click somewhere else on the page.

Note: If you "share" your Home page, the Modify and Delete links will not be available for shared items.

75

ElectricCommander

Reports
You can configure reports you would like to see on a regular basis and display a "thumbnail" report graphic in
this section.
l

Click the Add Report link to go to the New Reports page.


After filling-in the information on the New Reports page, you will see a thumbnail view of your report
(after it runs) on your Home page.
Note: If the drop-down menu on this page is empty, click the Help link on the New Report page for more
information.

Click the Collapse/Expand (+/-) box to see the full thumbnail report or just the report title.

Click the Rename link if you need to rename your report.

Click the Remove link if you need to remove this report from your Home page.

Note: If you "share" your Home page, the Rename and Remove links will not be available for shared items.

76

Using ElectricCommander in Your Environment

Using ElectricCommander in Your Environment


This topic addresses some common issues you may encounter as you start using ElectricCommander and
offers some tips about managing your Commander projects.
What's in a step?
Where's the script for the step?
Environment variables
When do you use subprocedures?
How do you evolve procedures?
Porting existing scripts
Commander project version control

What's in a step?
One of the first questions you may ask when you start to implement your build and test processes on
Commander is how to divide processes into individual steps: "Should I use only a few steps, each of which does
a lot, or a large number of fine-grain steps?" Here are some factors to help you decide how many steps to use:
l

Reporting - If you would like a separate report of success/failure for two activities, put those activities in
separate steps. If you are happy to have a single report for both activities, a single step may make sense.
For example, compilation and test phases should probably be in different steps because errors in the
two phases will probably be handled differently. Unit tests for product components managed by different
groups may make sense in separate steps; each group can watch for errors in its step.

Parallelism - If you want to use Commander to run two activities in parallel, put them in separate steps. If
these activities are in the same step, Commander cannot run them in parallel.
Commander parallelism works best at a coarse grain, such as running different sets of unit tests in
parallel or compiling for different platforms. Electric Cloud does not recommend trying to do fine-grain
parallelism with Commander, such as compiling every individual source file in a separate step this is
likely to be complicated and brittle, resulting in an enormous number of job steps, which will make it
difficult to view results. If you would like to use fine-grain parallelism for compilation, Electric Cloud
recommends using our ElectricAccelerator product. In this case, you would make your compilation steps
large, with as much work in each makefile as possible because ElectricAccelerator automatically
subdivides the work and runs as many sub-steps as possible in parallel. The more work in a makefile,
the more efficient the process becomes.

Resources - If two different activities need to run on different resources, they need to be in different
steps. A single step runs entirely on a single resource.

77

ElectricCommander

Conditional steps - If you want to skip portions of your process during some jobs, but execute them
during others, it probably makes sense to put those activities in separate steps and use the Commander
"Run condition" mechanism to decide whether they run during each particular job. However, if you are
invoking programs like make that already allow you to choose which actions to perform, it may make
more sense to have a single large step and handle conditional behavior with those programs, rather
than with Commander. For example, when running make, you can specify the targets to be built.

Setup - You might want to have a single step at the beginning of a procedure that processes the
procedure's parameters and sets up the environment for the rest of the procedure. The setup step will
create a snapshot of your source code or set up a ClearCase view also. After setup, the remaining steps
should be easier to write because they just use information created during the setup step.

Where's the script for a step?


Typically, each step executes a script of some type, which is processed by a command language such as cmd
on Windows, a shell on UNIX, or Perl.

Two ways to handle script execution


l

The first approach - Enter the script directly into the command field for the step. You can specify the
language interpreter as the shell for the step.

The second approach - Store the script in a file that is part of the source code for your project, then
specify a simple command for the step that invokes the command language to process the script file.

Electric Cloud recommends using the second approach in most cases. The main advantage of this approach is
that it makes your Commander procedures more robust. For example, suppose the script needs to change as
your product evolves. If you have kept the script outside Commander with the source code for the product, each
product version can have its own copy of the script. When you extract the source code for the product at the
beginning of a job, you also extract the scripts for its steps. You can change a step's script without worrying
about its impact on other versions of the product.
However, if the script for a step is stored in the step, it is more difficult to evolve the script with new product
versions. You probably still need to build older product versions, so you will worry whether the new script for the
step will work with older product versions. If the script does not work, perhaps you can modify the step's script to
test the version being built and take different actions for each versionthis process becomes increasingly more
complex as the number of versions increases. Or, you can make a separate copy of the build procedure for
each product version (more on this below), but this process also gets complicated as you acquire more and
more procedure versions. We find it is easier to store scripts for steps with the product code, so script changes
are handled in the same way as changes to the product.

Two cases where it makes sense to store the script for a step in the
ElectricCommander step
l

78

The first case is for the first step of a job.


At this point you have not extracted the source code for the product, so you do not yet have access to
any scripts stored with the source code.

Using ElectricCommander in Your Environment

The second case is for steps with one or two commands only, or steps already specified primarily by
information stored with your source code.
For example, if a step is running a make or ant command, step behavior is already specified almost
entirely by a makefile or a build.xml file for Ant. In this case, the step's script invokes a single, relatively
simple command; no need to store this in a file. If you subsequently find that the script for a step is
changing frequently, consider moving it out of Commander and into a file stored with your source code.

The object is to make your Commander procedures as reusable as possible, so no change is needed with
every small change to your product. Even better, organize your Commander procedures so a single procedure
can be used for multiple products. To do this, store product-or version-specific information with the product, not
with Commander.

Environment variables
Your build and test scripts probably depend on certain environment variables having certain values. In your
existing system, you probably set those values at the beginning of your script. However, in Commander you
need to set those values in each step that depends on them. The easiest way to set values is to create a short
command file during the first step of the job and save it in the top-level directory of the job workspace. The
command file should contain a sequence of commands to set all environment variables required by the job.
Then, in each subsequent step, invoke that command file at the beginning of the step to set environment
variables for that step. This approach simplifies management of your environment variables: if you need to
change a variable, you change only the setup step at the beginning of the job, and the value is reflected in all of
the following steps automatically.

When do you use subprocedures?


In Commander, the action for a step can invoke another procedure, passing parameters. This is a powerful tool
for structuring your processes. Subprocedures tend to be used in two ways: for encapsulating reusable
processes and for managing concurrency.
l

encapsulating reusable processes, is the preferred use. If you need to perform certain activities
repeatedly in different places, you can use a subprocedure for them. For example, when we build and
test the Commander product, we do it on multiple platforms, but the mechanism is virtually the same on
all platforms. We implement the basic build and test mechanism for one platform in a subprocedure
named BuildAndTest. In our main procedure for production builds, we invoke BuildAndTest multiple
times, once for each of the platforms. If the mechanism changes, we only need to change it once in
BuildAndTest to fix all six platforms.

managing concurrency - suppose you have three steps A1, A2, and A3, that must run sequentially, and
two other steps B1 and B2 that must also run sequentially, but the two groups can run in parallel. The
way to implement this is to put A1, A2, and A3 in one subprocedure named "A", and B1 and B2 in
another subprocedure named "B". Now you can create a top-level procedure with two steps: one
invoking A and the other invoking B, and mark those steps for parallel execution. As a result, A and B will
run in parallel but the steps inside each subprocedure will run serially.
If you placed all five steps inside the top-level procedure, there would be no way to achieve this effect.

How do you evolve procedures?


After you start using Commander for managing your build and test processes, it will not be long before you
encounter the following situation:

79

ElectricCommander

You have a set of Commander procedures that work fine on all existing versions of the product, but you are
about to change the product in a way that affects Commander procedures. For example, you might be adding a
new component, or perhaps you are going to change the way the product is installed for testing, or perhaps you
have restructured the product to allow more steps to run concurrently. As a result, you need to change
Commander procedures for the current version. At the same time, you need older product versions to continue
building as well.
In most cases, the easiest way to handle these situations is to leave the current Commander procedures alone
and keep using them for your older product version. This ensures you will not "break" older versions. Make
copies of the procedures that need to change, then modify the copies and use them for your new software
version.
You will have one version of procedures for each significant version of the product. For example, at Electric
Cloud, we incorporate the version number into the procedure names: "Master-1.0" is the version of the Master
procedure used with the 1.0 release, "Master-1.1" is used for 1.1, and "Master" with no version number is used
for our current development.
Another approach would be to make a copy of the entire project for each release. This method may be easier if
other information in the project, such as property values, needs to evolve also.
The "copying" approach gets more and more complicated as you add more and more versions of the procedure.
To minimize this complexity, try to structure your procedures so they do not have to change frequently. Some
techniques you can use:
l

Use parameters for things that do change frequently, such as the branch of software to build.

Where possible, store scripts and other information [used by the procedure] as part of the source code
for the project as described above, so this information is versioned automatically, along with your source
code.

Porting existing scripts


You probably already have scripts you have been using to build and test software, before switching to
ElectricCommander.
Over time, you will probably want to do quite a bit of restructuring to take full advantage of Commander.
However, you probably do not need to do major restructuring to get started with Commander. Here are some
steps you might take to "get up and running" with Commander as quickly as possible and gradually convert to
make the best use of the system.
To begin, see if you can take your existing script and run it monolithically as a single step in a procedure
under Commander. This will get you running and start providing some Commander benefits for resource
management, error analysis, and reporting.
Next, start dividing your previous script into separate steps for Commander. Begin with the steps easiest to
separate from the rest of the script, such as the commands to compile your software. One of the challenges
you face is how to pass data from one step to another. In a monolithic script, you can keep the data in
variables that persist throughout the job. As you divide the script into steps, you need to figure out which
variables are used only in a single step and which variables pass from step to step. For variables that pass
between steps, use Commander properties to store their values. In many cases you can compute shared

80

Using ElectricCommander in Your Environment

data values in a single step at the beginning of the job, store their values in properties on the job, then
access those values read-only in later job steps.
After dividing the steps, you can do finer-grain reporting. Start using the postp postprocessor to scan your
log files and generate statistics and diagnostics. Over time you will probably discover you have a few error
and warning messages peculiar to your site, and are not captured by postp's patterns. Learn how to extend
postp with additional patterns to capture all the information that matters to you.
Now that reporting statistics are being recorded, you may wish to develop your own reports to summarize
those statistics. You can easily use ectool to read statistics from the properties where they are stored.
Something else you can do after steps are divided: start tuning the performance of your procedures. For
example, you can start marking steps to run in parallel, and you can choose resources on a step-by-step
basis to finish your jobs faster and share resources more effectively.

Commander project version control


Electric Cloud recommends exporting your Commander project data at regular intervals and saving it in the
same configuration management system you use for your source code (use the "export" ectool command to
generate an XML file representing the contents of a project or procedure). This process allows you to track
project changes and also allows you to "look back" at older versions if that should become desirable. Also, you
should snapshot a version of Commander project data at the time of each major software release, so you can
revert to the exact Commander configuration used to generate that release if necessary.

81

ElectricCommander

Using ectool and the Commander API


ElectricCommander features can be accessed in two ways:
l

The most common access is through the web interface, which displays screens to create projects,
procedures, and steps; launch jobs; and manage all administration tasks.

The second access method is the Commander API. The API can be used from a command-line,
including a shell script, or a batch file. Any operation you can perform on the web interface, you can
perform using the API because they both rely on the same interface to the ElectricCommander server.
The Commander API supports ectool and ec-perl (or Perl) commands:
o ectool is a command-line tool developed to script ElectricCommander operations.
o ec-perl is delivered as a Perl package during ElectricCommander installation, or you can use any

Perl of your choice.


Because ectool and ec-perl can work together, this help topic describes Perl and ectool usage and differences.
l

Using ectool

Using ec-perl

Common global options

The Batch API

Installing Commander Perl modules into your Perl distribution

Installing Perl modules into the Commander Perl distribution

Using ectool
ectool is a command-line application that provides operational control over the ElectricCommander system.
ectool supports a large collection of commands, each of which translates to a message sent to the
ElectricCommander server.
For example, ectool getProjects returns information about all projects defined in the server.
l

ectool --help displays a summary of all commands and other command-line options.

For information about a particular command, use --help followed by the command name. For example,
ectool --help modifyStep returns information about the modifyStep command.

Logging in
If you use ectool outside of a job, you must invoke the ectool login command to login to the server. After logging
in, ectool saves information about the login session for use in future ectool invocations. If you run ectool as part
of a ElectricCommander job, you do not need to log inectool uses the login session (and credentials) for that
job.

82

Using ectool and the Commander API

To log in to a specific server, see the example below, which includes the server name, user name, and
password.
Login example:
ectool --server bldg1server login "Ellen Ernst" "ee123"
General syntax for ectool command usage:
ectool [global argument] <command> <positional arguments> [named arguments]

Global Arguments (optional)


See the Common global options section for more information.

Passing Lists as Arguments


Some API commands include arguments that expect a list of values. Two list forms: value lists and name/value
pairs. The syntax to specify a list depends on whether you are using ectool or ec-perl.

For ectool
l

value list - each value is specified as a separate argument on the command line
Example:
ectool addUsersToGroup group1 --userNames user1 user2 user3

name/value pairs - each pair is specified as a separate argument in the form name=value
Example:
ectool runProcedure proj1 --procedureName proc1 --actualParameter parm1=value1 p
arm2=value2

For ec-perl
l

value list - the argument value is a reference to an array of values


Example:
$cmdr->addUsersToGroup({ groupName => group1,
userName => ['user1', 'user2']});

name/value pairs - the argument value is a reference to an array of hash references. Each hash
contains a pair of entries, one for the name and one for the value. The hash keys depend on the specific
API.
Example:
$cmdr->runProcedure({ projectName
=> 'proj1',
procedureName => 'proc1',
actualParameter => [{ actualParameterName
value
{ actualParameterName
value

=>
=>
=>
=>

'parm1',
'value1'},
'parm2',
'value2'}]});

Using Perl
When ElectricCommander is installedServer, Agent, or Tools (using the express or advanced installation
type)a copy of Perl is installed. This Perl is pre-configured with all the packages you need to run the

83

ElectricCommander

Commander Perl API. Commander does not, however, automatically add this version of Perl to your path
because:
l

We did not want the ElectricCommander installation to interfere with existing scripts you may run, which
are dependent on finding another copy of Perl you already use.

Some special environment variables need to be set before calling Perl.

Both of these issues are addressed with a small wrapper program called ec-perl. The wrapper is installed as
part of ElectricCommander, and it is in a directory that is added to your path. When the ec-perl wrapper runs, it
sets up the environment, finds, and calls the Commander copy of Perl, passing all of its parameters to Perl.
To run ec-perl from a command line (or in a ElectricCommander step) simply enter:
ec-perl yourPerlOptions yourPerlScript.pl
The Perl script can include API calls to ElectricCommander with no other special handling required.
Another way to write Perl scripts: For an ElectricCommander step, enter the Perl script directly into the
"Command" field, and set the "Shell" field to ec-perl. The Commander-installed Perl is used to process the
Perl script.
You can develop Perl scripts to access the Perl API directly. Because ectool uses the Perl API to execute its
commands, any ectool command you can execute can be executed using the Perl API. If you are writing (or
currently using) a script that makes tens or hundreds of calls, the Perl API provides a significant performance
improvement over ectool.
The Perl API is delivered as a collection of Perl packages pre-installed in a Perl 5.8 distribution. The main API
package is called ElectricCommander.

Perl API structure


The Perl API has the same four elements as ectool, but the way these elements are specified is quite different.
Specifying global options
To use the Commander Perl API, you must first create an object. Global arguments are specified at the time the
object is created. These arguments are passed as members of an anonymous hash reference, as shown in the
following example:
use ElectricCommander;
$cmdr = ElectricCommander->new({
server
=> "vm-xpsp2",
port
=>
"8000",
securePort => "8443",
debug
=> "1",
});
In the example above, port options are not really necessary because they specify default values. When you
want to specify the server name only, you can use the shorthand form:
use ElectricCommander;
$cmdr = ElectricCommander->new("vm-xpsp2");

84

Using ectool and the Commander API

An even simpler form can be used if you call the Perl API from a script running as part of an ElectricCommander
job step. In this case, the Commander package sets the server name based on the environment variable,
COMMANDER_SERVER, set by the Commander agent.
use ElectricCommander;
$cmdr = ElectricCommander->new();
To see a complete list of global commands you can use with Perl, click here.
Note: If your script uses International characters (non-ascii), add the following block to the top of your ec-perl
command block:
use utf8;
ElectricCommander::initEncodings();
Specifying subcommands
For each subcommand, there is a corresponding Commander object function.
For example, to retrieve a list of jobs, use
$cmdr->getJobs();
Specifying arguments
Most subcommands expect one or more arguments. Arguments are specified as key value pairs in a hash ref
passed as the final argument to the subcommand. Additionally, as a convenience, some arguments may be
specified as positional arguments prior to the options hash ref.
For example, setProperty has two positional arguments, propertyName and value, and an optional jobId
argument that can be specified in either of the following forms:
$cmdr->setProperty("/projects/test/buildNumber", "22",
{jobId => $jobId});
or
$cmdr->setProperty({
propertyName => "/projects/test/buildNumber",
value => "22",
jobId => $jobId });
Handling return values
Every function to the object returns an object of type XML::XPath. This is an object that returns a parsed
representation of the ElectricCommanderreturned XML block. See documentation on CPAN for more
information.
$xPath = $cmdr->setProperty("filename", "temp.xml");
print "Return data from Commander:\n".
$xPath->findnodes_as_string ("/") . "\n";
Error handling
If a function call to the ElectricCommander object encounters an error, by default, it "dies" inside Perl and prints
an error message. If you want to handle errors yourself and continue processing, you must set a flag to disable
internal error handling and handle the error in your code.
For example:

85

ElectricCommander

$cmdr->abortOnError(0);
$xPath = $cmdr->getResource("NonExistent Resource");
if ($xPath) {
my $code = $xPath->findvalue('//code')->value();
if ($code ne "") {
my $mesg = $xPath->findvalue('//message');
print "Returned code is '$code'\n$mesg\n";
exit 1;
}
}
An alternative to using the abortOnError flag:
eval {$cmdr->get...};
if ($@) {
print "bad stuff: $@";
exit 1;
}
Specifying a named object
Any API argument that refers to a named object (for example, projectName, procedureName) performs
property reference expansion before looking in the database for the object. This process allows constructs like
the following to work without making two separate server requests:
$cmdr->getProject ('$[/server/defaultProject]')
Property reference expansion for names occurs in the global context, so context-relative shortcuts like
"myProject" are not available.

Common Global Options


Global arguments can be used alone or in conjunction with other commands. These arguments are used to
control communication with the server and can be used with the ectool or ec-perl API.
Global Arguments

Description

--help

Display an online version of ectool commands with a short description.


Displays command information if followed by a command name.

--version

86

Display the ectool version number.

Using ectool and the Commander API

Global Arguments

Description

--server <hostname>

ElectricCommander server address. Defaults to the COMMANDER_


SERVER environment variable. If this variable does not exist, the default is
to the last server contacted through the API. However, if there is no record
for which server was contacted, the default is to localhost.
Note: If you are using multiple servers, Electric Cloud recommends using
the server option to ensure the correct server is specified for your task. For
example, if you are using the import API, the server option may be
particularly important.
Do not use in a step context: Electric Cloud recommends that steps
running ectool or Perl scripts should never provide the server option if the
intention is to communicate with the server that launched the step. If the
intention is to communicate with a different server, this agent must be a
registered, enabled resource in the second server. Thus, that server will
ping the agent, and the agent will learn how to communicate with that
server.
In a step context, ectool and the Perl API proxy server requests through the
step's agent. If the agent does not recognize the provided server-name, it
rejects the request. ectool / Perl API retry the operation because at some
point the server should ping the agent, and then the agent will have learned
how to communicate with the server.
Generally, the issue is that the server publicizes its name as a fully-qualified
domain name and ectool / Perl API issue requests with a simple-name for
the server. This can happen if the step explicitly states which server it is
connecting to. Fix your steps that invoke ectool so they no longer include the
server-name, and ectool will default to the server-name that the server
provided.

--port <port>

HTTP listener port on the ElectricCommander server. Defaults to port 8000.

--securePort
<secureport>

HTTPS listener port on the ElectricCommander server. Defaults to port 8443.

--secure <0|1>

Use HTTPS to communicate with the Commander server.


Note:Certain requests (for example, login, createUser, and
modifyUser) automatically use HTTPS because passwords are being sent,
which means it is not necessary to specify secure for those APIs. Defaults to
1.

87

ElectricCommander

Global Arguments

Description

--timeout <s>

An API call waits for a response from the server for a specified amount of
time. Timeout for server communication defaults to 180 seconds (3 minutes)
if no other time is specified. After the timeout, the API call stops waiting for a
response, but the server continues to process the command.

--retryTimeout <s>

This is a separate timer, independent of the retry flag, and used to control
Commanders automatic error recovery. When the API is unable to contact
the Commander server, it will keep trying to contact the server for this length
of time. When the API is called from inside a step, it defaults to 24 hours.

--retry <0|1>

Retry the request if it times out based on the "timeout" value. Default is "0"
and should rarely be changed.

--user <username>

Use the session associated with the user. Defaults to the user who last
logged in.

--service <spn>

Specify the service principal name to use for Kerberos. Defaults to


HTTP@host.domain.

--setDefault <0|1>

Use the current session as the default for subsequent invocations. Defaults
to 1.

encoding
<charEncoding>

Use the specified encoding for input/output. For example, for

--dryrun

Displays session information and the request that would be sent, without

charEncoding, enter UTF-8, cp 437, and so on. Default is autodetected.

communicating with the server. If a subcommand is specified, the server


request that would be sent is displayed. This option can also be used to
change the default user/server value by specifying the --user or --server
options.
--silent

Suppresses printing the result.


For example:
ectool --silent createResource foo will not print the resource
name, agent state, any modify information, create time, owner, port, or any
other information otherwise displayed when you create a resource.

88

Using ectool and the Commander API

Global Arguments

Description

--valueOf

This option can return the value of a unique element. Because many ectool
APIs return an XML result, it is inconvenient to use ectool in shell scripts and
makefiles where you might want a piece of the ectool result to incorporate
into some other logic. Using the --valueOf <path> option evaluates the
XML result and emits the value of that node to satisfy such use cases.
For example:
$ ectool --valueOf '//version' getServerStatus
returns only "4.1.0.48418".

--format <format>

Specifies the response format. Must be one of 'xml' or 'json'. Defaults to 'xml'.
For example, you might specify:
ectool --format json setProperty summary hello

--ignoreEnvironment

Force ectool to ignore COMMANDER_ENV variables.

The Batch API


The Perl API supports a batch operation mode that allows you to send multiple API requests in a single
"envelope", which has several advantages over standard, individual API calls in some situations. For example,
you could use the batch API when you need to set 10 or even 100 property values.
The batch API reduces "round-trip" transmissions. All setProperty requests can be sent in a single envelope.
You can choose an option that changes all properties in a single database transaction in the server. This means
changes are made using an "all or none" approach. If one change fails, they all fail, which allows you to keep
your data in a consistent state. When you make a large number of requests in one envelope, the single
database transaction option provides much better performance.

Using the Batch API


To use the batch API, first create a object as you would for a standard API. From your newly created object,
create a batch object using the newBatch method. The newBatch method takes a single argument, which is
the "request processor mode". This argument tells the server how to process multiple requests. There are three
"request processor modes":
1. serial - each request in the envelope is processed serially, each in its own transaction.
2. parallel - each request in the envelope is processed in parallel, each in its own transaction.
3. single - each request in the envelope is processed serially, all in the same transaction.
Specifying serial, parallel, or single is optional. If you do not specify an option, the server determines the best
mode to use, based on the requests in the envelope.
Example - creating a batch object:
use ElectricCommander;
my $cmdr = ElectricCommander;

89

ElectricCommander

# Create the batch API object


my $batch = $cmdr->newBatch("parallel");
The batch object supports all the same calls as the standard API. The result of each call is a numeric
requestId that can be used to locate a response from an individual request within the batch.
Example - creating multiple requests in a batch:
# Create multiple requests
my @reqIds = (
$batch->setProperty("/myJob/p1", 99),
$batch->incrementProperty("/myJob/p2")
);
After the batch is created, submit it to the server for processing. The return from the submit() call is an XPath
object that represents an XML document containing the responses for all of the API requests.
Example - submitting the batch:
# Submit all the requests in a single envelope
$batch->submit();
Sample response from this example:
<responses xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xsi:
version="2.1" dispatchId=1680
<response requestId="1">
<property>
<propertyId>199827</propertyId>
<propertyName>p1</propertyName>
<createTime>2010-07-21T16:41:20.003Z</createTime>
<expandable>1</expandable>
<lastModifiedBy>project: EA Articles</lastModifiedBy>
<modifyTime>2010-07-21T16:41:20.003Z</modifyTime>
<owner>project: EA Articles</owner>
<value>99</value>
</property>
</response>
<response requestId="2">
<property>
<propertyId>199828</propertyId>
<propertyName>p2</propertyName>
<createTime>2010-07-21T16:41:20.019Z</createTime>
<expandable>1</expandable>
<lastModifiedBy>project: EA Articles</lastModifiedBy>
<modifyTime>2010-07-21T16:41:20.019Z</modifyTime>
<owner>project: EA Articles</owner>
<value>1</value>
</property>
</response>
</responses>
To extract information from the response to a request, use standard XPath syntax, and enter the requestId
returned by that specific API call to either the find or findvalue functions on the batch object.
Example - extracting response information:

90

Using ectool and the Commander API

# Extract the value from the "increment" request


my $value = $batch->findvalue($reqIds[0], 'property/value');
print "New value is $value\n";
Single-transaction batch processing can continue after errors if you enter an ignoreErrors attribute in the
request and/or requests elements. The ignoreErrors value is evaluated as a regular expression against
any error codes from the batch. If the expression matches, an error will not cause the batch to fail.
There are two ways to specify ignoreErrors when issuing a single-transaction batch call:
1. Specify the ignoreErrors attribute when creating the batch object. In this case, the attribute applies to
all requests in the batch:
my $batch = $N->newBatch('single', 'DuplicateResourceName');
2. Specify the ignoreErrors attribute as an argument to an individual request. In this case, the attribute
applies only to that request and will override any global value specified:
my $req2 = $batch->createResource($resource, {ignoreErrors =>
'DuplicateResourceName'});

Installing Commander Perl modules into Your Perl


Distribution
You may want to use your existing Perl distribution. If so, Commander uses a CPAN style module, located in
<installdir>/src, that can be installed with the following commands:
tar xzvf ElectricCommander-<your version>.tar.gz
cd ElectricCommander-<your version>
perl Makefile.PL
make install;# Use nmake on Windows
These commands install the Commander Perl and all of its submodules. If some prerequisite modules are
missing, the Makefile.PL script will indicate which modules are needed.

Installing Perl Modules into the Commander Perl Distribution


You may want expand the Commander Perl distribution by adding Perl modules from CPAN or third party
vendors.
Install Perl modules using CPAN installer. The installer comes with the Commander Perl distribution in
<commanderDir>/perl/bin.

For Linux
From the command line use: <commanderDir>/perl/bin/perl -MCPAN -e 'install <module>'

For Windows
Compatibility with Commander is important. Commander 4.1 (and above) versions use Perl 5.8 for ec-perl.
If the Perl package is not Perl-only and requires compiling (for example, for C code):
Use Windows Visual Studio VC6 (the same version used by Commander).
Make sure that cl and nmake are both in your path. The Visual Studio install has a Command Prompt with
these executables already in the path.

91

ElectricCommander

Extra steps are needed for Windows because of a problem with Perl and CPAN if you are running from a
directory with spaces in the name. (By default, Commander has spaces in the installed directory.)
l

Use a network drive to eliminate references to spaces.


Use subst to mount the Perl directory under a different drive letter:
c:\> subst x: "c:\program files\electric cloud\electriccommander"
Start CPAN from the new location:
c:\> x:\perl\bin\perl -MCPAN -e shell
Configure CPAN to install into the new location:
cpan> o conf makepl_arg PREFIX=x:/perl
Install the module:
cpan> install <module>
Ending CPAN:
cpan> quit

Change the <commanderDir>\perl\lib\config.pm file to eliminate spaces in references to the


Commander path.
For example:
#archlibexp => 'C:\Program Files\Electric Cloud\ElectricCommander\perl\lib',
archlibexp => 'X:\perl\lib',
#privlibexp => 'C:\Program Files\Electric Cloud\ElectricCommander\perl\lib',
privlibexp => 'X:\perl\lib',
#scriptdir => 'C:\Program Files\Electric Cloud\ElectricCommander\perl\lib',
scriptdir => 'X:\perl\lib',
#sitearchexp => 'C:\Program Files\Electric Cloud\ElectricCommander\perl\site\li
b',
sitearchexp => 'X:\perl\lib',
#sitelibexp => 'C:\Program Files\Electric Cloud\ElectricCommander\perl\site\li
b',
sitelibexp => 'X:\perl\lib',

Temporarily add X:\perl\bin to your Windows path.

When Upgrading Commander


During a Commander upgrade, the installer makes every attempt to preserve Perl packages. However, future
Commander versions may contain an upgraded Perl version, which may then require a reinstall of any added
Perl packages.

92

API Commands - listed by group and in alphabetical order

API Commands - listed by group and in alphabetical


order
Use the help system's Search feature to quickly locate the API commands you need, or click one of the links
below to view the entire command list "by group" or all commands in alphabetical order. In both lists, each API
command is linked to its own table "section" containing descriptions, definitions, and examples, specific to that
API command.
API commands listed by group
Commands are grouped into common usage sections for your convenience.
This view is helpful if you want to see all available commands for a particular object.

API commands in alphabetical order


This section is one continuous list of API commands in alphabetical order.

API command tables


These sections contains expanded information for each API command, including descriptions, optional
arguments, and usage examples.
The tables in this section are alphabetized by API command within each group.
Note: The API tables display positional arguments for each command; however, you can use "value pairs"
to construct your command scripts if you prefer.
For more information, see the "Using ectool and the Commander API" help topic.

API commands listed by group


Click on a command to go to expanded information for that command, including its associated arguments
(required and other options), descriptions, usage examples, and related commands.

ACL Management (access control list)


Commands

Description

breakAclInheritance

Breaks ACL (access control list) inheritance at the given object.


Checks ACL (access control list) permission information

checkAccess

associated with an object (including inherited ACLs) for the


current user.

93

ElectricCommander

Commands

createAclEntry

deleteAclEntry

getAccess

Description
Creates an ACE (access control list entry) on an object for a given
principal.
Deletes an ACE on an object for a given principal.
Retrieves ACL information associated with an object, including
inherited ACLs.

getAclEntry

Retrieves an ACE on an object for a given principal.

modifyAclEntry

Modifies an ACE on an object for a given principal.

restoreAclInheritance

Restores ACL inheritance at the given object.

Artifact Management
Commands

Description
Adds an artifact version query to an existing artifact. Dependent

addDependentsToArtifactVersi
on

artifact versions are retrieved when the parent artifact version is


retrieved.
Deletes stale artifact versions from an artifact cache. A "stale

cleanupArtifactCache

artifact version" is one whose metadata was previously deleted


from the Commander server.
Deletes stale artifact versions from the repository backing-store. A

cleanupRepository

"stale artifact version" is one whose metadata was previously


deleted from the Commander server.

createArtifact

Creates a new artifact.

createRepository

Creates a repository for one or more artifacts.

deleteArtifact

Deletes an existing artifact element and all artifact versions.


Deletes artifact version metadata from the Commander database.

deleteArtifactVersion

(This API call does not delete or remove artifacts stored on the
repository machine.)

94

API Commands - listed by group and in alphabetical order

Commands

Description
Deletes artifact repository metadata from the Commander

deleteRepository

database. (This API call does not delete or remove artifacts stored
on the repository machine.)
This command returns the most current artifact version that
matches the filter criteria and its dependent artifact versions. This

findArtifactVersions

API implicitly searches for artifact versions in the "available" state,


and if run in a job step, registers the step as a retriever for the
returned artifact versions. Use the Perl API for the
findArtifactVersions command.

getArtifact

Retrieves an artifact by its name.

getArtifacts

Retrieves all artifacts in the system.

getArtifactVersion

Retrieves an artifact version by its name.

getArtifactVersions

Retrieves all artifact versions in the system, filtered by artifact


name, retriever job ID, and/or retriever job step ID.
Retrieves the manifest for a specified artifact version, which

getManifest

includes a list of files and directories in the artifact version, plus its
checksum file.

getRepositories

Retrieves all artifact repository objects known to the Commander


server.

getRepository

Retrieves an artifact repository by its name.

modifyArtifact

Modifies an existing artifact.

modifyArtifactVersion

Modifies an existing artifact version.

modifyRepository

Modifies an existing artifact repository.

moveRepository

Moves an artifact repository in front of another, specified repository


or to the end of the list.

publishArtifactVersion

Publishes an artifact version to an artifact repository.

removeDependentsFromArtifact
Version

Removes a list of dependent artifact versions from an existing


artifact version.

95

ElectricCommander

Commands

retrieveArtifactVersions

Description
Retrieves the most recent artifact version, including its
dependents, from an artifact repository.

Credential Management
Commands

Description

attachCredential

Attaches a credential to an object.

createCredential

Creates a new credential for a project.

deleteCredential

Deletes a credential.

detachCredential

Detaches a credential from an object.

getCredential

Finds a credential by name.

getCredentials

Retrieves all credentials in a project.

getFullCredential

modifyCredential

Finds a credential by name, including password, from within a


running step.
Modifies an existing credential.

Database Configuration
Commands

Description

getDatabaseConfiguration

Retrieves the current database configuration.


Sets the database configuration on the server. If the server is in

setDatabaseConfiguration

bootstrap mode, these changes take effect immediately and the


server attempts to start. If the server is running, these changes
have no effect until the server is restarted.

Directory Provider Management

96

API Commands - listed by group and in alphabetical order

Commands

Description

createDirectoryProvider

Creates a new LDAP directory provider.

deleteDirectoryProvider

Deletes an LDAP directory provider.

getDirectoryProvider

Retrieves an LDAP directory provider by name.

getDirectoryProviders

Retrieves all LDAP directory providers.

modifyDirectoryProvider

Modifies an existing LDAP directory provider.

moveDirectoryProvider

testDirectoryProvider

Moves an LDAP directory provider in front of another specified


provider or to the end of the list.
Tests an LDAP directory provider.

Email Configuration and Management


Commands

Description

createEmailConfig

Creates a new email configuration.

deleteEmailConfig

Deletes an email configuration.

getEmailConfig

Retrieves an email configuration by name.

getEmailConfigs

Retrieves all email configurations.

modifyEmailConfig

Modifies an existing email configuration.

Email Notifiers Management


Commands

createEmailNotifier

Description
Creates an email notifier on an object specified by an
emailNotifierSelector.

deleteEmailNotifier

Deletes an email notifier from a property sheet container.

97

ElectricCommander

Commands

Description

getEmailNotifier

Retrieves an email notifier from a property sheet container.

getEmailNotifiers

modifyEmailNotifier

Retrieves all email notifiers defined for the specified property sheet
container.
Modifies an email notifier in a property sheet container specified
by an emailNotifierSelector.
Facilitates sending an email from the command-line or a
Command Step without setting up an Email Notifier.

sendEmail

This API is more dynamic than an email notifier because you do


not need to setup some kind of a template beforehand.
This API also makes sending email attachments easier than using
a notifier template.

Gateway/Zone Management
Commands

Description

createGateway

Creates a new gateway.

deleteGateway

Deletes a gateway.

getGateway

Finds a gateway by name.

getGateways

Retrieves all gateways.

modifyGateway

Modifies an existing gateway.

createZone

Creates a new zone.

deleteZone

Deletes a zone.

getZone

Finds a zone by name.

getZones

Retrieves all zones.

modifyZone

Modifies an existing zone.

Job Management

98

API Commands - listed by group and in alphabetical order

Commands

Description

abortAllJobs

Aborts all running jobs.

abortJob

Aborts a running job.

abortJobStep

Aborts any type of stepcommand step or subprocedure step.

completeJob

Completes an externally managed job.

completeJobStep

Completes an externally managed job step.

createJob

Creates an externally managed job.

createJobStep

Creates a job step in an existing job.

deleteJob

Deletes a job from the ElectricCommander database.


Returns a list of job steps from a single job or from a single

findJobSteps

subprocedure job step.


This API is used by the Job Details web page in the Commander
UI.

getJobDetails

Retrieves complete information about a job, including details from


each job step.

getJobInfo

Retrieves all information about a job, except job step information.

getJobNotes

Retrieves the notes property sheet from a job.

getJobs

Retrieves summary information for a list of jobs.

getJobsForSchedule

Retrieves jobs started by a specific schedule.

getJobStatus

Retrieves the status of a job.

getJobStepDetails

Retrieves details for a job step.

getJobStepStatus

Retrieves the status of a job step.

modifyJob

Modifies the status of an externally managed job.

modifyJobStep

Modifies the status of an externally managed job step.

moveJobs

Moves jobs from one project to another.

99

ElectricCommander

Commands

runProcedure

setJobName

Description
Creates and starts a new job using a procedure directly or
specified indirectly through a schedule.
Sets the name of a running job.

Parameter Management
Commands

Description

attachParameter

Attaches a formal parameter to a step.


Creates a new actual parameter for a step that calls a nested
procedure.

createActualParameter

The parameter is passed to the nested procedure when the step


runs. At run time, the actual parameter name needs to match the
name of a formal parameter in the nested procedure.

createFormalParameter

Creates a new formal parameter for a procedure.

deleteActualParameter

Deletes an actual parameter.

deleteFormalParameter

Deletes a formal parameter.

detachParameter

Detaches a formal parameter from a step.

getActualParameter

Retrieves an actual parameter by its name.

getActualParameters

Retrieves all actual parameters from a job, job step, or step.

getFormalParameter

Retrieves a formal parameter by its name.

getFormalParameters

Retrieves all formal parameters from a procedure, schedule, or


step.
Modifies an existing actual parameter. An actual parameter is a

modifyActualParameter

name/value pair that is passed to a subprocedure. This command


supports renaming the actual parameter and setting its value.

modifyFormalParameter

100

Modifies an existing formal parameter.

API Commands - listed by group and in alphabetical order

Plugin Management
Commands

deletePlugin

Description
Deletes an existing plugin object without deleting the associated
project or files.

getPlugin

Retrieves an installed plugin.

getPlugins

Retrieves all installed plugins.

installPlugin

modifyPlugin

Installs a plugin from a JAR file. Extracts the JAR contents on the
server and creates a project and a plugin.
Modifies a plugin.
Sets the promoted flag on a plugin. Only one version of a plugin
can be promoted at a time, so setting the promoted flag to true on

promotePlugin

one version sets the flag to false on all other plugins with the
same key. The promoted version is the one resolved by an indirect
reference of the form $[/plugins/<key>] or a plugin name
argument without a specified version.

uninstallPlugin

Uninstalls a plugin, deleting the associated project and any


installed files.

Procedure Management
Commands

Description

createProcedure

Creates a new procedure for an existing project.

createStep

Creates a new procedure step.

deleteProcedure

Deletes a procedure, including all steps.

deleteStep

Deletes a step from a procedure.

getProcedure

Finds a procedure by its name.

getProcedures

Retrieves all procedures in a project.

101

ElectricCommander

Commands

Description

getStep

Retrieves a step from a procedure.

getSteps

Retrieves all steps in a procedure.

modifyProcedure

Modifies an existing procedure.

modifyStep

Modifies an existing step.

moveStep

Moves a step within a procedure.

Project Management
Commands

Description

createProject

Creates a new project.

deleteProject

Deletes a project, including all procedures, procedure steps, and


jobs.

getProject

Finds a project by its name.

getProjects

Retrieves all projects.

modifyProject

Modifies an existing project.

Property Management
Commands

createProperty

deleteProperty

102

Description
Creates a regular string or nested property sheet using a
combination of property path and context.
Deletes a property from a property sheet.

API Commands - listed by group and in alphabetical order

Commands

Description
Evaluates a script in a given context.This API is similar to
expandString except that it evaluates the value argument as a

evalScript

Javascript block, without performing any property substitution on


either the script or the result.
The string value of the final expression in the script is returned as
the value element of the response.

expandString

Expands property references in a string, in the current context.

getProperties

Retrieves all properties associated with an object.

getProperty

Retrieves the specified property value.


Atomically increments the specified property value by the

incrementProperty

incrementByamount. If the property does not exist, it will be


created with an initial value of the incrementBy amount.

modifyProperty

setProperty

Modifies a regular string or nested property sheet using a


combination of property path and context.
Sets the value for the specified property.

Resource Management
Commands

Description

addResourcesToPool

Adds resources to a specified resource pool.

createResource

Creates a new resource.

createResourcePool

Creates a pool container for resource.

deleteResource

Deletes a resource.

deleteResourcePool

Deletes a resource pool.

getResource

Retrieves a resource by its name.

getResources

Retrieves all resources.

103

ElectricCommander

Commands

Description

getResourcesInPool

Retrieves a list of resources in a pool.

getResourcePool

Retrieves a specified resource pool by name.

getResourcePools

Retrieves a list of resource pools.

getResourceUsage

Retrieves resource usage information.

modifyResource

Modifies an existing resource.

modifyResourcePool

Modifies an existing resource pool.

pingAllResources

Pings all resources.

pingResource

Pings one resources.

removeResourcesFromPool

Removes resources from a specified resource pool.

Schedule Management
Commands

Description

createSchedule

Creates a new schedule.

deleteSchedule

Deletes a schedule.

getSchedule

Retrieves a schedule by its name.

getSchedules

Retrieves all schedules.

modifySchedule

Modifies an existing schedule.

Server Management

104

Commands

Description

getVersions

Retrieves server version information.

API Commands - listed by group and in alphabetical order

Commands

Description

shutdownServer

Shuts down the ElectricCommander server.

importLicenseData

Imports one or more licenses.

getAdminLicense

Retrieves the admin license, which can be used when all


concurrent user licenses are in use.

getLicense

Retrieves information for one license.

getLicenses

Retrieves all license data.

getLicenseUsage

Retrieves the current license usage.

deleteLicense

Deletes a license.

getServerStatus

Returns the status of the server.

User/Group Management
Commands

Description
Logs into the server and saves the session ID for subsequent

login

ectool use.
The user name provided determines the permissions for
commands that can be run during the session.

logout

Logs out of the client session.

addUsersToGroup

Adds ones or more specified users to a particular group.

createGroup

Creates a new local group of users.

createUser

Creates a new local user.

deleteGroup

Deletes a local group.

deleteUser

Deletes a local user.

getGroup

Retrieves a group by its name.

105

ElectricCommander

Commands

Description

getGroups

Retrieves all groups.

getUser

Retrieves a user by name.

getUsers

Retrieves all users.

modifyGroup

Modifies an existing group.

modifyUser

Modifies an existing user.

removeUsersFromGroup

Removes one or more users from a particular group.

Workflow Definition Management


Commands

Description

createStateDefinition

Creates a new state definition for a workflow definition.

createTransitionDefinition

Creates a new transition definition for a workflow definition.

createWorkflowDefinition

Creates a new workflow definition for a project.

deleteStateDefinition

Deletes a state definition.

deleteTransitionDefinition

Deletes a transition definition.

deleteWorkflowDefinition

106

Deletes a workflow definition, including all state and transition


definitions.

getStateDefinition

Finds a state definition by name.

getStateDefinitions

Retrieves all state definitions in a workflow definition.

getTransitionDefinition

Finds a transition definition by name.

getTransitionDefinitions

Retrieves all transition definitions in a workflow definition.

getWorkflowDefinition

Finds a workflow definition by name.

getWorkflowDefinitions

Retrieves all workflow definitions in a project.

API Commands - listed by group and in alphabetical order

Commands

Description

modifyStateDefinition

Modifies an existing state definition.

modifyTransitionDefinition

Modifies an existing transition definition.

modifyWorkflowDefinition

Modifies an existing workflow definition.

moveStateDefinition

Moves a state definition within a workflow definition.

moveTransitionDefinition

Moves a transition definition within a workflow definition.

Workflow Management
Commands

completeWorkflow

Description
Marks a workflow as complete, which means transitions are no
longer evaluated.

deleteWorkflow

Deletes a workflow, including all states and transitions.

getState

Finds a state by name.

getStates

Retrieves all states in a workflow.

getTransition

Finds a transition by name.

getTransitions

Retrieves all transitions in a workflow.

getWorkflow

Finds a workflow by name.

getWorkflows

Retrieves all workflow instances in a project.

runWorkflow

Runs the specified workflow definition, returns the workflow name.

transitionWorkflow

Manually transition from a workflow active state.

Workspace Management

107

ElectricCommander

Commands

Description

createWorkspace

Creates a new workspace.

deleteWorkspace

Deletes a workspace.

getWorkspace

Retrieves a workspace by name.

getWorkspaces

Retrieves all workspaces.

modifyWorkspace

Modifies an existing workspace.

Miscellaneous
Commands

Description

changeOwner

Changes the owner of an object.


Makes a copy of an existing ElectricCommander project,

clone

procedure, step, schedule, resource, directory provider, email


configuration, or email notifier.

countObjects

Returns the count of objects specified by the provided filter.


This API deletes objects specified by the provided filters. Because

deleteObjects

of the complexity of specifying filter criteria, this API is not


supported by ectool. However, all of its capabilities are supported
through the Perl API.
Exports part or all server data to an XML file. The default is to
export all data in the systemthe specified path is interpreted by

export

the server. If the path is local, it will be created on the server


machine. If it is a network path, it must be accessible by the server
and the server user. If it is a relative path (NOT RECOMMENDED),
it must be relative to the servers working directory.
Finds several different types of Commander objectsit is the
underlying mechanism used to implement the Commander

findObjects

"Search" feature. Because of this command's general nature and


the complexity of specifying filter and sort criteria, it is not
supported by ectool. Use the Perl API for the findObjects
command.

108

API Commands - listed by group and in alphabetical order

Commands

Description
Used to retrieve the full object based on IDs returned by

getObjects

findObjects. All requested objects must be of the same


objectType. See findObjects for a list of object types.

import

Imports data from an XML export file.

API commands listed in alphabetical order


Click on a command to go to expanded information for that command, including its associated arguments
(required and optional),
descriptions, usage examples, and related commands.

Commands

Description

abortAllJobs

Aborts all running jobs.

abortJob

Aborts a running job.

abortJobStep

Aborts any type of stepcommand step or subprocedure step.


Adds an artifact version query to an existing artifact. Dependent

addDependentsToArtifactVersi
on

artifact versions are retrieved when the parent artifact version is


retrieved.

addResourcesToPool

Adds resources to a specific resource pool.

addUsersToGroup

Adds ones or more specified users to a particular group.

attachCredential

Attaches a credential to an object.

attachParameter

Attaches a formal parameter to a step.

breakAclInheritance

Breaks ACL (access control list) inheritance at the given object.

changeOwner

Changes the owner of an object.


Checks ACL (access control list) permission information

checkAccess

associated with an object (including inherited ACLs) for the


current user.

109

ElectricCommander

Commands

Description
Deletes stale artifact versions from an artifact cache. A "stale

cleanupArtifactCache

artifact version" is one whose metadata was previously deleted


from the Commander server.
Deletes stale artifact versions from the repository backing-store. A

cleanupRepository

"stale artifact version" is one whose metadata was previously


deleted from the Commander server.
Makes a copy of an existing ElectricCommander project,

clone

procedure, step, schedule, resource, directory provider, email


configuration, or email notifier.

completeJob

Completes an externally managed job.

completeJobStep

Completes an externally managed job step.

completeWorkflow

createAclEntry

Marks a workflow as complete, which means transitions are no


longer evaluated.
Creates an ACE (access control list entry) on an object for a given
principal.
Creates a new actual parameter for a step that calls a nested

createActualParameter

procedure. The parameter is passed to the nested procedure


when the step runs. At run time, the actual parameter name needs
to match the name of a formal parameter in the nested procedure.

createArtifact

Creates a new artifact.

createCredential

Creates a new credential for a project.

createDirectoryProvider

Creates a new LDAP directory provider.

createEmailConfig

Creates a new email configuration.

createEmailNotifier

Creates an email notifier on an object specified by an


emailNotifierSelector.

110

createFormalParameter

Creates a new formal parameter for a procedure.

createGateway

Creates a new gateway.

API Commands - listed by group and in alphabetical order

Commands

Description

createGroup

Creates a new local group of users.

createJob

Creates an externally managed job.

createJobStep

Creates a job step in an existing job.

createProcedure

Creates a new procedure for an existing project.

createProject

Creates a new project.

createProperty

Creates a regular string or nested property sheet using a


combination of property path and context.

createRepository

Creates a repository for one or more artifacts.

createResource

Creates a new resource.

createResourcePool

Creates a pool container for resources.

createSchedule

Creates a new schedule.

createStateDefinition

Creates a new state definition for a workflow definition.

createStep

Creates a new procedure step.

createTransitionDefinition

Creates a new transition definition for a workflow definition.

createUser

Creates a new local user.

createWorkflowDefinition

Creates a new workflow definition for a project.

createWorkspace

Creates a new workspace.

createZone

Creates a new zone.

deleteAclEntry

Deletes an ACE on an object for a given principal.

deleteActualParameter

Deletes an actual parameter.

deleteArtifact

Deletes an existing artifact element and all artifact versions.

111

ElectricCommander

Commands

Description
Deletes artifact version metadata from the Commander database.

deleteArtifactVersion

(This API call does not delete or remove artifacts stored on the
repository machine.)

deleteCredential

Deletes a credential.

deleteDirectoryProvider

Deletes an LDAP directory provider.

deleteEmailConfig

Deletes an email configuration.

deleteEmailNotifier

Deletes an email notifier from a property sheet container.

deleteFormalParameter

Deletes a formal parameter.

deleteGateway

Deletes a gateway.

deleteGroup

Deletes a local group.

deleteJob

Deletes a job from the ElectricCommander database.

deleteLicense

Deletes a license.
This API deletes objects specified by the provided filters. Because

deleteObjects

of the complexity of specifying filter criteria, this API is not


supported by ectool. However, all of its capabilities are supported
through the Perl API.

deletePlugin

deleteProcedure

deleteProject

deleteProperty

Deletes an existing plugin object without deleting the associated


project or files.
Deletes a procedure, including all steps.
Deletes a project, including all procedures, procedure steps, and
jobs.
Deletes a property from a property sheet.
Deletes artifact repository metadata from the Commander

deleteRepository

database. (This API call does not delete or remove artifacts stored
on the repository machine.)

deleteResource

112

Deletes a resource.

API Commands - listed by group and in alphabetical order

Commands

Description

deleteResourcePool

Deletes a resource pool.

deleteSchedule

Deletes a schedule.

deleteStateDefinition

Deletes a state definition.

deleteStep

Deletes a step from a procedure.

deleteTransitionDefinition

Deletes a transition definition.

deleteUser

Deletes a local user.

deleteWorkflow

Deletes a workflow, including all states and transitions.

deleteWorkflowDefinition

Deletes a workflow definition, including all state and transition


definitions.

deleteWorkspace

Deletes a workspace.

deleteZone

Deletes a zone.

detachCredential

Detaches a credential from an object.

detachParameter

Detaches a formal parameter from a step.


Evaluates a script in a given context.This API is similar to
expandString except that it evaluates the value argument as a

evalScript

Javascript block, without performing any property substitution on


either the script or the result.
The string value of the final expression in the script is returned as
the value element of the response.

expandString

Expands property references in a string, in the current context.


Exports part or all server data to an XML file. The default is to

export

export all data in the systemthe specified path is interpreted by


the server.

113

ElectricCommander

Commands

Description
This command returns the most current artifact version that
matches the filter criteria and its dependent artifact versions. This

findArtifactVersions

API implicitly searches for artifact versions in the "available" state,


and if run in a jobstep, registers the step as a retriever for the
returned artifact versions. Use the Perl API for the
findArtifactVersions command.
Returns a list of job steps from a single job or from a single

findJobSteps

subprocedure job step. This API is used by the Job Details web
page in the Commander UI.
This command finds several different types of Commander
objectsit is the underlying mechanism used to implement the

findObjects

Commander "Search" feature. Because of this command's general


nature and the complexity of specifying filter and sort criteria, it is
not supported by ectool. Use the Perl API for the findObjects
command.

getAccess

inherited ACLs.

getAclEntry

Retrieves an ACE on an object for a given principal.

getActualParameter

Retrieves an actual parameter by its name.

getActualParameters

Retrieves all actual parameters from a job, jobstep, or step.

getAdminLicense

Retrieves the admin license, which can be used when all


concurrent user licenses are in use.

getArtifact

Retrieves an artifact by its name.

getArtifacts

Retrieves all artifacts in the system.

getArtifactVersion

Retrieves an artifact version by its name.

getArtifactVersions

114

Retrieves ACL information associated with an object, including

Retrieves all artifact versions in the system, filtered by artifact


name, retriever job ID, and/or retriever job step ID.

getCredential

Finds a credential by name.

getCredentials

Retrieves all credentials in a project.

API Commands - listed by group and in alphabetical order

Commands

Description

getDatabaseConfiguration

Retrieves the current database configuration.

getDirectoryProvider

Retrieves an LDAP directory provider by name.

getDirectoryProviders

Retrieves all LDAP directory providers.

getEmailConfig

Retrieves an email configuration by name.

getEmailConfigs

Retrieves all email configurations.

getEmailNotifier

Retrieves an email notifier from a property sheet container.

getEmailNotifiers

getFormalParameter

getFormalParameters

getFullCredential

Retrieves all email notifiers defined for the specified property sheet
container.
Retrieves a formal parameter by its name.
Retrieves all formal parameters from a procedure, schedule, or
step.
Finds a credential by name, including password, from within a
running step.

getGateway

Finds a gateway by name.

getGateways

Retrieves all gateways.

getGroup

Retrieves a group by its name.

getGroups

Retrieves all groups.

getJobDetails

Retrieves complete information about a job, including details from


each job step.

getJobInfo

Retrieves all information about a job, except job step information.

getJobNotes

Retrieves the notes property sheet from a job.

getJobs

Retrieves summary information for a list of jobs.

getJobsForSchedule

Retrieves jobs started by a specific schedule.

getJobStatus

Retrieves the status of a job.

115

ElectricCommander

Commands

Description

getJobStepDetails

Retrieves details for a job step.

getJobStepStatus

Retrieves the status of a job step.

getLicense

Retrieves information for one license.

getLicenses

Retrieves all license data.

getLicenseUsage

Retrieves the current license usage.


Retrieves the manifest for a specified artifact version, which

getManifest

includes a list of files and directories in the artifact version, plus its
checksum file.
The getObjects command is used to retrieve the full object

getObjects

based on IDs returned by findObjects. All requested objects


must be of the same objectType. See findObjects for a list of
object types.

getPlugin

Retrieves an installed plugin.

getPlugins

Retrieves all installed plugins.

getProcedure

Finds a procedure by its name.

getProcedures

Retrieves all procedures in a project.

getProject

Finds a project by its name.

getProjects

Retrieves all projects.

getProperties

Retrieves all properties associated with an object.

getProperty

Retrieves the specified property value.

getRepositories

116

Retrieves all artifact repository objects known to the Commander


server.

getRepository

Retrieves an artifact repository by its name.

getResource

Retrieves a resource by its name.

getResources

Retrieves all resources.

API Commands - listed by group and in alphabetical order

Commands

Description

getResourcesInPool

Retrieves a list of resources in a pool.

getResourcePool

Retrieves a specified resource pool by name.

getResourcePools

Retrieves a list of resource pools.

getResourceUsage

Retrieves resource usage information.

getSchedule

Retrieves a schedule by its name.

getSchedules

Retrieves all schedules.

getServerStatus

Returns the status of the server.

getState

Finds a state by name.

getStates

Retrieves all states in a workflow.

getStateDefinition

Finds a state definition by name.

getStateDefinitions

Retrieves all state definitions in a workflow definition.

getStep

Retrieves a step from a procedure.

getSteps

Retrieves all steps in a procedure.

getTransition

Finds a transition by name.

getTransitions

Retrieves all transitions in a workflow.

getTransitionDefinition

Finds a transition by name.

getTransitionDefinitions

Retrieves all transition definitions in a workflow definition.

getUser

Retrieves a user by name.

getUsers

Retrieves all users.

getVersions

Retrieves server version information.

getWorkflow

Finds a workflow by name.

getWorkflows

Retrieves all workflow instances in a project.

117

ElectricCommander

Commands

Description

getWorkflowDefinition

Finds a workflow definition by name.

getWorkflowDefinitions

Retrieves all workflow definitions in a project.

getWorkspace

Retrieves a workspace by name.

getWorkspaces

Retrieves all workspaces.

getZone

Finds a zone by name.

getZones

Retrieves all zones.

import

Imports data from an XML export file.

importLicenseData

Imports one or more licenses.


Atomically increments the specified property value by the

incrementProperty

incrementByamount. If the property does not exist, it will be


created with an initial value of the incrementBy amount.

installPlugin

Installs a plugin from a JAR file. Extracts the JAR contents on the
server and creates a project and a plugin.
Logs into the server and saves the session ID for subsequent

login

ectool use. The userName provided determines the permissions


for commands that can be run during the session.

logout

Logs out of the client session.

modifyAclEntry

Modifies an ACE on an object for a given principal.


Modifies an existing actual parameter. An actual parameter is a

modifyActualParameter

name/value pair that is passed to a subprocedure. This command


supports renaming the actual parameter and setting its value.

118

modifyArtifact

Modifies an existing artifact.

modifyArtifactVersion

Modifies an existing artifact version.

modifyCredential

Modifies an existing credential.

modifyDirectoryProvider

Modifies an existing LDAP directory provider.

API Commands - listed by group and in alphabetical order

Commands

Description

modifyEmailConfig

Modifies an existing email configuration.

modifyEmailNotifier

Modifies an email notifier in a property sheet container specified


by an emailNotifierSelector.

modifyFormalParameter

Modifies an existing formal parameter.

modifyGateway

Modifies an existing gateway.

modifyGroup

Modifies an existing group.

modifyJob

Modifies the status of an externally managed job.

modifyJobStep

Modifies the status of an externally managed job step.

modifyPlugin

Modifies an existing plugin.

modifyProcedure

Modifies an existing procedure.

modifyProject

Modifies an existing project.

modifyProperty

Modifies a regular string or nested property sheet using a


combination of property path and context.

modifyRepository

Modifies an existing artifact repository.

modifyResource

Modifies an existing resource.

modifyResourcePool

Modifies an existing resource pool.

modifySchedule

Modifies an existing schedule.

modifyStateDefinition

Modifies an existing state definition.

modifyStep

Modifies an existing step.

modifyTransitionDefinition

Modifies an existing transition definition.

modifyUser

Modifies an existing user.

modifyWorkflowDefinition

Modifies an existing workflow definition.

modifyWorkspace

Modifies an existing workspace.

119

ElectricCommander

Commands

Description

modifyZone

Modifies an existing zone.

moveDirectoryProvider

moveJobs

moveRepository

Moves an LDAP directory provider in front of another specified


provider or to the end of the list.
Moves jobs from one project to another project.
Moves an artifact repository in front of another, specified repository
or to the end of the list.

moveStateDefinition

Moves a state definition within a workflow definition.

moveStep

Moves a step within a procedure.

moveTransitionDefinition

Moves a transition definition within a workflow definition.

pingAllResources

Pings all resources.

pingResource

Pings one resources.


Sets the promoted flag on a plugin. Only one version of a plugin
can be promoted at a time, so setting the promoted flag to true on

promotePlugin

one version sets the flag to false on all other plugins with the
same key. The promoted version is the one resolved by an indirect
reference of the form $[/plugins/<key>] or a plugin name
argument without a specified version.

publishArtifactVersion

Publishes an artifact version to an artifact repository.

removeDependentsFromArtifact
Version

Removes a list of dependent artifact versions from an existing

removeResourcesFromPool

Removes resources from a specified resource pool.

removeUsersFromGroup

Removes one or more users from a particular group.

restoreAclInheritance

Restores ACL inheritance at the given object.

retrieveArtifactVersions

120

artifact version.

Retrieves the most recent artifact version, including its


dependents, from an artifact repository.

API Commands - listed by group and in alphabetical order

Commands

runProcedure

runWorkflow

Description
Creates and starts a new job using a procedure directly or
specified indirectly through a schedule.
Runs the specified workflow definition, returns the workflow name.
Facilitates sending an email from the command-line or a
Command Step without setting up an Email Notifier. This API is

sendEmail

more dynamic than an email notifier because you do not need to


setup some kind of a template beforehand. This API also makes
sending email attachments easier than using a notifier template.
Sets the database configuration on the server. If the server is in

setDatabaseConfiguration

bootstrap mode, these changes take effect immediately and the


server attempts to start. If the server is running, these changes
have no effect until the server is restarted.

setJobName

Sets the name of a running job.

setProperty

Sets the value for the specified property.

shutdownServer

Shuts down the ElectricCommander server.

testDirectoryProvider

Tests an LDAP directory provider.

transitionWorkflow

Manually transition from the workflow active state.

uninstallPlugin

Uninstalls a plugin, deleting the associated project and any


installed files.

121

ElectricCommander

API commands - ACL Management


breakAclInheritance
checkAccess
createAclEntry
deleteAclEntry
getAccess
getAclEntry
modifyAclEntry
restoreAclInheritance

breakAclInheritance
Breaks ACL (access control list) inheritance at the given object. With inheritance broken, only the access control
entries directly on the ACL will be considered.
You must specify locator arguments to find the object where you want to break inheritance.

Arguments

Descriptions
The name of the application in ElectricFlow.

applicationName
Argument type: String
The name of the application tier in ElectricFlow.
applicationTierName
Argument type: String
The name of the artifact.
artifactName
Argument type: String
The name of the artifact version.
Note: An artifact version name is interpreted by the server as
the artifactVersionName attribute for the
artifactVersionName

artifactVersion in question. This name is parsed and


interpreted as "groupId:artifactKey:version" and the
object is searched either way you specify its name. The
ElectricCommander server interprets the name form correctly.
Argument type: String

122

API commands - ACL Management

Arguments

Descriptions
The name of the component.

componentName
Argument type: String
The name of the email configuration.
configName
Argument type: String
The name of the credential that can be one of these formats:

credentialName

relative (for example, "cred1")The credential is assumed


to be in the project that contains the request target object. A
qualifying project name is required.

absolute (for example,


"/projects/BuildProject/credentials/cred1")The credential
can be from any specified project, regardless of the project
where the target object is.

Argument type: String


The name of the environment in ElectricFlow.
environmentName
Argument type: String
The name of the environment template.
environmentTemplateName
Argument type: String
The name of the environment template tier.
environmentTemplateTierName
Argument type: String
The name of the environment tier in ElectricFlow.
environmentTierName
Argument type: String
The name of the gateway.
gatewayName
Argument type: String
The full name of the group. For Active Directory and LDAP, the full
groupName

name if the full domain name.


Argument type: String

123

ElectricCommander

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.
Argument type: String
The unique identifier for a job step that is assigned automatically

jobStepId

when the job step is created.


Argument type: UUID
The name of the email notifier.

notifierName
Argument type: String
This is an object identifier returned by findObjects and
getObjects. This value is a "handle" only for passing to API
objectId

commands. The internal structure of this value is subject to


change; do not parse this value.
Argument type: String
The property path.

path
Argument type: String
The plugin key for a promoted plugin or a plugin key and version
pluginName

for an unpromoted plugin.


Argument type: String
The name of the procedure or a path to a procedure that includes
the name.

procedureName

If you use this argument, you must also use projectName.


Argument type: String
The name of the process if the container is a process or process

processName

step.
Argument type: String
The name of the process step if the container is a process step.

processStepName
Argument type: String

124

API commands - ACL Management

Arguments

Descriptions
The name of the project, which can be a path.

projectName

The project name is ignored for credentials, procedures, steps,


and schedules if they are specified as a path.
Argument type: String
The unique identifier for a property sheet that is assigned

propertySheetId

automatically when the property sheet is created.


Argument type: UUID
The name of the repository used for artifact management.

repositoryName
Argument type: String
The name of a resource.
resourceName
Argument type: String
The name of a pool containing one or more resources.
resourcePoolName
Argument type: String
resourceTemplateName

The name of the resource template.


The name of a schedule, which can be a path to the schedule. If

scheduleName

you use this argument, you must also use projectName.


Argument type: String
The name of the snapshot.

snapshotName
Argument type: String
The name of the state definition.
stateDefinitionName
Argument type: String
The name of the state.
stateName
Argument type: String

125

ElectricCommander

Arguments

Descriptions
The name of the step, which can be a path to the step.

stepName

If you use this argument, you must also use projectName and
procedureName.
Argument type: String
The name of the system object.

systemObjectName

System objects names include:


admin|artifactVersions|directory|emailConfigs|log|p
lugins|
server|session|workspaces.
Argument type: SystemObjectName
The name of the transition definition.

transitionDefinitionName
Argument type: String
The name of the transition.
transitionName
Argument type: String
The full name of a user. For Active Directory or LDAP, this may be
userName

user@domain).
Argument type: String
The name of the workflow definition.

workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String
The name of a workspace.
workspaceName
Argument type: String
The name of the zone.
zoneName
Argument type: String

Positional arguments
Arguments to locate the object, beginning with the top-level object locator.

126

API commands - ACL Management

Response
None or status OK message.

ec-perl
syntax: $cmdr->breakAclInheritance({...});

Example
$cmdr->breakAclInheritance ({ projectName => "Sample Project"});

ectool
syntax: ectool breakAclInheritance ...

Example
ectool breakAclInheritance --projectName "Sample Project"
Back to Top

checkAccess
Checks access control list (ACL) permission information associated with an object for the current user, including
inherited ACLs.
You must specify object locator arguments to define the object where you need to verify access.

Arguments

Descriptions
The name of the application that must be unique among all projects.

applicationName
Argument type: String
The name of the application tier.
applicationTierName
Argument type: String
The name of the artifact.
artifactName
Argument type: String

127

ElectricCommander

Arguments

Descriptions
The name of the artifact version.
Note: An artifact version name is interpreted by the server as the
artifactVersionName attribute for the artifactVersion in

artifactVersionName

question. This name is parsed and interpreted as


"groupId:artifactKey:version" and the object is
searched when you specify its name one of these ways. The
Electric Commander server interprets the name form correctly.
Argument type: String
The name of the component.

componentName
Argument type: String
The name of the email configuration.
configName
Argument type: String
The name of the credential container of the property sheet that owns
the property.
Specify credentialName using one of two forms:
l

relative (for example, "cred1")The credential is assumed to


be in the project that contains the request target object. This
form requires a qualifying project name.

absolute (for example,


"/projects/BuildProject/credentials/cred1")The credential
can be from any specified project, regardless of the project
target object project.

credentialName

Argument type: String


The name of the environment that must be unique among all
environmentName

projects.
Argument type: String
The name of the environment template.

environmentTemplateName
Argument type: String
The name of the environment template tier.
environmentTemplateTierName
Argument type: String

128

API commands - ACL Management

Arguments

Descriptions
The name of the environment tier.

environmentTierName
Argument type: String
The name of the gateway.
gatewayName
Argument type: String
The full name of the group. For Active Directory and LDAP, this is a
groupName

full domain name.


Argument type: String
The unique Commander-generated identifier (a UUID) for a job that
is assigned automatically when the job is created. The system also

jobId

accepts a job name assigned to the job by its name template.


Argument type: String
The unique identifier for a job step that is assigned automatically
when the job step is created.

jobStepId
Argument type: UUID

The name of the email notifier.


notifierName
Argument type: String
The object identifier returned by findObjects and getObjects.
This value is a "handle" only for passing to API commands. The
objectId

internal structure of this value is subject to change. Do not parse this


value.
Argument type: String
Property path string.

path
Argument type: String
The name of the plugin. This is the plugin key for a promoted plugin
pluginName

or a plugin key and version for an unpromoted plugin.


Argument type: String

129

ElectricCommander

Arguments

Descriptions
The name of the procedure. It can be be a path to the procedure.

procedureName

When using this procedure, you must also use projectName.


Argument type: String
The name of the process.

processName
Argument type: String
The name of the process step.
processStepName
Argument type: String
The name of the project that must be unqiue among all projects. It
can be a path to the project. The project name is ignored for
projectName

credentials, procedure, steps, and schedules when it is specified as


a path.
Argument type: String
The unique identifier for a property sheet that is assigned

propertySheetId

automatically when the property sheet is created.


Argument type: UUID
The name of the repository for artifact management.

repositoryName
Argument type: String
The name of the resource.
resourceName
Argument type: String
The name of a pool containing one or more resources.
resourcePoolName
Argument type: String
The name of the resource template.
resourceTemplateName
Argument type: String
The name of the schedule. It can be path to the schedule. When
scheduleName

using this argument, you must also enter projectName.


Argument type: String

130

API commands - ACL Management

Arguments

Descriptions
The name of the snapshot. It can be path to the snapshot.

snapshotName
Argument type: String
The name of the state definition.
stateDefinitionName
Argument type: String
The name of the state.
stateName
Argument type: String
The name of the step. It can be a path to the step. When using this
stepName

argument, you must also enter projectName and procedureName.


Argument type: String

systemObjectName

System object names include:


admin|directory|licensing|log|plugins|priority|proje
cts|.
Argument type: SystemObjectName
The name of the transition definition.

transitionDefinitionName
Argument type: String
The name of the transition.
transitionName
Argument type: String
The full name of the user. For Active Directory and LDAP, the name
userName

can be user@domain.
Argument type: String
The name of the workflow definition.

workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String
The name of the workspace.
workspaceName
Argument type: String

131

ElectricCommander

Arguments

Descriptions
The name of the zone.

zoneName
Argument type: String

Positional arguments
Arguments to locate the object, beginning with the top-level object locator.

Response
For the specified object, returns the effective permissions for the current user.

ec-perl
syntax: $cmdr->checkAccess({...});

Example
$cmdr->checkAccess ({"projectName"=>"Sample Project"});

ectool
syntax: ectool checkAccess ...

Example
ectool checkAccess -projectName "Sample Project"
Back to Top

createAclEntry
Creates an ACE (access control list entry) on an object for a given principal.
You must specify the principalType, principalName, and locator options for the object to modify.

Arguments

Descriptions
This is either user or group.

principalType
Argument type: PrincipalType
This is either a user or a group name.
principalName
Argument type: PrincipalName
The name of the application that must be unique among all
applicationName

projects.
Argument type: String

132

API commands - ACL Management

Arguments

Descriptions
The name of the application tier.

applicationTierName
Argument type: String
The name of the artifact.
artifactName
Argument type: String
The name of the artifact version.
Note: An artifact version name is interpreted by the server as
the artifactVersionName attribute for the
artifactVersionName

artifactVersion in question. This name is parsed and


interpreted as "groupId:artifactKey:version" and the
object is searched either way you specify its name. The
ElectricCommander server interprets the name form correctly.
Argument type: String
<allow|deny> Determines whether the principal can modify

changePermissionsPrivilege

access control for the object.


Argument type: Access
The name of the component.

componentName
Argument type: String
The name of the email configuration.
configName
Argument type: String
The name of the credential specified in one of these formats:

credentialName

relative(for example, "cred1")The credential is assumed


to be in the project that contains the requested target
object.

absolute(for example,
"/projects/BuildProject/credentials/cred1")The credential
can be from any specified project, regardless of the project
for the target object.

When using this argument, you must also enter projectName.


Argument type: String

133

ElectricCommander

Arguments

Descriptions
The name of the environment that must be unique among all

environmentName

projects.
Argument type: String
The name of the environment template.

environmentTemplateName
Argument type: String
The name of the environment template tier.
environmentTemplateTierName
Argument type: String
The name of the environment tier.
environmentTierName
Argument type: String
<allow|deny> Determines whether the principal can invoke this
object as part of a job. This privilege is only relevant for a few
executePrivilege

objects such as procedures and procedure steps.


Argument type: String
The name of the gateway.

gatewayName
Argument type: String
The name of a group.
groupName
Argument type: String
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system
jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID
The unique identifier for a job step that is assigned automatically

jobStepId

when the job step is created.


Argument type: UUID
<allow|deny> Determines whether the principal can change the

modifyPrivilege

contents of the object.


Argument type: Access

134

API commands - ACL Management

Arguments

Descriptions
The name of the email notifier.

notifierName
Argument type: String
The object identifier returned by findObjects and getObjects.
objectId
Argument type: String
Path to the property.
path
Argument type: String
The name of the plugin.It is the plugin key for a promoted plugin or
pluginName

the plugin key and version for an unpromoted plugin.


Argument type: String
The name of the procedure. When using this argument, you must

procedureName

also enter projectName.


Argument type: String
The name of the process.

processName
Argument type: String
The name of the process step.
processStepName
Argument type: String
The name of the project.
projectName
Argument type: String
The unique identifier for a property sheet that is assigned
propertySheetId

automatically when the property sheet is created.


Argument type: UUID
<allow|deny> Determines whether the principal can examine

readPrivilege

the contents of the object.


Argument type: Access
The name of the repository for artifact management.

repositoryName
Argument type: String

135

ElectricCommander

Arguments

Descriptions
The name of the resource.

resourceName
Argument type: String
The name of a pool containing one or more resources.
resourcePoolName
Argument type: String
The name of the resource template.
resourceTemplateName
Argument type: String
The name of the schedule. When using this argument, you must
scheduleName

also enter projectName.


Argument type: String
The name of the snapshot.

snapshotName
Argument type: String
The name of the state definition.
stateDefinitionName
Argument type: String
The name of the state.
stateName
Argument type: String
The name of the step. When using this argument, you must also
stepName

enter projectName and procedureName.


Argument type: String

systemObjectName

System object names include:


admin|artifacts|directory|emailConfigs|forceAbort|l
icensing|
log|plugins|priority|projects|repositories|resource
s|server| session|test|workspaces|zonesAndGateways
Argument type: SystemObjectName

The name of the transition definition.


transitionDefinitionName
Argument type: String

136

API commands - ACL Management

Arguments

Descriptions
The name of the transition.

transitionName
Argument type: String
The full name of the user.
userName
Argument type: String
The name of the workflow definition.
workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String
The name of the workspace.
workspaceName
Argument type: String
The name of the zone.
zoneName
Argument type: String

Positional arguments
principalType and principalName

Response
None or status OK message.

ec-perl
syntax: $cmdr->createAclEntry(<principalType> <principalName>, {...});

Example
$cmdr->createAclEntry("user", "j smith", {"projectName"=>"Sample Project",
"readPrivilege"=>"allow", "modifyPrivilege"=>"deny", "executePrivilege"=>"deny",
"changePermissionsPrivilege"=>"deny"});

ectool
syntax: ectool createAclEntry <principalType> <principalName> ...

Example
ectool createAclEntry user "j smith" --projectName "Sample Project" --readPrivilege
allow
--modifyPrivilege deny --executePrivilege deny --changePermissionsPrivilege deny
Back to Top

137

ElectricCommander

deleteAclEntry
Deletes an access control entry (ACE) in an access control list (ACL) on an object for a given principal (user or
group).
You must specify principalType, principalName, and locator arguments.

Arguments

Descriptions
A user or a group: <user|group>. The default is to user.

principalType
Argument type: PrincipalType
The name of the user or the group.
principalName
Argument type: PrincipalName
The name of the application that must be unique among all
applicationName

projects.
Argument type: String
The name of the application tier.

applicationTierName
Argument type: String
The name of the artifact.
artifactName
Argument type: String
The name of the artifact version.
Note: An artifact version name is interpreted by the server as
the
artifactVersionName attribute for the artifactVersion in
question.
artifactVersionName
This name is parsed and interpreted as
"groupId:artifactKey:version" and the object is searched
either way you specify its name. The Commander server interprets
the name form correctly.
Argument type: String
The name of the component.
componentName
Argument type: String

138

API commands - ACL Management

Arguments

Descriptions
The name of the email configuration.

configName
Argument type: String
The name of the credential specified in one of these formats:

credentialName

relative(for example, "cred1")The credential is assumed


to be in the project that contains the requested target
object.

absolute(for example,
"/projects/BuildProject/credentials/cred1")The credential
can be from any specified project, regardless of the project
for the target object.

Argument type: String


The name of the environment that must be unique among all
environmentName

projects.
Argument type: String
The name of the environment template that must be unique among

environmentTemplateName

all projects.
Argument type: String
Name of the environment template tier that must be unique among

environmentTemplateTierName

all tiers for the environment template.


Argument Type: String
The name of the environment tier.

environmentTierName
Argument type: String
The name of the gateway.
gatewayName
Argument type: String
The name of a group whose ACL entry you want to delete.
groupName
Argument type: String
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system
jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID

139

ElectricCommander

Arguments

Descriptions
The unique identifier for a job step that is assigned automatically

jobStepId

when the job step is created.


Argument type: UUID
The name of the email notifier with the ACE that you want to

notifierName

delete.
Argument type: String
An object identifier returned by findObjects and getObjects.

objectId
Argument type: String
Path to the property.
path
Argument type: String
The name of the plugin with the ACE that you want to delete.
pluginName
Argument type: String
The name of the procedure with the ACE that you want to delete.
When you use this argument, you must also enter projectName
procedureName

for the project of which this procedure is a member.


Argument type: String
The name of the process.

processName
Argument type: String
The name of the process step.
processStepName
Argument type: String
The name of the project with the ACE that you want to delete.
projectName
Argument type: String
The unique identifier for a property sheet that is assigned
propertySheetId

automatically when the property sheet is created.


Argument type: UUID
The name of the repository for artifact management.

repositoryName
Argument type: String

140

API commands - ACL Management

Arguments

Descriptions
The name of the resource with the ACE that you want to delete.

resourceName
Argument type: String
The name of a pool containing one or more resources.
resourcePoolName
Argument type: String
Name of the resource template.
resourceTemplateName
Argument Type: String
The name of the schedule with the ACE that you want to delete.
When you use this argument, you must also enter projectName
scheduleName

from which this schedule runs procedures.


Argument type: String
The name of the snapshot.

snapshotName
Argument type: String
The name of the state definition.
stateDefinitionName
Argument type: String
The name of the state.
stateName
Argument type: String
The name of the step with the ACE that you want to delete. When
using this argument, you must also enter projectName and
stepName

procedureName to indicate where this step resides.


Argument type: String

systemObjectName

System object names include:


admin|directory|licensing|log|plugins|priority|
projects|resources|server|session|workspaces
Argument type: SystemObjectName

The name of the transition definition.


transitionDefinitionName
Argument type: String

141

ElectricCommander

Arguments

Descriptions
The name of the transition.

transitionName
Argument type: String
The name of the user with the ACE that you want to delete.
userName
Argument type: String
The name of the workflow definition.
workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String
The name of the workspace with the ACL entry that you want to
workspaceName

delete.
Argument type: String
The name of the zone.

zoneName
Argument type: String

Positional arguments
principalType, principalName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deleteAclEntry(<principalType>, <principalName>, {<optionals>});

Example
$cmdr->deleteAclEntry('user', 'j smith', {projectName => 'Sample Project'});

ectool
syntax: ectool deleteAclEntry <principalType> <principalName> ...

Example
ectool deleteAclEntry user "j smith" --projectName "Sample Project"
Back to Top

142

API commands - ACL Management

getAccess
Retrieves ACL (access control list) information associated with an object, including inherited ACLs.
You must specify object locators to find the object to which you need to verify access.

Arguments

Descriptions
(Optional) The name of the application that must be unique among

applicationName

all projects.
Argument type: String
(Optional) The name of the application tier.

applicationTierName
Argument type: String
(Optional) The name of the artifact.
artifactName
Argument type: String
(Optional) The name of the artifact version.
Note: An artifact version name is interpreted by the server as
the artifactVersionName attribute for the
artifactVersionName

artifactVersion in question. This name is parsed and


interpreted as "groupId:artifactKey:version" and the
object is searched either way you specify its name. The
Commander server interprets the name form correctly.
Argument type: String
(Optional) The name of the component.

componentName
Argument type: String
(Optional) The name of the email configuration.
configName
Argument type: String

143

ElectricCommander

Arguments

Descriptions
(Optional) The name of the credential specified in one of these
formats:

credentialName

relative(for example, "cred1")The credential is assumed


to be in the project that contains the requested target
object.

absolute(for example,
"/projects/BuildProject/credentials/cred1")The credential
can be from any specified project, regardless of the project
for the target object.

Argument type: String

(Optional) Whether or not to include one level of broken


inheritance if it exists. This argument is used for seeing what
access would look like if the lowest level of broken inheritance was
restored.
emulateRestoreInheritance

<Boolean flag - 0|1|true|false> If set to 1, this argument


returns ACL information to what it would be if inheritance were
restored on this object.
Argument type: Boolean
(Optional) The name of the environment that must be unique

environmentName

among all projects.


Argument type: String
(Optional) Name of the environment template.

environmentTemplateName
Argument type:String
(Optional) Name of the environment template tier.
environmentTemplateTierName
Argument type:String
(Optional) The name of the environment tier.
environmentTierName
Argument type: String
(Optional) The name of the gateway.
gatewayName
Argument type: String

144

API commands - ACL Management

Arguments

Descriptions
(Optional) The name of the group.

groupName
Argument type: String
(Optional) The unique Commander-generated identifier (a UUID)
for a job that is assigned automatically when the job is created.
jobId

The system also accepts a job name assigned to the job by its
name template.
Argument type: String
(Optional) The unique identifier for a job step that is assigned

jobStepId

automatically when the job step is created.


Argument type: String
(Optional) The name of the email notifier with the ACL.

notifierName
Argument type: String
(Optional) An object identifier returned by findObjects and
objectId

getObjects.
Argument type: String
(Optional) Property path.

path
Argument type: String
(Optional) The name of the plugin with the ACL.
pluginName
Argument type: String
(Optional) The name of the procedure with the ACL. When using
procedureName

this argument, you must also enter projectName.


Argument type: String
(Optional) The name of the process.

processName
Argument type: String
(Optional) The name of the process step.
processStepName
Argument type: String

145

ElectricCommander

Arguments

Descriptions
(Optional) The name of the project that contains the ACL that must

projectName

be unique among all projects.


Argument type: String
(Optional) The unique identifier for a property sheet that is

propertySheetId

assigned automatically when the property sheet is created.


Argument type: UUID
The name of the repository for artifact management.

repositoryName
Argument type: String
The name of the resource with the ACL.
resourceName
Argument type: String
The name of a pool with one or more resources.
resourcePoolName
Argument type: String
(Optional) Name of the resource template.
resourceTemplateName
Argument type:String

scheduleName

(Optional) The name of the schedule with the ACL.


Also requiresprojectName
(Optional) The name of a snapshot.

snapshotName
Argument type: String
stateDefinitionName

(Optional) The name of the state definition.

stateName

(Optional) The name of the state.


(Optional) The name of the step containing the ACL. When using

stepName

this argument, you must also enter projectName


Argument type: String

systemObjectName

(Optional) System objects include:


admin|artifactVersions|directory|emailConfigs|log|p
lugins|
server|session|workspaces
Argument type: SystemObjectName

146

API commands - ACL Management

Arguments

Descriptions
(Optional) The name of the transition definition.

transitionDefinitionName
Argument type: String
(Optional) The name of the transition.
transitionName
Argument type: String
(Optional) The name of the user with the ACL.
userName
Argument type: String
(Optional) The name of the workflow definition.
workflowDefinitionName
Argument type: String
(Optional) The name of the workflow.
workflowName
Argument type: String
(Optional) The name of the workspace with the ACL.
workspaceName
Argument type: String
(Optional) The name of the zone.
zoneName
Argument type: String

Positional arguments
Arguments to specify the object, beginning with the top-level object locator.

Response
One or more object elements, each consisting of one or more aclEntry elements. Each object
represents
an object in the ACL inheritance chain starting with the most specific object. Each aclEntry identifies a
user or
group and the privileges granted or denied by the entry, and includes a breakInheritance element if
applicable.

ec-perl
syntax: $cmdr->getAccess({<optionals>});

Example
$cmdr->getAccess({projectName => "Sample Project"});

147

ElectricCommander

ectool
syntax: ectool getAccess ...

Example
ectool getAccess --projectName "Sample Project"
Back to Top

getAclEntry
Retrieves an ACE (access control entry) list on an object for a given principal.
You must specify a principalType, principalName, and an object locator to specify the ACE.

Arguments

Descriptions
This is either user or group.

principalType
Argument type: PrincipalType
This is either a user or a group name.
principalName
Argument type: PrincipalName
(Optional) The name of the application that must be unique among
applicationName

all projects.
Argument type: String
(Optional) The name of the application tier.

applicationTierName
Argument type: String
(Optional) The name of the artifact.
artifactName
Argument type: String
(Optional) The name of the artifact version.
Note: An artifact version name is interpreted by the server as
the artifactVersionName attribute for the
artifactVersionName

artifactVersion in question. This name is parsed and


interpreted as "groupId:artifactKey:version" and the
object is searched either way you specify its name. The
ElectricCommander server interprets the name form correctly.
Argument type: String

148

API commands - ACL Management

Arguments

Descriptions
(Optional) The name of the component.

componentName
Argument type: String
(Optional) The name of the email configuration.
configName
Argument type: String
(Optional) The name of the credential specified in one of these
formats:

credentialName

relative(for example, "cred1")The credential is assumed


to be in the project that contains the requested target
object.

absolute(for example,
"/projects/BuildProject/credentials/cred1")The credential
can be from any specified project, regardless of the project
for the target object.

Argument type: String

(Optional) The name of the environment that must be unique


environmentName

among all projects.


Argument type: String
(Optional) Name of the environment template.

environmentTemplateName
Argument type:String
(Optional) Name of the environment template tier.
environmentTemplateTierName
Argument type:String
(Optional) The name of the gateway.
gatewayName
Argument type: String
(Optional) The name of the group.
groupName
Argument type: String

149

ElectricCommander

Arguments

Descriptions
(Optional) The unique Commander-generated identifier (a UUID)
for a job that is assigned automatically when the job is created.

jobId

The system also accepts a job name assigned to the job by its
name template.
Argument type: UUID
(Optional) The unique identifier for a job step that is assigned

jobStepId

automatically when the job step is created.


Argument type: String
(Optional) The name of the email notifier.

notifierName
Argument type: String
(Optional) This is an object identifier returned by findObjects
objectId

and getObjects.
Argument type: String
(Optional) Property path.

path
Argument type: String
(Optional) The name of the plugin. The plugin key for a promoted
pluginName

plugin or the plugin key and version for an unpromoted plugin.


Argument type: String
(Optional) The name of the procedure with the ACL. When using

procedureName

this argument, you must also enter projectName.


Argument type: String
(Optional) The name of the process.

processName
Argument type: String
(Optional) The name of the process step.
processStepName
Argument type: String
(Optional) The name of the project.
projectName
Argument type: String

150

API commands - ACL Management

Arguments

Descriptions
(Optional) The unique identifier for a property sheet that is

propertySheetId

assigned automatically when the property sheet is created.


Argument type: String
(Optional) The name of the repository for artifact management.

repositoryName
Argument type: UUID
(Optional) The name of the resource.
resourceName
Argument type: String
(Optional) The name of a pool containing one or more resources.
resourcePoolName
Argument type: String
(Optional) Name of the resource template.
resourceTemplateName
Argument type:String

scheduleName

(Optional) The name of a schedule. When using this argument,


you must also enter projectName.
(Optional) The name of a snapshot.

snapshotName
Argument type: String
(Optional) The name of the state definition.
stateDefinitionName
Argument type: String
(Optional) The name of the state.
stateName
Argument type: String
(Optional) The name of the step. When using this argument, you
stepName

must also enter projectName and procedureName.


Argument type: String

systemObjectName

(Optional) System objects include:


admin|artifactVersions|directory|emailConfigs|log|p
lugins|
server|session|workspaces
Argument type: SystemObjectName

151

ElectricCommander

Arguments

Descriptions
(Optional) The name of the transition definition.

transitionDefinitionName
Argument type: String
(Optional) The name of the transition.
transitionName
Argument type: String
(Optional) The full name of the user.
userName
Argument type: String
(Optional) The name of the workflow definition.
workflowDefinitionName
Argument type: String
(Optional) The name of the workflow.
workflowName
Argument type: String
(Optional) The name of the workspace.
workspaceName
Argument type: String
(Optional) The name of the zone.
zoneName
Argument type: String

Positional arguments
principalType, principalName

Response
One aclEntry element.

ec-perl
syntax: $cmdr->getAclEntry(<principalType>, < principalName>, {...});

Example
$cmdr->getAclEntry("user", "j smith", {projectName => "Sample Project"});

ectool
syntax: ectool getAclEntry <principalType> < principalName> ...

Example
ectool getAclEntry --user "j smith" --projectName "Sample Project"
Back to Top

152

API commands - ACL Management

modifyAclEntry
Modifies an ACE (access control entry) in an access control list (ACL) on an object for a given principal.
Note: If a privilege is not specified, an object inherits it from its parent object ACL.
You must specify principalType, principalName, and object locator arguments to identify the target ACL.

Arguments

Descriptions
This is either user or group.

principalType
Argument type: PrincipalType
This is either a user or a group name.
principalName
Argument type: PrincipalName
The name of the application that must be unique among all
applicationName

projects.
Argument type: String
The name of the application tier.

applicationTierName
Argument type: String
The name of the artifact.
artifactName
Argument type: String
The name of the artifact version.
An artifact version name is interpreted by the server as the
artifactVersionName attribute for the artifactVersion in
artifactVersionName

question. This name is parsed and interpreted as


"groupId:artifactKey:version" and the object is searched
either way you specify its name. The Commander server interprets
the name form correctly.
Argument type: String
<allow|deny> Determines whether the principal can modify

changePermissionsPrivilege

access control for the object.


Argument type: Access
The name of the component.

componentName
Argument type: String

153

ElectricCommander

Arguments

Descriptions
The name of the email configuration.

configName
Argument type: String
The name of the credential specified in one of these formats:

credentialName

relative(for example, "cred1")The credential is assumed


to be in the project that contains the requested target
object.

absolute(for example,
"/projects/BuildProject/credentials/cred1")The credential
can be from any specified project, regardless of the project
for the target object.

Argument type: String


The name of the environment that must be unique among all
environmentName

projects.
Argument type: String
Name of the environment template.

environmentTemplateName
Argument type:String
Name of the environment template tier.
environmentTemplateTierName
Argument type:String
The name of the environment tier.
environmentTierName
Argument type: String
<allow|deny> Determines whether the principal can invoke this
object as part of a job. This privilege is only relevant for a few
executePrivilege

objects such as procedures and procedure steps.


Argument type: Access
The name of the gateway.

gatewayName
Argument type: String
The name of the group with the ACL entry.
groupName
Argument type: String

154

API commands - ACL Management

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID
The unique identifier for a job step that is assigned automatically

jobStepId

when the job step is created.


Argument type: UUID
<allow|deny> Determines whether the principal can change the

modifyPrivilege

contents of the object.


Argument type: Access
The name of the email notifier with the ACL entry.

notifierName
Argument type: String
The object identifier returned by findObjects and getObjects.
objectId
Argument type: String
Property path.
path
Argument type: String
The name of the plugin with the ACL entry.
pluginName
Argument type: String
The name of the procedure with the ACL entry. When using this
procedureName

argument, you must also enter projectName.


Argument type: String
The name of the process.

processName
Argument type: String
The name of the process step.
processStepName
Argument type: String
The name of the project with the ACL entry.
projectName
Argument type: String

155

ElectricCommander

Arguments

Descriptions
The unique identifier for a property sheet that is assigned

propertySheetId

automatically when the property sheet is created.


Argument type: UUID
<allow|deny> Determines whether the principal can examine

readPrivilege

the contents of the object.


Argument type: Access
The name of the repository for artifact management.

repositoryName
Argument type: String
The name of the resource containing the ACL entry.
resourceName
Argument type: String
The name of a pool containing one or more resources.
resourcePoolName
Argument type: String
Name of the resource template.
resourceTemplateName
Argument type:String
The name of the schedule with the ACL entry. When using this
scheduleName

argument, you must also enter projectName.


Argument type: String
The name of a snapshot.

snapshotName
Argument type: String
The name of the state definition.
stateDefinitionName
Argument type: String
The name of the state.
stateName
Argument type: String
The name of the step with the ACL entry. . When using this
stepName

argument, you must also enter projectName.


Argument type: String

156

API commands - ACL Management

Arguments

systemObjectName

Descriptions
System object names include:
admin|artifacts|directory|emailConfigs|forceAbort|
licensing|log|plugins|priority|projects|
repositories|resources|server|session|test|
workspaces|zonesAndGateways
Argument type: SystemObjectName

The name of the transition definition.


transitionDefinitionName
Argument type: String
The name of the transition.
transitionName
Argument type: String
The name of the user containing the ACL entry.
userName
Argument type: String
The name of the workflow definition.
workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String
The name of the workspace containing the ACL entry.
workspaceName
Argument type: String
The name of the zone.
zoneName
Argument type: String

Positional arguments
principalType, principalName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->modifyAclEntry(<principalType>, <principalName>, {<optionals>});

157

ElectricCommander

Example
$cmdr->modifyAclEntry("user", "j smith", {projectName => "Sample Project",
modifyPrivilege => "deny", });

ectool
syntax: ectool modifyAclEntry <principalType> <principalName> ...

Example
ectool modifyAclEntry user "j smith" --projectName "Sample Project"
--modifyPrivilege deny
Back to Top

restoreAclInheritance
Restores ACL (access control list) inheritance for the specified object.
Note: You must use object locators to specify the object where you want to restore ACL inheritance.

Arguments

Descriptions
The name of the application that must be unique among all

applicationName

projects.
Argument type: String
The name of the application tier.

applicationTierName
Argument type: String
The name of the artifact.
artifactName
Argument type: String
The name of the artifact version.
Note: An artifact version name is interpreted by the server as
the artifactVersionName attribute for the
artifactVersion in question.
artifactVersionName

This name is parsed and interpreted as


"groupId:artifactKey:version" and the object is
searched either way you specify its name. The
ElectricCommander server interprets the name form correctly.
Argument type: String

158

API commands - ACL Management

Arguments

Descriptions
The name of the component.

componentName
Argument type: String
The name of the email configuration.
configName
Argument type: String
The name of the credential specified in one of these formats:

credentialName

relative(for example, "cred1")The credential is assumed


to be in the project that contains the requested target
object.

absolute(for example,
"/projects/BuildProject/credentials/cred1")The credential
can be from any specified project, regardless of the project
for the target object.

When using this argument, you must also enter projectName.


Argument type: String
The name of the environment that must be unique among all
environmentName

projects.
Argument type: String
Name of the environment template.

environmentTemplateName
Argument type:String
Name of the environment template tier.
environmentTemplateTierName
Argument type:String
The name of the environment tier.
environmentTierName
Argument type: String
The name of the gateway.
gatewayName
Argument type: String
The name of the group with the ACL inheritance that you want to
groupName

restore.
Argument type: String

159

ElectricCommander

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.
Argument type: String
The unique identifier for a job step that is assigned automatically

jobStepId

when the job step is created.


Argument type: String
The name of the email notifier with the ACL inheritance that you
want to restore.
Also requires projectName and procedureName;

notifierName

projectName,procedureName, and stepName; jobId or


jobStepId
Argument type: String

objectId

This is an object identifier returned by findObjects and


getObjects.
Property path.

path
Argument type: String
The name of the plugin with the ACL inheritance that you want to
pluginName

restore.
Argument type: String
The name of the procedure with the ACL inheritance that you want
to restore. When using this argument, you must also enter

procedureName

projectName.
Argument type: String
The name of the process.

processName
Argument type: String
The name of the process step.
processStepName
Argument type: String

160

API commands - ACL Management

Arguments

Descriptions
The name of the project with the ACL inheritance that you want to

projectName

restore.
Argument type: String
The unique identifier for a property sheet that is assigned

propertySheetId

automatically when the property sheet is created.


Argument type: UUID
The name of the repository for artifact management.

repositoryName
Argument type: String
The name of the resource whose ACL inheritance you want to
resourceName

restore.
Argument type: String
The name of a pool containing one or more resources.

resourcePoolName
Argument type: String
Name of the resource template.
resourceTemplateName
Argument type:String
The name of the schedule with the ACL inheritance that you want
to restore. When using this argument, you must also enter
scheduleName

projectName.
Argument type: String
The name of a snapshot.

snapshotName
Argument type: String
The name of the state definition.
stateDefinitionName
Argument type: String
The name of the state.
stateName
Argument type: String

161

ElectricCommander

Arguments

Descriptions
The name of the step with the ACL inheritance that you want to
restore. When using this argument, you must also enter

stepName

projectName and procedureName.


Argument type: String
The name of the system object whose ACL inheritance you want to
restore.

systemObjectName

System objects include:


admin|artifactVersions|directory|emailConfigs|
log|plugins|server|session|workspaces
Argument type: SystemObjectName
The name of the transition definition.

transitionDefinitionName
Argument type: String
The name of the transition.
transitionName
Argument type: String
The name of the user with the ACL inheritance that you want to
userName

restore.
Argument type: String
The name of the workflow definition.

workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String
The name of the workspace with the ACL inheritance that you want
workspaceName

to restore.
Argument type: String
The name of the zone.

zoneName
Argument type: String

Positional arguments
Arguments to locate the object, beginning with the top-level object locator.

162

API commands - ACL Management

Response
None or a status OK message.

ec-perl
syntax: $cmdr->restoreAclInheritance({<optionals>});

Example
$cmdr->restoreAclInheritance({projectName => "Sample Project"});

ectool
syntax: ectool restoreAclInheritance ...

Example
ectool restoreAclInheritance --projectName "Sample Project"
Back to Top

163

ElectricCommander

API commands - Applications


createApplication
deleteApplication
getApplication
getApplications
modifyApplication

createApplication
Creates a new application for a project.
You must specify the projectName and the applicationName arguments.

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String
Name of the application that must be unique among all projects.
applicationName
Argument Type: String
Comment text describing this object that is not interpreted at all by
description

ElectricCommander.
Argument Type: String

Positional arguments
projectName, applicationName

Response
Returns an application element.

ec-perl
syntax:$<object>->createApplication(<projectName>, <applicationName>,
{<optionals>});

Example
$ec->createApplication("Default", "app1", {description => "aDescription"});

ectool
syntax: ectool createApplication <projectName> <applicationName> [optionals...]

164

API commands - Applications

Example
ectool createApplication default newApp --description aDescription
Back to Top

deleteApplication
Delete an application.
You must specify the projectName and the applicationName arguments.

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String
Name of the application that must be unique among all projects.
applicationName
Argument Type: String

Positional arguments
projectName, applicationName

Response
None or a status OK message.

ec-perl
syntax: $<object>->deleteApplication (<projectName>, <applicationName>);

Example
$ec->deleteApplication ("Default", "appToDelete");

ectool
syntax: ectool deleteApplication <projectName> <applicationName>

Example
ectool deleteApplication default appToDelete
Back to Top

getApplication
Finds an application by name.
You must specify the projectName and the applicationName arguments.

165

ElectricCommander

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String
Name of the application that must be unique among all projects.
applicationName
Argument Type: String
(Optional) The revision ID of the versioned object.
applicationEntityRevisionId
Argument type: UUID

Positional arguments
projectName, applicationName

Response
Retrieves the specified application element.

ec-perl
syntax: $<object>->getApplication(<projectName>, <applicationName>, {<optionals>});

Example
$ec->getApplication("Default", "newApp",
{applicationEntityRevisionId => "4fa765dd-73f1-11e3-b67e-b0a420524153"});

ectool
syntax: ectool getApplication <projectName> <applicationName> [optionals...]

Example
ectool getApplication default newApp
--applicationEntityRevisionId 4fa765dd-73f1-11e3-b67e-b0a420524153
Back to Top

getApplications
Retrieves all applications in a project.
You must specify the projectName argument.

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String

166

API commands - Applications

Arguments

Descriptions
(Optional) <Boolean flag - 0|1|true|false> If set to "true", the

includeEntityRevisions

search results include the revisions of application.


Argument type: Boolean

Positional arguments
projectName

Response
Retrieves zero or more application elements.

ec-perl
syntax: $<object>->getApplications(<projectName> , {<optionals>});

Example
$ec->getApplications("Default");

ectool
syntax: ectool getApplications <projectName> [optionals...]

Example
ectool getApplications default
Back to Top

modifyApplication
Modifies an existing application.
You must specify the projectName and the applicationName arguments.

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String
Name of the application that must be unique among all projects.
applicationName
Argument Type: String

167

ElectricCommander

Arguments

Descriptions
Comment text describing this object; not interpreted at all by

description

ElectricCommander.
Argument Type: String
New name for an existing object that is being renamed.

newName
Argument Type: String

Positional arguments
projectName, applicationName

Response
Retrieves an updated application element.

ec-perl
syntax:$<object>->modifyApplication(<projectName>, <applicationName>,
{<optionals>});

Example
$ec->modifyApplication("Default", "app1", {newName=> "newAppName",
description => "exampleText"});

ectool
syntax:ectool modifyApplication <projectName> <applicationName> [optionals...]

Example
ectool modifyApplication default newApp --newName modApp
--description exampleText
Back to Top

168

API commands - Application Tier

API commands - Application Tier


createApplicationTier
deleteApplicationTier
getApplicationTier
getApplicationTiers on page 172
getApplicationTiersinComponent
modifyApplicationTier

createApplicationTier
Creates a new application tier in the application.
You must specify the projectName, applicationName, and applicationTierName arguments.

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String
Name of the application that must be unique among all projects.
applicationName
Argument Type: String
Name of the tier that must be unique within the application.
applicationTierName
Argument Type: String
Comment text describing this object that is not interpreted at all by
description

ElectricCommander.
Argument Type: String

Positional arguments
projectName , applicationName, applicationTierName

Response
Returns an application tier element.

ec-perl
syntax:$<object>->createApplicationTier(<projectName>, <applicationName>,
<applicationTierName>, {<optionals>});

169

ElectricCommander

Example
$ec->createApplicationTier("Default", "app1", "appTier2",
{description => "example_text"});

ectool
syntax: ectool createApplicationTier <projectName> <applicationName>
<applicationTierName> [optionals...]

Example
ectool createApplicationTier default newApp appTier1
--description example_text
Back to Top

deleteApplicationTier
Deletes a tier from an application.
You must specify the projectName, applicationName, and applicationTierName arguments.

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String
Name of the application that must be unique among all projects.
applicationName
Argument Type: String
Name of the tier that must be unique within the application.
applicationTierName
Argument Type: String

Positional arguments
projectName , applicationName, applicationTierName

Response
None or a status OK message.

ec-perl
syntax: $<object>->deleteApplicationTier(<projectName>, <applicationName>,
<applicationTierName>);

Example
$ec->deleteApplicationTier("Default", "app1", "appTierToDelete");

170

API commands - Application Tier

ectool
syntax: ectool deleteApplicationTier <projectName> <applicationName>
<applicationTierName>

Example
ectool deleteApplicationTier default newApp appTierToDelete
Back to Top

getApplicationTier
Finds an application tier by name.
You must specify the projectName, applicationName, and applicationTierName arguments.

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String
Name of the application that must be unique among all projects.
applicationName
Argument Type: String
Name of the tier that must be unique within the application.
applicationTierName
Argument Type: String
(Optional) The revision ID of the versioned object.
applicationEntityRevisionId
Argument type: UUID

Positional arguments
projectName , applicationName, applicationTierName

Response
Retrieves an application tier element.

ec-perl
syntax: $<object>->getApplicationTier(<projectName>, <applicationName>,
<applicationTierName>, {<optionals>});

Example
$ec->getApplicationTier("Default", "app1", "appTier2",
{applicationEntityRevisionId => "4fa765dd-73f1-11e3-b67e-b0a420524153"});

171

ElectricCommander

ectool
syntax: ectool getApplicationTier <projectName> <applicationName>
<applicationTierName> [optionals...]

Example
ectool getApplicationTier default newApp appTier1
--applicationEntityRevisionId 4fa765dd-73f1-11e3-b67e-b0a420524153
Back to Top

getApplicationTiers
Retrieves all application tiers in an application.
You must specify the projectName and applicationName arguments.

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String
Name of the application that must be unique among all projects.
applicationName
Argument Type: String
The revision ID of the versioned object.
applicationEntityRevisionId
Argument type: UUID

Positional arguments
projectName, applicationName

Response
Retrieves zero or more application tier elements.

ec-perl
syntax: $<object>->getApplicationTiers(<projectName>, <applicationName>,
{<optionals>});

Example
$ec->getApplicationTiers("Default",
"app1" {applicationEntityRevisionId => "4fa765dd-73f1-11e3-b67e-b0a420524153"});

ectool
syntax:ectool getApplicationTiers <projectName> <applicationName> [optionals...]

172

API commands - Application Tier

Example
ectool getApplicationTiers default newApp
--applicationEntityRevisionId 4fa765dd-73f1-11e3-b67e-b0a420524153
Back to Top

getApplicationTiersInComponent
Retrieves all application tiers that are used by the given component.
You must specify the projectName and the componentName arguments.

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String
Name of the component.
componentName
Argument Type: String
Name of an application to which this component is scoped.
applicationName
Argument Type: String
The revision ID of the versioned object.
applicationEntityRevisionId
Argument type: UUID

Positional arguments
projectName, componentName

Response
Retrieves zero or more application tier elements used by the specified component.

ec-perl
syntax:$<object>->getApplicationTiersInComponent(<projectName>, <componentName>,
{<optionals>});

Example
$ec->getApplicationTiersInComponent("default", "newComponent");

ectool
syntax:ectool getApplicationTiersInComponent <projectName> <componentName>
[optionals...]

173

ElectricCommander

Example
ectool getApplicationTiersInComponent default newComponent
Back to Top

modifyApplicationTier
Modifies an existing tier in the application.
You must specify the projectName, applicationName, and applicationTierName arguments.

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String
Name of the application that must be unique among all projects.
applicationName
Argument Type: String
Name of the tier that must be unique within the application.
applicationTierName
Argument Type: String
Comment text describing this object, which is not interpreted by
description

ElectricCommander.
Argument Type: String
New name for an existing object that is being renamed.

newName
Argument Type: String

Positional arguments
projectName, applicationName, applicationTierName

Response
Retrieves an updated application tier element.

ec-perl
syntax:$<object>->modifyApplicationTier(<projectName>, <applicationName>,
<applicationTierName>, {<optionals>});

Example
$ec->modifyApplicationTier("Default", "app1", "appTier2",
{newName=> "appTierB", description=> "newText"});

174

API commands - Application Tier

ectool
syntax:ectool modifyApplicationTier <projectName> <applicationName>
<applicationTierName> [optionals...]

Example
ectool modifyApplicationTier default newApp appTier1
--description new_exampleText --newName appTierA
Back to Top

175

ElectricCommander

API commands - Artifact Management


addDependentsToArtifactVersion

getArtifactVersions

cleanupArtifactCache

getManifest

cleanupRepository

getRepositories

createArtifact

getRepository

createArtifactVersion on page 181

modifyArtifact

createRepository

modifyArtifactVersion

deleteArtifact

modifyRepository

deleteArtifactVersion

moveRepository

deleteRepository

publishArtifactVersion

findArtifactVersions

removeDependentsFromArtifactVersion

getArtifact

resolveRoute on page 206


retrieveArtifactVersions

getArtifacts
getArtifactVersion

addDependentsToArtifactVersion
Adds an artifact version query to an existing artifact. Dependent artifact versions are retrieved when the parent
artifact version is retrieved.
You must specify an artifactVersionName.

Arguments

Descriptions
The name of the artifact version.
An artifact version name is interpreted by the server as the
artifactVersionName attribute for the artifactVersion in

artifactVersionName

question. This name is parsed and interpreted as


"groupId:artifactKey:version" and the object is searched
either way you specify its name. The Commander server interprets
the name form correctly.
Argument type:String

176

API commands - Artifact Management

Arguments

Descriptions
One or more artifact version queries. The most current match of
each query is retrieved when the primary artifact is retrieved.
Dependent artifact version query strings are in this form:
<groupId>:<artifactKey>:<versionRange>

dependentArtifactVersions

(versionRange is optional).
The version range syntax is standard number interval notation. ()
marks exclusive ranges and [] marks inclusive ranges.
Argument type:Collection

Positional arguments
artifactVersionName

Response
None or status OK message.

ec-perl
syntax: $cmdr->addDependentsToArtifactVersion (<artifactVersionName>,
{<optionals>});

Example
# Add a dependency on cmdr:SDK:1.2.0 and the most current version of core:infra tha
t
# is greater than or equal to 2.1.0.
$cmdr->addDependentsToArtifactVersion ({artifactVersionName => "myGroup:myAKey:1.0.
0-55",
dependentArtifactVersions => ["cmdr:SDK:1.2.0", "core:infra:[2.1.0,]"]});

ectool
syntax: ectool addDependentsToArtifactVersion <artifactVersionName>...

Example
ectool addDependentsToArtifactVersion --artifactVersionName "myGroup:myAKey:1.0.0-5
5",
--dependentArtifactVersions "cmdr:SDK:1.2.0" "core:infra:[2.1.0,]"
Back to Top

cleanupArtifactCache
Deletes stale artifact versions from an artifact cache. A "stale artifact version" is one whose metadata was
previously deleted from the Commander server.

177

ElectricCommander

Note: If you are not logged in as "admin", you cannot use this command. However, using the force option
overrides admin login privileges.
You must specify a cacheDirectory.

Arguments

Descriptions
The directory where stale artifact versions are stored.

cacheDirectory
Argument type:String
<Boolean flag - 0|1|true|false> If set to "true", this option can
be used so you can cleanup the artifact cache if you are not
force

logged in as "admin".
Argument type:Boolean

Positional arguments
cacheDirectory

Response
Returns a list of directories that were deleted.

ec-perl
syntax: $cmdr->cleanupArtifactCache(<cacheDirectory>);

Example
$cmdr->cleanupArtifactCache("/var/artifact-cache");

ectool
syntax: ectool cleanupArtifactCache <cacheDirectory>

Example
ectool cleanupArtifactCache "/var/artifact-cache"
Back to Top

cleanupRepository
Deletes stale artifact versions from the repository backing-store. A "stale artifact version" is one whose metadata
was previously deleted from the Commander server.
Note: If you are not logged in as "admin", you cannot use this command. However, using the force option
overrides
admin login privileges.
You must specify a backingStoreDirectory.

178

API commands - Artifact Management

Arguments

Descriptions
The repository directory where artifact versions are stored.

backingStoreDirectory
Argument type:String
<Boolean flag - 0|1|true|false> If set to "true", this option can
be used so you can cleanup the repository even if the g/a/v s in the
directory specified do not match up with any artifacts reported by
force

the server. By default, this is false, and helps users avoid deleting
arbitrary directory trees if they did not specify the repository
backingstore properly.
Argument type:Boolean

Positional arguments
backingStoreDirectory

Response
Returns a list of directories that were deleted.

ec-perl
syntax: $cmdr->cleanupRepository(<backingStoreDirectory>);

Example
use strict;
use ElectricCommander;
my $cmdr = ElectricCommander->new({debug => 1});
$cmdr->login("admin", "changeme");
$cmdr->cleanupRepository("/var/repository-data");

ectool
syntax: ectool cleanupRepository <backingStoreDirectory>

Example
ectool cleanupRepository "/var/repository-data"
Back to Top

createArtifact
Creates a new artifact.
You must specify groupId and artifactKey.

179

ElectricCommander

Arguments

Descriptions
A user-generated group name for this artifact. This field is limited to
alphanumeric characters, spaces, spaces, underscores, hyphens,

groupId

and periods.
Argument type:String
User-specified identifier for this artifact. This field is limited to
alphanumeric characters, spaces, underscores, hyphens, and

artifactKey

periods.
Argument type:String
A template for the names of artifact versions published to this
artifact. This option overrides the value set in the server settings for
"artifact name template.". The global setting can be manipulated in

artifactVersionNameTemplate

the Server Settings page (Administration > Server, select the


Settings link).
Argument type:String
A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the

description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type:String

Positional arguments
groupId, artifactKey

Response
Returns an artifact element.

ec-perl
syntax: $cmdr->createArtifact(<groupId>, <artifactKey>, {<optionals>});

Example
$cmdr->createArtifact("thirdPartyTools", "SDK", {description => "3rd party tools SD
K"});

ectool
syntax: ectool createArtifact <groupId> <artifactKey> ...

180

API commands - Artifact Management

Example
ectool createArtifact thirdPartyTools SDK --description "3rd party tools SDK"
Back to Top

createArtifactVersion
Creates a new artifact version.
You must specify version.

Arguments

Descriptions
The version component of the GAV

version

(groupId/artifactVersionId/version) coordinates.
Argument type:String
User-specified identifier for this artifact. This field is limited to
alphanumeric characters, spaces, underscores, hyphens, and

artifactKey

periods.
Argument type:String
Name of the artifact.

artifactName
Argument type:String
The set of artifact versions on which this artifactVersion
dependentArtifactVersions

depends.
Argument type:Collection
A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the

description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type:String

181

ElectricCommander

Arguments

Descriptions
The groupId component of the GAV
(groupId/artifactVersionId/version) coordinates.

groupId

This field is limited to alphanumeric characters, spaces, spaces,


underscores, hyphens, and periods.
Argument type:String
The unique identifier for the job step that is used to make a project

jobStepId

association.
Argument type:UUID
The name of the artifact repository.

repositoryName
Argument type:String

Positional arguments
version

Response
Returns an artifact element.

ec-perl
syntax:$cmdr->createArtifactVersion(<groupId>, <artifactKey>, {<optionals>});

Example
$cmdr->createArtifactVersion("thirdPartyTools", "SDK", {description => "3rd party t
ools SDK"});

ectool
syntax: ectool createArtifactVersion <groupId> <artifactKey> ...

Example
ectool createArtifactVersion thirdPartyTools SDK --description "3rd party tools SD
K"
Back to Top

createRepository
Creates a repository for one or more artifacts.
You must specify a repositoryName.

182

API commands - Artifact Management

Arguments

Descriptions
The name of the artifact repository.

repositoryName
Argument type:String
A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the
description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type:String
<Boolean flag -0|1|true|false> Determines whether the

repositoryDisabled

repository is disabled. Default is "false".


Argument type:Boolean
The URL to use to communicate with the repository server.

url
Argument type:String
The name of the zone where this repository resides.
zoneName
Argument type:String

Positional arguments
repositoryName

Response
Returns a repository element.

ec-perl
syntax: $cmdr->createRepository(<repositoryName>, {<optionals>});

Example
$cmdr->createRepository("myRepos", {repositoryDisabled => "true", url =>
"https://test.ecloud.com:8200"});

ectool
syntax: ectool createRepository <repositoryName> ...

Example
ectool createRepository myRepos --repositoryDisabled "true" --url
"https://test.ecloud.com:8200"
Back to Top

183

ElectricCommander

deleteArtifact
Deletes an existing artifact element and all artifact versions.
You must specify an artifactName.

Arguments

Descriptions
The name of the artifact to delete.

artifactName
Argument type:String

Positional arguments
artifactName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deleteArtifact(<artifactName>);

Example
$cmdr->deleteArtifact("commander:SDK");

ectool
syntax: ectool deleteArtifact <artifactName>

Example
ectool deleteArtifact "commander:SDK"
Back to Top

deleteArtifactVersion
Deletes artifact version metadata from the Commander database.
(This API call does not delete or remove artifacts stored on the repository machine.)
You must specify an artifactVersionName.

184

API commands - Artifact Management

Arguments

Descriptions
The name of the artifact version.
Note: An artifact version name is interpreted by the server as
the artifactVersionName attribute for the
artifactVersion in question. This name is parsed and

artifactVersionName

interpreted as "groupId:artifactKey:version"and the


object is searched either way you specify its name. The
Commander server interprets the name form correctly.
Argument type:String

Positional arguments
artifactVersionName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deleteArtifactVersion(<artifactVersionName>);

Example
$cmdr->deleteArtifactVersion("myGroup:myKey:1.0.0-55");

ectool
syntax: ectool deleteArtifactVersion <artifactVersionName>

Example
ectool deleteArtifactVersion "myGroup:myKey:1.00.0-55"
Back to Top

deleteRepository
Deletes artifact repository metadata from the Commander database.
(This API call does not delete or remove artifacts stored on the repository machine.)
You must enter a repositoryName.

Arguments

Descriptions
The name of the artifact repository to delete.

repositoryName
Argument type:String

185

ElectricCommander

Positional arguments
repositoryName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deleteRepository(<repositoryName>);

Example
$cmdr->deleteRepository ("cmdrReposOne");

ectool
syntax: ectool deleteRepository <repositoryName>

Example
ectool deleteRepository cmdrReposOne
Back to Top

findArtifactVersions
This command returns the most current artifact version that matches the filter criteria and its dependent artifact
versions.
This API implicitly searches for artifact versions in the "available" state, and if run in a job step, registers
the step as a retriever for the returned artifact versions.
Because of the complexity of specifying filter criteria, this API is not supported by ectool. However, all
of its capabilities are supported through the Perl API.
Note: The retrieveArtifactVersions API uses this API to find the appropriate artifact version in the
Commander server
and then retrieves the artifact version from a repository. You may prefer to use the
retrieveArtifactVersions API
instead of this API because while this API returns slightly different information, it also has the side-effect of
"retriever
step registration" mentioned above.
You must specify an artifactName or a groupId with an artifactKey.

186

API commands - Artifact Management

Arguments

Descriptions
User-specified identifier for this artifact. This field is limited to
alphanumeric characters, spaces, underscores, hyphens, and

artifactKey

periods.
Argument type:String
The name of an artifact.

artifactName
Argument type:String
The name of an artifact version.
artifactVersionName
Argument type:String

187

ElectricCommander

Arguments

Descriptions
A list of zero or more filter criteria definitions used to define objects
to find.
Each element of the filter list is a hash reference containing one
filter criterion. You may specify several filter criteria, in which case
an object must meet all filter criteria to be included in the result.
See the code example below for instructions on forming the list
and passing it to the ElectricCommander Perl API.
Two types of filters:
"property filters" - used to select objects based on the value
of the object's intrinsic or custom property
"boolean filters" ("and", "or", "not") - used to combine one or
more filters using boolean logic.
Each "property filter" consists of a property name to test and an
operator to use for comparison. The property can be either an
intrinsic property defined by Commander or a custom property
added by the user. Each operator takes zero, one, or two operands
to compare against the desired property.

filters
Property filter operators are:
between (2 operands)
contains (1)
equals (1)
greaterOrEqual (1)
greaterThan (1)
in (1)
lessOrEqual (1)
lessThan (1)
like (1)
notEqual (1)
notLike (1)
isNotNull (0)
isNull (0)
A boolean filter is a boolean operator and an array of one or more
filters that are operands. Each operand can be either a property
filter or a boolean filter.
Boolean operators are:

188

API commands - Artifact Management

Arguments

Descriptions
not (1 operand)
and (2 or more operands)
or (2 or more operands)
Argument type: Collection
A user-generated group name for this artifact. This field may
consist of alphanumeric characters, spaces, underscores,

groupId

hyphens, and periods.


Argument type:String
Options are:
l

0/false dependent artifacts are not retrieved.

1/true dependent artifacts are retrieved.

includeDependents

Argument type:Boolean
The unique identifier for the job step that is making the request.
This job step is marked as a retriever for the matching artifact
jobStepId

versions.
Argument type:UUID
The range of versions to search. Version range syntax is standard
number interval notation. () marks exclusive ranges and [] marks

versionRange

inclusive ranges.
Argument type:String

Positional arguments
None

Response
This command returns zero or more artifactVersion elements. In addition, this API returns a
searchDetails element with
text describing how the server evaluated candidate artifact versions and ultimately decided to return the
result
artifactVersion and its dependent(s).

ec-perl
syntax: $cmdr->findArtifactVersions({<optionals>});

189

ElectricCommander

Example 1
# Find the most current core:infra artifact version whose version is 1.x.x.
$cmdr->findArtifactVersions({groupId => "core",
artifactKey => "infra",
versionRange => "[1.0, 2.0)"});
# Or alternatively ...
$cmdr->findArtifactVersions({artifactName => "core:infra",
versionRange => "[1.0,2.0)"});

Example 2
# Find the most current core:infra artifact version with QA approval level 3 or abo
ve.
$cmdr->findArtifactVersions({groupId => "core",
artifactKey => "infra",
filter => {propertyName => "qaLevel",
operator => "greaterOrEqual",
operand1 => "3"}});

ectool
Not supported.
Back to Top

getArtifact
Retrieves an artifact by name.
You must specify an artifactName.

Arguments

Descriptions
The name of the artifact.

artifactName
Argument type:String

Positional arguments
artifactName

Response
Retrieves an artifact element.

ec-perl
syntax: $cmdr->getArtifact (<artifactName>);

Example
$cmdr-> getArtifact("myGroup:myKey");

190

API commands - Artifact Management

ectool
syntax: ectool getArtifact <artifactName>

Example
ectool getArtifact "myGroup:myKey"
Back to Top

getArtifacts
Retrieves all artifacts in the system.
You must specify search filter criteria to find the artifacts you need.

Arguments

Descriptions

None

Positional arguments
None

Response
Zero or more artifact elements.

ec-perl
syntax: $cmdr->getArtifacts ();

Example
$cmdr->getArtifacts ();

ectool
syntax: ectool getArtifacts

Example
ectool getArtifacts
Back to Top

getArtifactVersion
Retrieves an artifact version by its name.
You must specify an artifactVersionName.

191

ElectricCommander

Arguments

Descriptions
The name of the artifact version to retrieve.
Note: An artifact version name is interpreted by the server as
the artifactVersionName attribute for the
artifactVersion in question. This name is parsed and

artifactVersionName

interpreted as "groupId:artifactKey:version" and the


object is searched either way you specify its name. The
ElectricCommander server interprets either name form
correctly.
Argument type:String
<Boolean flag - 0|1|true|false> If set to 1, this argument
includes jobId and jobName in returned information. A retriever

includeRetrieverJobs

job is any job that has retrieved the artifact version.


Argument type:Boolean
<Boolean flag - 0|1|true|false> If set to 1, this argument
includes jobId, jobName, and jobStepId information. A retriever
job is any job that has retrieved the artifact version. Because there

includeRetrieverJobSteps

is no bound to how many job steps may retrieve a given artifact


version, the server limits the response to the most recent 200 job
steps.
Argument type:Boolean
If one of the includeRetriever* options are specified, return at
most "this many" of the most recent retrievers. Without this option,

maxRetrievers

the Commander server will return all retrievers.


Argument type:String

Positional arguments
artifactVersionName

Response
One artifactVersion element. If includeRetrieverJobs or includeRetrieverJobSteps is set,
the artifactVersion element will contain zero or more retriever child elements, each containing
retriever information for one job or job step.

ec-perl
syntax: $cmdr->getArtifactVersion(<artifactVersionName>, {<optionals>});

192

API commands - Artifact Management

Example
$cmdr->getArtifactVersion("myGroup:myKey:1.0.0-55", {includeRetrieverJobs => "tru
e"});

ectool
syntax: ectool getArtifactVersion <artifactVersionName> ...

Example
ectool getArtifactVersion myGroup:myKey:1.0.0-55 -includeRetrieverJobs "true"
Back to Top

getArtifactVersions
Retrieves all artifact versions in the system, filtered by artifact name, retriever job ID, and/or retriever job step ID.
You must specify search filter criteria to find the artifact versions you need.
If you do not provide any options, all artifact versions in the system are returned.

Arguments

Descriptions
The name of the artifact for the versions to retrieve.

artifactName
Argument type:String
The job ID that retrieved an artifact.
retrieverJobId
Argument type:String
The job step ID that retrieved an artifact.
retrieverJobStepId
Argument type:UUID

Positional arguments
None

Response
Zero or more artifactVersion elements.

ec-perl
syntax: $cmdr->getArtifactVersions({<optionals>});

Example
$cmdr->getArtifactVersions({artifactName => "myGroup:myKey"});

193

ElectricCommander

ectool
syntax: ectool getArtifactVersions ...

Example
ectool getArtifactVersions --artifactName "myGroup:myKey"
Back to Top

getManifest
Retrieves the manifest for a specified artifact version. The manifest includes a list of files and directories
in the artifact version and its checksum file.
You must specify the artifactVersionName.

Arguments

Descriptions
The name of the artifact version whose manifest you want to

artifactVersionName

retrieve.
Argument type:String

Positional arguments
None

Response
Manifest information for the specified artifact version: returns an XML stream containing any number of file
elements, including the file name, file size, and "sha1" hashes for every file in the artifactVersionName.

ec-perl
syntax: $cmdr->getManifest(<artifactVersionName>);

Example
my ($manifest,$diagnostics) = $cmdr->getManifest("myGroup:myKey:1.0.0-55");

ectool
syntax: ectool getManifest <artifactVersionName>

Example
ectool getManifest myGroup:myKey:1.0.0-55

getRepositories
Retrieves all artifact repository objects known to the Commander server.

194

API commands - Artifact Management

Arguments

Descriptions

None

Positional arguments
None

Response
Zero or more repository elements.

ec-perl
syntax: $cmdr->getRepositories ();

Example
$cmdr->getRepositories ();

ectool
syntax: ectool getRepositories

Example
ectool getRepositories
Back to Top

getRepository
Retrieves an artifact repository by its name.
You must specify a repositoryName.

Arguments

Descriptions
The name of the artifact repository to retrieve.

repositoryName
Argument type:String

Positional arguments
repositoryName

Response
One repository element.

ec-perl
syntax: $cmdr->getRepository(<repositoryName>);

195

ElectricCommander

Example
$cmdr->getRepository("myRepository");

ectool
syntax: ectool getRepository <repositoryName>

Example
ectool getRepository myRepository
Back to Top

modifyArtifact
Modifies an existing artifact.
You must specify an artifactName.

Arguments

Descriptions
The name of the artifact to modify.

artifactName
Argument type:String
A template for the names of artifact versions published to this
artifact. This option overrides the value set in the server settings for
"artifact name template." The global setting can be manipulated in
artifactVersionNameTemplate

the Server Settings page (Administration > Server, select the


Settings link).
Argument type:String
A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the

description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type:String

Positional arguments
artifactName

Response
None or a status OK message.

196

API commands - Artifact Management

ec-perl
syntax: $cmdr->modifyArtifact(<artifactName>, {<optionals>});

Example
$cmdr->modifyArtifact("thirdParty-SDK", {description => "contains artifact versions
for SDK"});

ectool
syntax: ectool modifyArtifact <artifactName> ...

Example
ectool modifyArtifact thirdParty-SDK --description "contains artifact versions for
SDK"
Back to Top

modifyArtifactVersion
Modifies an existing artifact version.
You must specify an artifactVersionName.

Arguments

Descriptions
The name of the artifact version to modify.
Note: An artifact version name is interpreted by the server as
the artifactVersionName attribute for the
artifactVersion in question. This name is parsed and

artifactVersionName

interpreted as "groupId:artifactKey:version" and the


object is searched either way you specify its name. The
ElectricCommander server interprets either name form
correctly.
Argument type:String
The state of the artifact version.

artifactVersionState

<publishing|available|unavailable>.
Argument type:ArtifactVersionState

197

ElectricCommander

Arguments

Descriptions
One or more artifact version queries. The most current match for
each query is retrieved when the primary artifact is retrieved.
Dependent artifact version query strings are in this form:
<groupId>:<artifactKey>:<versionRange>

dependentArtifactVersions

(version range is optional).


Note: The absence of this argument does not clear or modify
the dependent artifact version list for this artifact version.
Argument type:Collection
A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the

description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type:String
New name for this artifact version.

newName
Argument type:String
<Boolean flag - 0|1|true|false> Defaults to "false."
Removes all dependent artifacts from this artifact version.
removeAllDependentArtifactVe
rsions

Subsequent "retrieves" will no longer retrieve dependent artifacts


for this artifact version.
Argument type:Boolean
The name of the artifact repository.

repositoryName
Argument type:String

Positional arguments
artifactVersionName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->modifyArtifactVersion(<artifactVersionName>, {<optionals>});

198

API commands - Artifact Management

Example
$cmdr->modifyArtifactVersion("myGroup:myKey:1.0.1-42375", {artifactVersionState =>
"unavailable"});

ectool
syntax: ectool modifyArtifactVersion <artifactVersionName> ...

Example
ectool modifyArtifactVersion "myGroup:myKey:1.0.1-57385" --artifactVersionState una
vailable
Back to Top

modifyRepository
Modifies an existing artifact repository.
You must specify a repositoryName.

Arguments

Descriptions
The name of the artifact repository.

repositoryName
Argument type:String
A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the
description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type:String
New name of the repository.

newName
Argument type:String
<Boolean flag - 0|1|true|false> Marks the repository as
enabled or disabled. If you do not enter this option, the state of the
repositoryDisabled

repository is unchanged.
Argument type:Boolean
The URL used to communicate with the artifact repository.

url
Argument type:String

199

ElectricCommander

Arguments

Descriptions
The name of the zone where this repository resides.

zoneName
Argument type:String

Positional arguments
repositoryName

Response
Returns a modified repository element.

ec-perl
syntax: $cmdr->modifyRepository (<repositoryName>, {<optionals>});

Example
$cmdr->modifyRepository("myNewRepos", {newName => "cmdrRepository"});

ectool
syntax: ectool modifyRepository <repositoryName> ...

Example
ectool modifyRepository myNewRepos --newName cmdrRepository
Back to Top

moveRepository
Moves an artifact repository in front of another, specified repository or to the end of the list.
This API does not move artifact version data to another repository server machine. Only the repository
order in which Commander searches to retrieve an artifact version is changed.
You must specify a repositoryName.

Arguments

Descriptions
The name of the artifact repository you need to move.

repositoryName
Argument type:String
Moves this repository (repositoryName) to a place before the
name specified by this option. If omitted repositoryName is
beforeRepositoryName

moved to the end.


Argument type:String

200

API commands - Artifact Management

Positional arguments
repositoryName

Response
Returns a modified repository element or an error if the repository does not exist.

ec-perl
syntax: $cmdr->moveRepository(<repositoryName>, {<optionals>});

Example
$cmdr->moveRepository(reposThree, {beforeRepositoryName => "reposOne"});

ectool
syntax: ectool moveRepository <repositoryName> ...

Example
ectool moveRepository reposThree --beforeRepositoryName reposOne
Back to Top

publishArtifactVersion
Publishes an artifact version to an artifact repository.
Note: This API wraps the "publish" function in the ElectricCommander::ArtifactManagement
Perl module and hides some additional functionality implemented in that module.
You must specify an artifactName or a groupId with an artifactKey.

Arguments

Descriptions
The name of an artifact.

artifactName
Argument type:String
User-specified identifier for this artifact. This field is limited to
alphanumeric characters, spaces, underscores, hyphens, and
artifactKey

periods.
Argument type:String

201

ElectricCommander

Arguments

Descriptions
<Boolean flag - 0|1|true|false> Default is "true".
Controls whether or not the artifact version is compressed during
transport, which improves performance for cases where artifact
version files are compressible, saving network bandwidth. Where

compress

artifact version files are not compressible, performance is reduced.


Another consideration is that the artifact version is stored
compressed/uncompressed based on this setting in the repository
backing-store.
Argument type:Boolean
One or more artifact version queries. The most current match of
each query is retrieved when the primary artifact is retrieved.
Dependent artifact version query strings are in this form:
<groupId>:<artifactKey>:<versionRange> (versionRange

dependentArtifactVersions

is optional).
The version range syntax is standard number interval notation.
() marks exclusive ranges and [] marks inclusive ranges.
Argument type:Collection
A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the

description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type:String
Semi-colon delimited list of file-path patterns indicating which
files/directories under "fromDirectory" to exclude when
publishing an artifact version. Defaults to "empty," which means no

excludePatterns

files are excluded. See more information on "pattern syntax"


below.
Argument type:Collection

202

API commands - Artifact Management

Arguments

Descriptions
<Boolean flag - 0|1|true|false> Default is "true".
If true, follow symbolic links and record the target file contents with

followSymlinks

the symbolic link name in the artifact. If false, record the symbolic
link as a symbolic link. Following symbolic links causes the publish
API to remain compatible with previous releases.
Argument type:Boolean
The directory containing files to publish as the artifact version. A
subset of files can be published based on includePatterns and

fromDirectory

excludePatterns.
Argument type:String
A user-generated group name for this artifact. This field is limited to
alphanumeric characters, spaces, underscores, hyphens, and

groupId

periods.
Argument type:String
Semi-colon delimited list of file-path patterns indicating which
files/directories under "fromDirectory" to publish in the artifact
version. Defaults to "empty," which means all files will be included.

includePatterns

Conversely, if only two files are "included," no other files except


those two will be included. See more information on "pattern
syntax" below.
Argument type:Collection
The name of the artifact repository where you want to publish.

repositoryName
Argument type:String
Unique identifier for the artifact version in the form:
major.minor.patch-qualifier-buildNumber
major, minor, patch, and buildNumber are integers and
qualifier can contain any character except the following:
\:<>|?*/
version

If a version argument is provided, but does not follow the above


format, the version will be considered 0.0.0-<user-specifiedversion-arg>-0 implicitly.
See examples below.
Argument type:String

203

ElectricCommander

Version number examples

Interpretation
User Input
Major.Minor.Patch

Qualifier

Build Number

1.0.0

1.0

1.0.0

1.0-frank

1.0.0

1.0-36

1.0.0

1.0-frank-36

1.0.0

frank

0
36

frank

36

Pattern syntax
Include / exclude patterns are expressed as relative paths under the fromDirectory.
Pattern syntax and behavior is the same as Ant and uses the following wildcard specifiers:
? - matches a single character
* - matches any number of characters, but only at a single directory level
** - matches any number of directory levels
Examples:
Use *.txt to match any .txt file in the top-level directory.
Use */*.txt to match any .txt file in any child directory.
Use **/*.txt to match any .txt file at any level.

Positional arguments
None

Response
One artifactVersion element.

ec-perl
syntax: $cmdr->publishArtifactVersion({<optionals>});

Example
# Add version 1.0.0-55 for artifact myGroup:myKey with a dependency on cmdr:SDK:1.2
.0,
# and the most current version of core:infra that is greater than or equal to

204

API commands - Artifact Management

2.1.0.
# Note: In the Perl API, the argument must be specified as singular even though it
# can take multiple values.
$cmdr->publishArtifactVersion({artifactName => "myGroup:myKey",
version => "1.0.0-55",
dependentArtifactVersion => ["cmdr:SDK:1.2.0", "core:infra:{2.
1,]"]});

ectool
syntax: ectool publishArtifactVersion ...

Example
ectool publishArtifactVersion --artifactName "myGroup:myKey" --version "1.0.0-55"
--dependentArtifactVersion "cmdr:SDK:1.2.0":"core:infra"
Back to Top

removeDependentsFromArtifactVersion
Removes a list of dependent artifact versions from an existing artifact version.
You must specify the artifactVersionName.

Arguments

Descriptions
The name of the artifact version from which you want to remove
dependents.
Note: An artifact version name is interpreted by the server as the
artifactVersionName attribute for the artifactVersion in

artifactVersionName

question. This name is parsed and interpreted as


"groupId:artifactKey:version" and the object is searched
either way you specify its name--the Commander server interprets
either name form correctly.
Argument type:String
One or more artifact version queries. The most current match of
each query is retrieved when the primary artifact is retrieved.
Dependent artifact version query strings are in this form:
<groupId>:<artifactKey>:<versionRange>

dependentArtifactVersions

(versionRange is optional).
The version range syntax is standard number interval notation.
() marks exclusive ranges and [] marks inclusive ranges.
Argument type:Collection

205

ElectricCommander

Positional arguments
artifactVersionName

Response
None or status OK message.

ec-perl
syntax: $cmdr->removeDependentsFromArtifactVersion(<artifactVersionName>,
{<optionals>});

Example
# Note: In the Perl API, the argument must be specified as singular
# even though it can take multiple values.
$cmdr->removeDependentsFromArtifactVersion(myGroup:myKey:1.0.0-55,
{dependentArtifactVersion => ["cmdr:onlineHelp:1.0.0"});

ectool
syntax: ectool removeDependentsFromArtifactVersion <artifactVersionName> ...

Example
ectool removeDependentsFromArtifactVersion myGroup:myKey:1.0.0-55
--dependentArtifactVersions "cmdr"onlineHelp:1.0.0"
Back to Top

resolveRoute
Resolves the network route to an artifact repository.

Arguments

Descriptions
Name of the artifact repository.

toRepositoryName
Argument type:String
Identifier of the agent requesting the route to a destination agent or
fromAgentId

artifact repository.
Argument type:Long
Name of the resource requesting the route to a destination agent

fromResourceName

or artifact repository.
Argument type:String

206

API commands - Artifact Management

Positional arguments
toRepositoryName

Response
None or a status OK message.

ec-perl
syntax:$cmdr->resolveRoute (<toRepositoryName>, {<optionals>});

Examples
$cmdr->resolveRoute("WebServer", {fromResourceName => "admin"});

ectool
syntax: ectool resolveRoute <toRepositoryName> [optionals...]

Example
ectool resolveRoute "WebServer" --fromResourceName "admin"
Back to Top

retrieveArtifactVersions
Retrieves the most recent artifact version, including its dependents, from an artifact repository.
Note: This API wraps the "retrieve" function in the ElectricCommander::ArtifactManagement
Perl module and hides some additional functionality implemented in that module.
You must specify search criteria options to locate the artifact versions you want to retrieve.

Arguments

Descriptions
User-specified identifier for this artifact. This field is limited to
alphanumeric characters, spaces, underscores, hyphens, and

artifactKey

periods.
Argument type:String
The name of the artifact.

artifactName
Argument type:String
The name of the artifact version.
artifactVersionName
Argument type:String

207

ElectricCommander

Arguments

Descriptions
The directory where the artifact version is stored.

cacheDirectory

Note: The artifact version files are stored in a subdirectory


under this cache directory.
Argument type:String

208

API commands - Artifact Management

Arguments

Descriptions
A list of zero or more filter criteria definitions used to define objects
to find.
Each element of the filter list is a hash reference containing one
filter criterion. You may specify several filter criteria, in which case
an object must meet all filter criteria to be included in the result.
See the code example below for instructions on forming the list
and passing it to the ElectricCommander Perl API.
Two types of filters:
"property filters" are used to select objects based on the value of
the object's intrinsic or custom property.
"boolean filters" ("and", "or", "not") are used to combine one or
more filters using boolean logic.
Each "property filter" consists of a property name to test and an
operator to use for comparison. The property can be either an
intrinsic property defined by Commander or a custom property
added by the user. Each operator takes zero, one, or two operands
to compare against the desired property.

filters
Property filter operators are:
between (2 operands)
contains (1)
equals (1)
greaterOrEqual (1)
greaterThan (1)
in (1)
lessOrEqual (1)
lessThan (1)
like (1)
notEqual (1)
notLike (1)
isNotNull (0)
isNull (0)
A boolean filter is a boolean operator and an array of one or more
filters that are operands. Each operand can be either a property

209

ElectricCommander

Arguments

Descriptions
filter or a boolean filter.
Boolean operators are:
not (1 operand)
and (2 or more operands)
or

(2 or more operands)

Argument type: Collection


A user-generated group name for this artifact. This field may
consist of alphanumeric characters, spaces, underscores,
groupId

hyphens, and periods.


Argument type:String
The published artifact version includes the artifact's dependents,
such as a list of one or more artifact versions consisting of a list of
possible values [(0 | 1| true | false)].
The values are:

includeDependents

0/false dependent artifacts are not retrieved.

1/true dependent artifacts are retrieved.

Argument type:Boolean

Options are:
l

true - deletes previous content in the directory and


replaces the content with your new version.

false - (existing behavior) if the directory does not exist,


one will be created and filled with the artifact's content. If
the directory exists, a new directory is created with a
unique name and the artifact contents is supplied there.

update - this is similar to a merge operationtwo artifact


versions can be moved into the same directory, but
individual files with the same name will be overwritten.

overwrite

Argument type:String

210

API commands - Artifact Management

Arguments

Descriptions
A space-separated list of artifact repository names. Retrieval is
attempted from each specified repository in a specified order until
it succeeds or all specified repositories have rejected the retrieval.
If not specified, and if this request is made in a job step context, a

repositoryNames

preferred list of repository names is obtained from the Resource


definition in the server. If that list is empty, the global repository list
is used.
Argument type:String
Used to retrieve an artifact version to a specific directory without
imposing the structure of a cache directory. Specify the full path to
the new directory.
l

If the artifact version is in a local cache directory. it will be


copied out of the cache.

If the artifact version is not in a cache directory, it will be


downloaded directly to the specified directory, without
putting it into a cache. toDirectory overrides
cacheDirectory for downloads.

toDirectory

Argument type:String
The range of versions to search. Version range syntax is standard
number interval notation. () marks exclusive ranges and [] marks
versionRange

inclusive ranges.
Argument type:String

Positional arguments
None

Response
Returns one or more artifactVersion elements.

ec-perl
syntax: $cmdr->retrieveArtifactVersions {<optionals>});

Examples
# Retrieve the most current core:infra artifact version whose version is 1.x.x.
$cmdr->retrieveArtifactVersions({groupId => "core",
artifactKey => "infra",
versionRange => "[1.0,2.0)"});
# Or alternatively...
$cmdr->retrieveArtifactVersions({artifactName => "core:infra",
versionRange => "[1.0,2.0)"});

211

ElectricCommander

ectool
syntax: ectool retrieveArtifactVersions ...

Example
ectool retrieveArtifactVersions --artifactName "core:infra" --versionRange "[1.0,2.
0)"
Note: The filter option does not perform as expected if using ectool. If you need the filter option,
write your retrieveArtifactVersions API call in ec-perl.

Back to Top

212

API commands - Component

API commands - Component


addComponentToApplicationTier on page 213
createComponent on page 214
deleteComponent on page 215
getComponent on page 216
getComponents on page 217
getComponentsinApplicationTier on page 218
modifyComponent on page 220
removeComponentFromApplicationTier on page 221

addComponentToApplicationTier
Adds the specified component to the specified application tier.
You must specify the projectName, applicationName, applicationTierName, and componentName
arguments.

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String
Name of the application that must be unique among all projects.
applicationName
Argument Type: String
Name of the tier that must be unique within the application.
applicationTierName
Argument Type: String
Name of the component.
componentName
Argument Type: String
Name of the project that contains the component.
componentProjectName
Argument Type: String

Positional arguments
projectName, applicationName, applicationTierName, componentName

Response
Returns the component and specified application tier elements.

213

ElectricCommander

ec-perl
Syntax:
$<object>->addComponentToApplicationTier(<projectName>, <applicationName>,
<applicationTierName>, <componentProjectName>, <componentName>,
{<optionals>});

Example:
$ec->addComponentToApplicationTier("default", "newApp", "appTier1",
"component1");

ectool
Syntax:
ectool addComponentToApplicationTier <projectName> <applicationName>
<applicationTierName> <componentName> [optionals...]

Example:
ectool addComponentToApplicationTier default newApp appTier1 VCScomponent
Back to Top

createComponent
Creates a new component for a project.
You must specify the projectName, applicationName, and pluginName arguments.

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String
Name of the component.
componentName
Argument Type: String
Name of the plugin.
pluginName
Argument Type: String
Name of the application to which this component is scoped.
applicationName
Argument Type: String
Name of the credential to attach to this component.
credentialName
Argument Type: String

214

API commands - Component

Arguments

Descriptions
Comment text describing this object. It is not interpreted by

description

ElectricCommander.
Argument Type: String

Positional arguments
projectName, applicationName, pluginName

Response
Returns a version control component element.

ec-perl
Syntax:
$<object>->createComponent(<projectName>, <componentName>, <pluginName>,
{<optionals>});

Example:
$ec->createComponent("default", "component1", "Publish Artifact Version",
{description => "New agent"});

ectool
Syntax:
ectool createComponent <projectName> <componentName> <pluginName>
[optionals...]

Example:
ectool createComponent default component1
--description "New agent"

"Publish Artifact Version"

Back to Top

deleteComponent
Deletes a component.
You must specify the projectName and componentName arguments.

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String

215

ElectricCommander

Arguments

Descriptions
Name of the component.

componentName
Argument Type: String
The name of an application to which this component is scoped.
applicationName
Argument Type: String

Positional arguments
projectName, componentName

Response
None or a status OK message.

ec-perl
Syntax:
$<object>->deleteComponent(<projectName>, <componentName>),
{<optionals>};
Example:
$ec->deleteComponent("default", "VCScomponent");

ectool
Syntax:
ectool deleteComponent <projectName> <componentName>
[optionals...]
Example:
ectool deleteComponent default VCScomponent
Back to Top

getComponent
Finds a component by name.
You must specify the projectName and componentName arguments.

216

API commands - Component

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String
Name of the component.
componentName
Argument Type: String
The revision ID of the versioned object.
applicationEntityRevisionId
Argument type: UUID
Name of an application to which this component is scoped.
applicationName
Argument Type: String

Positional arguments
projectName, componentName

Response
Retrieves the specified component element.

ec-perl
Syntax:
$<object>->getComponent(<projectName>, <componentName>, {<optionals>});

Example:
$ec->getComponent("default", "component1",
{applicationEntityRevisionId => "4fa765dd-73f1-11e3-b67e-b0a420524153"});

ectool
Syntax:
ectool getComponent <projectName> <componentName>
[optionals...]

Example:
ectool getComponent default VCScomponent
--applicationEntityRevisionId 4fa765dd-73f1-11e3-b67e-b0a420524153
Back to Top

getComponents
Retrieves all components in a project.

217

ElectricCommander

You must specify the projectName argument.

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String
The revision ID of the versioned object.
applicationEntityRevisionId
Argument type: UUID
Name of the application. You can search for components scoped
applicationName

to an application.
Argument Type: String

Positional arguments
projectName

Response
Retrieves zero or more component elements.

ec-perl
Syntax:
$<object>->getComponents(<projectName>, {<optionals>});

Example:
$ec->getComponents("default",
{applicationEntityRevisionId => "4fa765dd-73f1-11e3-b67e-b0a420524153"});

ectool
Syntax:
ectool getComponents <projectName> [optionals...]

Example:
ectool getComponents default
--applicationEntityRevisionId 4fa765dd-73f1-11e3-b67e-b0a420524153
Back to Top

getComponentsinApplicationTier
Returns the list of components in an application tier.
You must specify the projectName, applicationName, and applicationTierName arguments.

218

API commands - Component

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String
Name of the application that must be unique among all projects.
applicationName
Argument Type: String
Name of the tier that must be unique within the application.
applicationTierName
Argument Type: String
The revision ID of the versioned object.
applicationEntityRevisionId
Argument type: UUID
<Boolean flag - 0|1|true|false> If set to "true", the artifact name
includeArtifactDetail

and version are returned as part of component response.


Argument type: Boolean

Positional arguments
projectName, applicationName, applicationTierName

Response
Retrieves zero or more component elements in the specified application tier.

ec-perl
Syntax:
$<object>->getComponentsInApplicationTier(<projectName>, <applicationName>,
<applicationTierName>, {<optionals>});

Example:
$ec->getComponentsInApplicationTier("default", "newApp",
"appTier1", {applicationEntityRevisionId => "4fa765dd-73f1-11e3-b67e-b0a42052415
3"});

ectool
Syntax:
ectool getComponentsInApplicationTier <projectName> <applicationName>
<applicationTierName> [optionals...]

219

ElectricCommander

Example:
ectool getComponentsInApplicationTier default newApp appTier1
--applicationEntityRevisionId 4fa765dd-73f1-11e3-b67e-b0a420524153
Back to Top

modifyComponent
Modifies an existing component.
You must specify the projectName and componentName arguments.

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String
Name of the component.
componentName
Argument Type: String
Name of an application to which this component is scoped.
applicationName
Argument Type: String
(Optional) Name of the credential to attach to this component.
credentialName
Argument Type: String
(Optional) Comment text describing this component. It is not
description

interpreted by ElectricCommander.
Argument Type: String
(Optional) New name of the component.

newName
Argument Type: String
(Optional) Name of the plugin.
pluginName
Argument Type: String

Positional arguments
projectName, componentName

220

API commands - Component

Response
Retrieves an updated component element.

ec-perl
Syntax:
$<object>->modifyComponent(<projectName>, <componentName>, {<optionals>});

Example:
$ec->modifyComponent("default", "component1", {credentialName => "cred1",
newName => "NewName"});

ectool
Syntax:
ectool modifyComponent <projectName> <componentName> [optionals...]

Example:
ectool modifyComponent default component1
Name

--credentialName cred1

--newName New

Back to Top

removeComponentFromApplicationTier
Removes the given component from the given application tier.
You must specify the projectName, applicationName, applicationTierName, and componentName
arguments.

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String
Name of the application that must be unique among all projects.
applicationName
Argument Type: String
Name of the tier that must be unique within the application.
applicationTierName
Argument Type: String
Name of component.
componentName
Argument Type: String

221

ElectricCommander

Arguments

Descriptions
(Optional) Name of the project that contains the component.

componentProjectName
Argument Type: String

Positional arguments
projectName, applicationName, applicationTierName, componentName

Response
None or a status OK message.

ec-perl
Syntax:
$<object>->removeComponentFromApplicationTier(<projectName>,
<applicationName>, <applicationTierName>, <componentName>);

Example:
$ec->removeComponentFromApplicationTier("default", "newApp",
"appTier1", "component1");

ectool
Syntax:
ectool removeComponentFromApplicationTier <projectName>
<applicationName> <applicationTierName> <componentName>

Example:
ectool removeComponentFromApplicationTier default newApp
appTier1 VCScomponent
Back to Top

222

API Commands - Credential Management

API Commands - Credential Management


attachCredential
createCredential
deleteCredential
detachCredential
getCredential
getCredentials
getFullCredential
modifyCredential

attachCredential
Attaches a credential to a step or a schedule.
Attaching a credential allows the credential to be passed as an actual argument by a schedule or subprocedure
step, or to be used in a getFullCredential call by a command step.
You must specify projectName, credentialName, and locator arguments to identify a step or a schedule.

Arguments

Descriptions
The name of the project that must be must be unique among all

projectName

projects.
Argument type: String
Name of the credential in one of these forms:

credentialName

relative (for example, "cred1")The credential is assumed


to be in the project that contains the request target object.

absolute (for example,


"/projects/BuildProject/credentials/cred1")Tthe credential
can be from any specified project, regardless of the target
objects project.

Argument type: String


The name of the application process to which the credential is
applicationName

attached.
Argument type: String

223

ElectricCommander

Arguments

Descriptions
The name of the component or component process to which the

componentName

credential is attached.
Argument type: String
The name of a procedure to which the credential is attached.

procedureName
Argument type: String
The name of a process to which the credential is attached.
processName
Argument type: String
The name of a process step to which the credential is attached.
processStepName
Argument type: String
The name of the schedule for running a procedure or process in
scheduleName

the "named" project.


Argument type: String
A step name in a procedure or process in the "named" project.

stepName
Argument type: String

Positional arguments
projectName, credentialName

Response
None or status OK message.

ec-perl
syntax: $cmdr->attachCredential(<projectName>, <credentialName>, {...});

Example
$cmdr->attachCredential("Test Proj", "Preflight User", {procedureName =>
"Run Build", stepName=>"Get Sources"});

ectool
syntax: ectool attachCredential <projectName> <credentialName> ...

Example
ectool attachCredential "Test Proj" "Preflight User"
--procedureName "Run Build" --stepName "Get Sources"
Back to Top

224

API Commands - Credential Management

createCredential
Creates a new credential for a project.
You must specify a projectName, credentialName, username, and password.

Arguments

Descriptions
The name of the project where the credential will be stored. The

projectName

name must be unique within all projects.


Argument type: String
The name of the credential.

credentialName
Argument type: String
The user name for the credential.
userName
Argument type: String
The password for the credential.
password
Argument type: String
A plain text or HTML description for this object.
If using HTML, you must surround your text with <html> ...
description

</html> tags. The only HTML tags allowed in the text are: <a>
<b> <br> <div> <dl> <font> <i> <li> <ol> <p> <pre>
<span> <style> <table> <tc> <td> <th> <tr> <ul>
Argument type: String
<Boolean flag - 0|1|true|false>If true, the password can be

passwordRecoveryAllowed

recovered by runnning getFullCredential from a job step.


Argument type: Boolean

Positional arguments
projectName, credentialName, userName, password

Response
None or status OK message.

ec-perl
syntax: $cmdr->createCredential(<projectName>, <credentialName>,
<userName>, <password>, {<optionals>});

225

ElectricCommander

Example
$cmdr->createCredential("Sample Project", "Build User", "build", "abc123",
{userName => "build", password => "abc123"});

ectool
syntax: ectool createCredential <projectName> <credentialName> <userName> <password>
...

Example
ectool createCredential "Sample Project" "Build User" "build"

"abc123"

Back to Top

deleteCredential
Deletes a credential.
You must specify a projectName and a credentialName.

Arguments

Descriptions
The name of the project that contains this credential. The project

projectName

name must be unique among all projects.


Argument type: String
Name of the credential in one of these forms:

credentialName

relative (for example, "cred1")The credential is assumed


to be in the project that contains the request target object.

absolute (for example,


"/projects/BuildProject/credentials/cred1")Tthe credential
can be from any specified project, regardless of the target
objects project.

Argument type: String

Positional arguments
projectName, credentialName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deleteCredential(<projectName>, <credentialName>);

226

API Commands - Credential Management

Example
$cmdr->deleteCredential('Sample Project', 'Build User');

ectool
syntax: ectool deleteCredential <projectName> <credentialName>

Example
ectool deleteCredential "Sample Project" "Build User"
Back to Top

detachCredential
Detaches a credential from an object.
You must specify projectName and credentialName. Also, depending on where the credential is
attached, you must specify a step (using procedureName and stepName), or define a schedule
(using scheduleName).

Arguments

Descriptions
The name of the project that must be unique among all projects.

projectName
Argument type: String
Name of the credential in one of these forms:

credentialName

relative (for example, "cred1")The credential is assumed


to be in the project that contains the request target object.

absolute (for example,


"/projects/BuildProject/credentials/cred1")Tthe credential
can be from any specified project, regardless of the target
objects project.

Argument type: String


The name of the application process with the credential that you
applicationName

want to detach..
Argument type: String
The name of the component or component process with the

componentName

credential that you want to detach..


Argument type: String

227

ElectricCommander

Arguments

Descriptions
The name of the procedure with the credential that you want to

procedureName

detach.
Argument type: String
The name of the process with the credential that you want to

processName

detach.
Argument type: String
The name of the process step with the credential that you want to

processStepName

detach.
Argument type: String
The name of the schedule where this credential is attached.

scheduleName
Argument type: String
The name of the step where this credential is attached. When
stepName

using this argument, you must also enter procedureName.


Argument type: String

Positional arguments
projectName, credentialName

Response
None, or a status OK message on success, or:
NoSuchCredential if the specified credential does not exist.
NoSuchSchedule if the specified schedule does not exist.

ec-perl
syntax: $cmdr->detachCredential(<projectName>, <credentialName>, {<optionals>});

Examples
$cmdr->detachCredential("Test Proj", "Preflight User",
{procedureName => "Run Build",
stepName => "Get Sources"});
$cmdr->detachCredential("Test Proj", "Preflight User",
{scheduleName => "Build Schedule"});

ectool
syntax: ectool detachCredential <projectName> <credentialName> ...

228

API Commands - Credential Management

Examples
ectool detachCredential "Test Proj" "Preflight User"
--procedureName "Run Build" --stepName "Get Sources"
ectool detachCredential "Test Proj" "Preflight User"
--scheduleName "Build Schedule"
Back to Top

getCredential
Finds a credential by name.
You must specify projectName and credentialName.

Arguments

Descriptions
The name of the project that must be unique among all projects.

projectName
Argument type: String
Name of the credential in one of these forms:

credentialName

relative (for example, "cred1")The credential is assumed


to be in the project that contains the request target object.

absolute (for example,


"/projects/BuildProject/credentials/cred1")Tthe credential
can be from any specified project, regardless of the target
objects project.

Argument type: String

Positional arguments
projectName, credentialName

Response
One credential element.

ec-perl
syntax: $cmdr->getCredential(<projectName>, <credentialName> );

Example
$cmdr->getCredential("SampleProject", "Build User");

ectool
syntax: ectool getCredential <projectName> <credentialName>

229

ElectricCommander

Example
ectool getCredential "Sample Project" "Build User"
Back to Top

getCredentials
Retrieves all credentials in a project.
You must specify a projectName.

Arguments

Descriptions
The name of the project that must be unique among all projects.

projectName
Argument type: String
<Boolean flag - 0|1|true|false> If set to 1, only those
credentials that the currently logged-in user has execute privileges
usableOnly

for will be returned.


Argument type: Boolean

Positional arguments
projectName

Response
Zero or more credential elements.

ec-perl
syntax: $cmdr->getCredentials(<projectName>, {...});

Example
$cmdr->getCredentials("Sample Project", {"usableOnly" => 1});

ectool
syntax: ectool getCredentials <projectName> ...

Example
ectool getCredentials "Sample Project" --usableOnly 1
Back to Top

getFullCredential
Finds a credential by name, including password, from within a running step.

230

API Commands - Credential Management

You must specify the credentialName and jobStepId.

Arguments

Descriptions
Name of the credential in one of these forms:

credentialName

relative (for example, "cred1")The credential is assumed


to be in the project that contains the request target object.

absolute (for example,


"/projects/BuildProject/credentials/cred1")Tthe credential
can be from any specified project, regardless of the target
objects project.

Argument type:String
The unique identifier for the job step that is used to make a project
jobStepId

association.
Argument type:UUID

Positional arguments
credentialName, jobStepId

Response
If valueis supplied, only the name is returned when called by ectool. If no value is supplied,
an xPath object is returned.

ec-perl
syntax: $cmdr->getFullCredential(<credentialName>, <jobStepId>);

Example
# Returns an xPath object containing the password.
my $xpath = $cmdr->getFullCredential("myCred", "4fa765dd-73f1-11e3-b67e-b0a42052415
3");
# Parse password from response.
my $password = $xpath->find("//password");

ectool
syntax: ectool getFullCredential <credentialName> <jobStepId>

Example
ectool getFullCredential "myCred" "4fa765dd-73f1-11e3-b67e-b0a420524153"
Back to Top

231

ElectricCommander

modifyCredential
Modifies an existing credential.
You must specify projectName and credentialName.

Arguments

Descriptions

projectName

The name of the project that must be unique among all projects.
Argument type:String
Name of the credential in one of these forms:

credentialName

relative (for example, "cred1")The credential is assumed


to be in the project that contains the request target object.

absolute (for example,


"/projects/BuildProject/credentials/cred1")Tthe credential
can be from any specified project, regardless of the target
objects project.

Argument type:String
A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the
description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type:String
New name of the credential.

newName
Argument type:String
The password for the specified user name.
password
Argument type:String
<Boolean flag - 0|1|true|false>If true, the password can be
passwordRecoveryAllowed

recovered by runnning getFullCredential from a job step.


Argument type: Boolean
The name of the user containing this credential.

userName
Argument type:String

Positional arguments
projectName, credentialName

232

API Commands - Credential Management

Response
None or a status OK message.

ec-perl
syntax: $cmdr->modifyCredential(<projectName>, <credentialName>, {<optionals>});

Example
$cmdr->modifyCredential("Sample Project", "Build User", {userName => "build"});

ectool
syntax: ectool modifyCredential <projectName> <credentialName> ...

Example
ectool modifyCredential "Sample Project" "Build User" --userName build
Back to Top

233

ElectricCommander

API Commands - Database Configuration


getDatabaseConfiguration
setDatabaseConfiguration
validateDatabase on page 237

getDatabaseConfiguration
Retrieves the current database configuration.

Arguments

Descriptions

None

Positional arguments
None

Response
Returns a databaseConfiguration element, which includes the database name, user name,
database dialect, driver, URL, along with the host name and port number.

ec-perl
syntax: $cmdr->getDatabaseConfiguration();

Example
$cmdr->getDatabaseConfiguration();

ectool
syntax: ectool getDatabaseConfiguration

Example
ectool getDatabaseConfiguration
Back to Top

setDatabaseConfiguration
Sets the database configuration on the server. If the server is in bootstrap mode, these changes take effect
immediately and the server attempts to start. If the server is already running, these changes have no effect
until the server is restarted.
Note: If you are replacing the database you are currently using, you must restart the Commander
server after configuring the new database you want to use.

234

API Commands - Database Configuration

ElectricCommander assigns default values to the following three arguments that are derived
from information you enter for the arguments below. The values for these arguments can be viewed in the
XML Response for getDatabaseConfiguration. You should not need to change these values, but
"customDatabase" arguments may be used to override Commander default values. Contact
Electric Cloud Customer Support for assistance with using these arguments:
customDatabaseDialect
customDatabaseDriver
customDatabaseUrl

Arguments

Descriptions
Class name of the Hibernate dialect (advanced use only. The
server chooses an appropriate dialect based on the

customDatabaseDialect

databaseType).
Argument Type: String
Class name of the JDBC driver (advanced use only. The server

customDatabaseDriver

chooses an appropriate driver based on the databaseType).


Argument Type: String
The JDBC to use (advanced use only. The server composes an

customDatabaseUrl

appropriate URL).
Argument Type: String
The name of the database that you want the ElectricCommander

databaseName

server to use. The default is commander.


Argument Type: String
The type of database that you want the ElectricCommander server
to use.
Supported database types are:

databaseType

<builtin|mysql|sqlserver|oracle>.
The default is builtin.
Argument Type: DatabaseType
The domain name or IP address of the host server machine where

hostName

the database is running.


Argument Type: String

235

ElectricCommander

Arguments

Descriptions
<Boolean flag - 0|1|true|false> If true, ignore a passkey
fingerprint mismatch between the current passkey file and the

ignorePasskeyMismatch

database configuration and discard the stored credentials.


Note: This action discards all saved passwords.
Argument Type: Boolean
<Boolean flag - 0|1|true|false> If true, ignore a host name
mismatch between the current server and the database

ignoreServerMismatch

configuration where the server previously started.


Argument Type: Boolean
The password required to access the database.

password

setDatabaseConfiguration does not allow a passwordless


database user. Make sure the database user has a password.
Argument Type: String
The port number used to access the database. The default is the

port

server port default.


Argument Type: String
<Boolean flag - 0|1|true|false> When a host name mismatch
between the current server and the database configuration occurs,
the default behavior is to invalidate all sessions. If this argument is

preserveSessions

set to true, all sessions are preserved and the server can
reconnect to running jobs. This option is used in combination with
ignoreServerMismatch.
Argument Type: Boolean
The name of the user required to access the database.

userName
Argument Type: String

Positional arguments
None

Response
None or a status OK message.

236

API Commands - Database Configuration

ec-perl
syntax: $cmdr->setDatabaseConfiguration({<optionals>});

Example
$cmdr->setDatabaseConfiguration({hostName => "localhost", port => 3306});
# If the database type is set to the mysql, sqlserver, or oracle and
# you want to use the builtin database
$cmdr->setDatabaseConfiguration({databaseType => "builtin", databaseName => "builti
n"});

ectool
syntax: ectool setDatabaseConfiguration <specify configuration values> ...>

Example
ectool setDatabaseConfiguration --hostName localhost --port 3306
# If the database type is set to the mysql, sqlserver, or oracle and
# you want to use the builtin database
ectool setDatabaseConfiguration --databaseType builtin --databaseName builtin

Back to Top

validateDatabase
Performs consistency checks on the database.

Arguments

Descriptions
Comma-separated list of options that specify the aspects of the

options

database to validate.
Argument Type: String

Positional arguments
None

Response
None or a status OK message.

ec-perl
syntax:$cmdr->validateDatabase( {<optionals>});

Example
$cmdr->validateDatabase();

237

ElectricCommander

ectool
syntax: ectool validateDatabase [optionals ...]

Example
ectool validateDatabase
Back to Top

238

API Commands - Directory Provider Management

API Commands - Directory Provider Management


createDirectoryProvider
deleteDirectoryProvider
getDirectoryProvider
getDirectoryProviders
modifyDirectoryProvider
moveDirectoryProvider
testDirectoryProvider

createDirectoryProvider
Creates a new Active Directory or LDAP directory provider.
You must specify a providerName, providerType, and url.

Arguments

Descriptions
Name for a LDAP directory provider that must be unique.

providerName

This human-readable name appears in the user interface to


identify users and groups from this provider.
Argument type: String
The attribute in a group record that contains the common group
name. If specified, this name is used only when searching for
groups from an external provider. Use this argument if the

commonGroupNameAttribute

groupNameAttribute or the uniqueGroupNameAttribute is


set to distinguishedName, which is not searchable.
Argument type: String
A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the

description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type: String
(Optional) The domain name from which Active Directory servers

domainName

are automatically discovered.


Argument type: String

239

ElectricCommander

Arguments

Descriptions
(Optional) The attribute in an LDAP user record that contains the
user's email address. If the attribute is not specified, the account

emailAttribute

name and domain name are concatenated to form an email


address.
Argument type: String
<Boolean flag -0|1|true|false> Determines whether or not to
enable external groups for the directory provider. This argument

enableGroups

defaults to "true".
Argument type: Boolean
The attribute in a user record that contains the user's full name
(first and last) to display in the UI. If this attribute is not specified or

fullUserNameAttribute

the resulting value is empty, the user's account name is used


instead.
Argument type: String
The string is prepended to the basedn to construct the directory

groupBase

domain name (DN) that contains group records.


Argument type: String
A comma-separated attribute name list that identifies a group
member. Most LDAP configurations only specify a single value, but

groupMemberAttributes

if there is a mixture of POSIX and LDAP style groups in the


directory, multiple attributes may be required.
Argument type: String
(Optional) This LDAP query is performed in the groups directory
context to identify groups containing a specific user as a member.
Two common forms of group record in LDAP directories: POSIX
style groups where members are identified by account name, and
groupOfNames or uniqueGroupOfNames records where

groupMemberFilter

members are identified by the full user DN. Both forms are
supported, so the query is passed to parameters: "{0}" is replaced
with the full user record DN, and "{1}" is replaced with the user's
account name.
Argument type: String

240

API Commands - Directory Provider Management

Arguments

Descriptions
The attribute in a group record that contains the name of the group.

groupNameAttribute
Argument type: String
This LDAP query is performed in the context of the groups
groupSearchFilter

directory to enumerate group records.


Argument type: String
The domain name (DN) of a user who has read-only access to
LDAP user and group directories. If this property is not specified,
the server attempts to connect as an unauthenticated user. Not all

managerDn

servers allow anonymous read-only access.


Note: This user does not need to be an admin user with modify
privileges.
Argument type: String
If the managerDn property is set, this password is used to

managerPassword

authenticate the manager user.


Argument type: String
Type string for a directory provider: <ldap|activedirectory>

providerType
Argument type: ProviderType
This is an identifier (string) used for LDAP directory providers so
users and groups (within LDAP) can be uniquely identified in
"same name" collisions across multiple directory providers. The
realm

realm is appended to the user or group name when stored in the


ElectricCommander server. For example, <user>@dir (where the
realm is set to "dir").
Argument type: String

241

ElectricCommander

Arguments

Descriptions
The server URL is in the form protocol://host:port/basedn.
Protocol is either ldap or ldaps (for secure LDAP). The port is
implied by the protocol, but can be overridden if it is not at the
default location (389 for ldap, 636 for ldaps). The basedn is the

url

path to the top-level directory that contains users and groups at


this site. This is typically the domain name where each part is
listed with a dc= and separated by commas.
Note: Spaces in the basedn must be URL encoded (%20).
Argument type: String
This string is prepended to the basedn to construct the directory

userBase

DN that contains user records.


Argument type: String
The attribute in a user record that contains the user's account

userNameAttribute

name.
Argument type: String
This LDAP query is performed in the context of the user directory to
search for a user by account name. The string {0} is replaced

userSearchFilter

with the user's login ID. Typically, the query compares a user
record attribute with the substituted user login ID.
Argument type: String
<Boolean flag - 0|1|true|false> If true, recursively search the

userSearchSubtree

subtree below the user base.


Argument type: Boolean
<Boolean flag -0|1|true|false> Use this flag to define whether
or not SSL is used for server-agent communication, or if you need

useSSL

to use SSL to communicate with your Active Directory servers. The


default is "true".
Argument type: Boolean

Positional arguments
providerName, providerType, url

Response
None or status OK message.

242

API Commands - Directory Provider Management

ec-perl
syntax: $cmdr->createDirectoryProvider(<providerName>, {<optionals>});

Example
$cmdr->createDirectoryProvider("AD3", {url => "ldaps://pdc/dc=coname3.dc=com",
providerType => "activedirectory"});

ectool
syntax: ectool createDirectoryProvider <providerName> ...

Example
ectool createDirectoryProvider AD3 --url "ldaps://pdc/dc=coname3.dc=com"
--providerType activedirectory
Back to Top

deleteDirectoryProvider
Deletes an Active Directory or LDAP directory provider.
You must specify a providerName.

Arguments

Descriptions
The name of the directory provider that you want to delete.

providerName
Argument Type: String

Positional arguments
providerName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deleteDirectoryProvider(<providerName>);

Example
$cmdr->deleteDirectoryProvider('AD3');

ectool
syntax: ectool deleteDirectoryProvider <providerName>

Example
ectool deleteDirectoryProvider AD3
Back to Top

243

ElectricCommander

getDirectoryProvider
Retrieves a directory provider by name.
You must specify a providerName.

Arguments

Descriptions
The name of the directory provider that must be unique.

providerName
Argument Type: String

Positional arguments
providerName

Response
One directoryProvider element.
Note:For security reasons, the managerPassword field is never returned.

ec-perl
syntax: $cmdr->getDirectoryProvider(<providerName>);

Example
$cmdr->getDirectoryProvider("AD3");

ectool
syntax: ectool getDirectoryProvider <providerName>

Example
ectool getDirectoryProvider AD3
Back to Top

getDirectoryProviders
Retrieves all directory providers.

Arguments
None

Positional arguments
None

244

Descriptions

API Commands - Directory Provider Management

Response
Zero or more directoryProvider elements.

ec-perl
syntax: $cmdr->getDirectoryProviders();

Example
$cmdr->getDirectoryProviders();

ectool
syntax: ectool getDirectoryProviders

Example
ectool getDirectoryProviders
Back to Top

modifyDirectoryProvider
Modifies an existing LDAP directory provider.
You must specify the providerName.

Arguments

Descriptions
The name of the directory provider that must be unique.

providerName
Argument Type: String
The attribute in a group record that contains the common group
name. If specified, this name is used only when searching for
groups from an external provider. Use this argument if the
commonGroupNameAttribute

groupNameAttribute or the uniqueGroupNameAttribute is


set to distinguishedName, which is not searchable.
Argument Type: String
A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the

description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>.
Argument Type: String

245

ElectricCommander

Arguments

Descriptions
The domain from which Active Directory servers are automatically

domainName

discovered.
Argument Type: String
The attribute in a user record that contains the user's email
address. If the attribute is not specified, the account name and

emailAttribute

domain name are concatenated to form an email address.


Argument Type: String
<Boolean flag - 0|1|true|false> Determines whether or not to
enable external groups for the directory provider. Defaults to true.

enableGroups
Argument Type: Boolean
The attribute in a user record that contains the user's full name
(first and last) for display in the UI. If this attribute is not specified or
fullUserNameAttribute

the resulting value is empty, the user's account name is used


instead.
Argument Type: String
This string is prepended to the basedn to construct the directory

groupBase

DN that contains group records.


Argument Type: String
A comma-separated attribute name list that identifies a group
member. Most LDAP configurations only specify a single value, but

groupMemberAttributes

if there is a mixture of POSIX and LDAP style groups in the


directory, multiple attributes might be required.
Argument Type: String
This LDAP query is performed in the group directory context to
identify groups containing a specific user as a member. Two
common forms of group record in LDAP directories: POSIX style
groups where members are identified by account name, and

groupMemberFilter

groupOfNamesor uniqueGroupOfNamesrecords where


members are identified by the full user DN. Both forms are
supported, so the query is passed two parameters: "{0}" is
replaced with the full user record DN, and "{1}" is replaced with
the user's account name.

246

API Commands - Directory Provider Management

Arguments

Descriptions

groupNameAttribute

The group record attribute that contains the name of the group.
A filter name: this LDAP query is performed in the context of the

groupSearchFilter

groups directory to enumerate group records.


Argument Type: String
The DN of a user who has read access to LDAP user and group
directories. If this property is not specified, the server attempts to
connect as an unauthenticated user. Not all servers allow

managerDn

anonymous read-only access.


Note: This user does not need to be an admin user with modify
privileges.
Argument Type: String
If the managerDn property is set, this password is used to

managerPassword

authenticate the manager user.


Argument Type: String
New name of the directory provider.

newName
Argument Type: String
Type string for a directory provider:<ldap|activedirectory> .
providerType
Argument Type: DirectoryType
This is an identifier (string) used for LDAP directory providers so
users and groups (within LDAP) can be uniquely identified in
"same name" collisions across multiple directory providers. The
realm

realm is appended to the user or group name when stored in the


Commander server. For example, <user>@dir (where the realm is
set to "dir").
Argument Type: String

247

ElectricCommander

Arguments

Descriptions
The LDAP server URL is in the form
protocol://host:port/basedn.
Protocol is either ldap or ldaps (for secure LDAP). The port is
implied by the protocol, but can be overridden if it is not at the
default location (389 for ldap, 636 for ldaps). The basednis the

url

path to the top-level directory that contains users and groups at


this site. This is typically the domain name where each part is
listed with a dc=and separated by commas.
Note:Spaces in the basedn must be URL encoded (%20).
Argument Type: String
This string is prepended to the basedn to construct the directory

userBase

DN that contains user records.


Argument Type: String
The attribute in a user record that contains the user's account

userNameAttribute

name.
Argument Type: String
This LDAP query is performed in the context of the user directory to
search for a user by account name. The string "{0}" is replaced

userSearchFilter

with the user's login ID. Typically, the query compares a user
record attribute with the substituted user login ID
Argument Type: String .
<Boolean flag - 0|1|true|false> If true, recursively search

userSearchSubtree

the subtree below the user base.


Argument Type: Boolean
<Boolean flag - 0|1|true|false > Use this flag to define
whether or not SSL is used for server-agent communication, or if

useSSL

you need to use SSL to communicate with your Active Directory


servers. Default is "true".
Argument Type: Boolean

Positional arguments
providerName

Response
None or a status OK message.

248

API Commands - Directory Provider Management

ec-perl
syntax: $cmdr->modifyDirectoryProvider(<providerName>, {<optionals>});

Example
$cmdr->modifyDirectoryProvider("AD3", {emailAttribute => "email"});

ectool
syntax: ectool modifyDirectoryProvider <providerName> ...

Example
ectool modifyDirectoryProvider AD3 --emailAttribute email
Back to Top

moveDirectoryProvider
Moves an Active Directory or LDAP directory provider in front of another specified provider or to the
end of the list.
You must specify a providerName.

Arguments

Descriptions
The name of the directory provider that must be unique.

providerName
Argument Type: String
Moves this directory provider (providerName) to a place before
the name specified by this option. If omitted, providerName is
beforeProviderName

moved to the end.


Argument Type: String

Positional arguments
providerName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->moveDirectoryProvider(<providerName>, {<optionals>});

Example
$cmdr->moveDirectoryProvider("AD3", {beforeProviderName => "AD2"});

ectool
syntax: ectool moveDirectoryProvider <providerName> ...

249

ElectricCommander

Example
ectool moveDirectoryProvider AD3 --beforeProviderName AD2
Back to Top

testDirectoryProvider
Tests that a specific user name and password combination work with the specified directory provider settings.
You must specify userName and password (the command will prompt for the password if it is omitted).

Arguments

Descriptions
The name of the user you are testing for this provider.

userName
Argument Type: String
The password for the user that you are testing for this provider. The
password

command will prompt for the password if it is omitted.


Argument Type: String
The attribute in a group record that contains the common group
name. If specified, this name is used only when searching for
groups from an external provider. Use this argument if the

commonGroupNameAttribute

groupNameAttribute or the uniqueGroupNameAttribute is


set to distinguishedName, which is not searchable.
Argument Type: String
A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the

description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>.
Argument Type: String
The domain from which Active Directory servers are automatically

domainName

discovered.
Argument Type: String

250

API Commands - Directory Provider Management

Arguments

Descriptions
The attribute in a user record that contains the user's email
address. If the attribute is not specified, the account name and

emailAttribute

domain name are concatenated to form an email address.


Argument Type: String
<Boolean flag - 0|1|true|false> Determines whether or not to
enable external groups for the directory provider. Defaults to "true".

enableGroups
Argument Type: Boolean
The attribute in a user record that contains the user's full name
(first and last) for display in the UI. If this attribute is not specified or
fullUserNameAttribute

the resulting value is empty, the user's account name is used


instead.
Argument Type: String
This string is prepended to the basedn to construct the directory

groupBase

DN that contains group records.


Argument Type: String
A comma separated attribute name list that identifies a group
member. Most LDAP configurations only specify a single value, but

groupMemberAttributes

if there is a mixture of POSIX and LDAP style groups in the


directory, multiple attributes might be required.
Argument Type: String
This LDAP query is performed in the groups directory context to
identify groups containing a specific user as a member.
Two common forms of group record in LDAP directories: POSIX
style groups where members are identified by account name, and
groupOfNamesor uniqueGroupOfNamesrecords where

groupMemberFilter

members are
identified by the full user DN. Both forms are supported, so the
query is passed two parameters: "{0}" is replaced with the full
user record DN, and "{1}" is replaced with the user's account
name.
Argument Type: String

251

ElectricCommander

Arguments

Descriptions
The group record attribute that contains the name of the group.

groupNameAttribute
Argument Type: String
This LDAP query is performed in the context of the groups
groupSearchFilter

directory to enumerate group records.


Argument Type: String
The DN of a user who has read-only access to LDAP user and
group directories. If this property is not specified, the server
attempts to connect as an unauthenticated user. Not all servers

managerDn

allow anonymous read-only access.


Note: This user does not need to be an admin user with modify
privileges.
Argument Type: String
If the managerDn property is set, this password is used to

managerPassword

authenticate the manager user.


Argument Type: String
Type string for a directory provider:<ldap|activedirectory>.

providerType
Argument Type: DirectoryType
This is an identifier (string) used for LDAP directory providers so
users and groups (within LDAP) can be uniquely identified in
"same name" collisions across multiple directory providers. The
realm

realm is appended to the user or group name when stored in the


Commander server. For example, <user>@dir (where the realm is
set to "dir").
Argument Type: String

252

API Commands - Directory Provider Management

Arguments

Descriptions
The LDAP server URL is in the form
protocol://host:port/basedn.
Protocol is either ldap or ldaps (for secure LDAP). The port is
implied by the protocol, but can be overridden if it is not at the
default location (389 for ldap, 636 for ldaps). The basedn is the

url

path to the top-level directory that contains users and groups at


this site. This is typically the domain name where each part is
listed with a dc= and separated by commas.
Note: Spaces in the basedn must be URL encoded (%20).
Argument Type: String
<Boolean flag - 0|1|true|false> If "true", defaults will be used

useDefaults

for all fields not specified.


Argument Type: Boolean
This string is prepended to the base DN to construct the directory

userBase

DN that contains user records.


Argument Type: String
The attribute in a user record that contains the user's account

userNameAttribute

name.
Argument Type: String
A filter name. This LDAP query is performed in the context of the
user directory to search for a user by account name. The string "

userSearchFilter

{0}" is replaced with the user's login ID. Typically, the query
compares a user record attribute with the substituted user login ID.
Argument Type: String
<Boolean flag - 0|1|true|false> If "true", recursively search

userSearchSubtree

the subtree below the user base.


Argument Type: Boolean
<Boolean flag - 0|1|true|false> Use this flag to define
whether or not SSL is used for server-agent communication, or if

useSSL

you need to use SSL to communicate with your Active Directory


servers. Default is "true".
Argument Type: Boolean

253

ElectricCommander

Positional arguments
userName, password

Response
Three queries are returned: One query authenticates the user userAuthenticationTest, one query
retrieves information about the user findUserTest, and one shows the results of finding groups where the
user is a member findGroupsTest.

ec-perl
syntax: $cmdr->testDirectoryProvider(<userName>, <password>, {<optionals>});

Example
$cmdr->testDirectoryProvider("testUser", "testUserPassword",
{providerType => "activedirectory",
domainName => "my-company.com",
useDefaults => 1,
managerDn => "testManager",
managerPassword => "testManagerPassword"});

ectool
syntax: ectool testDirectoryProvider <userName> <password> ...

Example
ectool testDirectoryProvider testUser testUserPassword --providerType activeDirecto
ry
--domainName my-company.com
--useDefaults 1
--managerDn testManager
--managerPassword testManagerPassword
Back to Top

254

API Commands -Dynamic Enviroment

API Commands -Dynamic Enviroment


addResourcePoolToEnvironmentTier on page 256
addResourceTemplateToEnvironmentTemplateTier on page 257
addResourceToEnvironmentTemplateTier on page 258
createEnvironmentTemplate on page 259
createEnvironmentTemplateTier on page 260
createEnvironmentTemplateTierMap on page 262
createHook on page 263
createResourceTemplate on page 265
deleteEnvironmentTemplate on page 267
deleteEnvironmentTemplateTier on page 268
deleteEnvironmentTemplateTierMapping on page 270
deleteHook on page 271
deleteResourceTemplate on page 272
getAvailableResourcesForEnvironment on page 273
getEnvironmentTemplate on page 273
getEnvironmentTemplateTier on page 274
getEnvironmentTemplateTierMaps on page 275
getEnvironmentTemplateTiers on page 276
getEnvironmentTemplates on page 277
getHook on page 278
getHooks on page 279
getResourcePoolsInEnvironmentTier on page 280
getResourceTemplate on page 281
getResourceTemplates on page 282
getResourceTemplatesInEnvironmentTemplateTier on page 282
getResourcesInEnvironmentTemplateTier on page 283
modifyEnvTempTierResourceTempMapping on page 284
modifyEnvironmentTemplate on page 286
modifyEnvironmentTemplateTier on page 287

255

ElectricCommander

modifyEnvironmentTemplateTierMap on page 288


modifyHook on page 289
modifyResourceTemplate on page 292
provisionEnvironment on page 294
provisionResourcePool on page 295
removeResourceFromEnvironmentTemplateTier on page 297
removeResourcePoolFromEnvironmentTier on page 298
removeResourceTemplateFromEnvironmentTemplateTier on page 299
tearDown on page 300

addResourcePoolToEnvironmentTier
Adds a resource pool to a specific environment tier. A resource pool is a named group of resources.
You must specify the resourcePoolName, projectName, environmentName, and environmentTierName
arguments.

Arguments

Descriptions
Name of the resource pool that must be unique among all

resourcePoolName

resource pools.
Argument Type: String
Name of the project that must be unique among all projects.

projectName
Argument Type: String
Name of the environment that must be unique among all
environmentName

environments.
Argument Type: String
Name of the environment tier that must be unique among all tiers

environmentTierName

for the environment.


Argument Type: String

Positional arguments
resourcePoolName, projectName, environmentName, environmentTierName

256

API Commands -Dynamic Enviroment

Response
None or status OK message.

ec-perl
syntax:$cmdr->addResourcePoolToEnvironmentTier(<resourcePoolName>, <projectName>,
<environmentName>, <environmentTierName>);

Example:
$cmdr->addResourcePoolToEnvironmentTier("pool1", "Default", "Production", "Web Serv
er");

ectool
syntax:ectool addResourcePoolToEnvironmentTier <resourcePoolName> <projectName>
<environmentName> <environmentTierName>

Example:
ectool addResourcePoolToEnvironmentTier "pool1" "Default" "Production" "Web Server"
Back to Top

addResourceTemplateToEnvironmentTempla
teTier
Adds a resource template to the specified environment template tier.
You must specify the resourceTemplateName, projectName, environmentTemplateName, and
environmentTemplateTierNamearguments.

Arguments

Descriptions
Name of the resource template that must be unique among all

resourceTemplateName

resource templates.
Argument Type: String
Name of the project that must be unique among all projects.

projectName
Argument Type: String
Name of the environment template.
environmentTemplateName
Argument Type: String

257

ElectricCommander

Arguments

Descriptions
Name of the environment template tier that must be unique among

environmentTemplateTierName

all tiers for the environment template.


Argument Type: String
(Optional) Number of resources to be spun from the specified

resourceCount

resource template.
Argument Type: Integer

Positional arguments
resourceTemplateName , projectName, environmentTemplateName,
environmentTemplateTierName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->addResourceTemplateToEnvironmentTemplateTier(<resourceTemplateName>,
<projectName>,
<environmentTemplateName>, <environmentTemplateTierName>, {<optionals>});

Example:
$ec->addResourceTemplateToEnvironmentTemplateTier("Resource1", "default", "Produ
ction", "WebServer", {resourceCount => 4});

ectool
syntax: addResourceTemplateToEnvironmentTemplateTier <resourceTemplateName>
<projectName> <environmentTemplateName> <environmentTemplateTierName> ...

Example:
ectool addResourceTemplateToEnvironmentTemplateTier "Resource1" "default" "Produ
ction" "WebServer" --resourceCount => 4
Back to Top

addResourceToEnvironmentTemplateTier
Adds a resource to the specified environment template tier.
You must specify the resourceName, projectName, environmentTemplateName, and
environmentTemplateTierNamearguments.

258

API Commands -Dynamic Enviroment

Arguments

Descriptions
Name of the resource that must be unique among all resources.

resourceName
Argument Type: String
Name for the project that must be unique among all projects.
projectName
Argument Type: String
Name of the environment template.
environmentTemplateName
Argument Type: String
Name for the environment template tier that must be unique
environmentTemplateTierName

among all tiers for the environment template.


Argument Type: String

Positional arguments
resourceName, projectName, environmentTemplateName, environmentTemplateTierName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->addResourceToEnvironmentTemplateTier(<resourceName>, <projectName>,
<environmentTemplateName>, <environmentTemplateTierName>);

Example:
$ec->addResourceToEnvironmentTemplateTier("Resource1", "default", "Dev1", "Tomca
t");

ectool
syntax: addResourceToEnvironmentTemplateTier <resourceName> <projectName>
<environmentTemplateName> <environmentTemplateTierName>
Example:
ectool addResourceToEnvironmentTemplateTier "Resource1" "default" "Dev1" "Tomca
t"
Back to Top

createEnvironmentTemplate
Creates an environment template.
You must specify the projectName and environmentTemplateName arguments.

259

ElectricCommander

Arguments

Descriptions
Name of the project that must be unique among all projects.

projectName
Argument Type: String
Name of the environment template.
environmentTemplateName
Argument Type: String
(Optional)A plain text or HTML description for this object. If using
HTML, you must surround your text with <html> ... </html>

description

tags. The only HTML tags allowed in the text are: <a> <b> <br>
<div> <dl> <font> <i> <li> <ol> <p> <pre> <span>
<style> <table> <tc> <td> <th> <tr> <ul>.
This text is not interpreted by the ElectricCommander automation
platform.
Argument type:String

Positional arguments
projectName, environmentTemplateName

Response
Returns a environment template object.

ec-perl
syntax: $cmdr->createEnvironmentTemplate(<projectName>, <environmentTemplateName>,
{<optionals>});

Example:
$ec->createEnvironmentTemplate("default", "Dev1");

ectool
syntax: ectool createEnvironmentTemplate <projectName> <environmentTemplateName> ...

Example:
ectool createEnvironmentTemplate "default" "Dev1"
Back to Top

createEnvironmentTemplateTier
Creates a tier in an environment template.

260

API Commands -Dynamic Enviroment

You must specify the projectName, environmentTemplateName, and environmentTemplateTierName


arguments.

Arguments

Descriptions
Name of the project that must be unique among all projects.

projectName
Argument Type: String
Name of the environment template.
environmentTemplateName
Argument Type: String
Name of the environment template tier that must be unique among
environmentTemplateTierName

all tiers for the environment template.


Argument Type: String
(Optional)A plain text or HTML description for this object. If using
HTML, you must surround your text with <html> ... </html>

description

tags. The only HTML tags allowed in the text are: <a> <b> <br>
<div> <dl> <font> <i> <li> <ol> <p> <pre> <span>
<style> <table> <tc> <td> <th> <tr> <ul>.
This text is not interpreted by the ElectricCommander automation
platform.
Argument type:String

Positional arguments
projectName, environmentTemplateName, environmentTemplateTierName

Response
Returns an environment tier in an environment template.

ec-perl
syntax: $cmdr->createEnvironmentTemplateTier(<projectName>,
<environmentTemplateName>, <environmentTemplateTierName>, {<optionals>});

Example:
$ec->createEnvironmentTemplateTier("default", "Dev1", "Repository");

ectool
syntax: ectool createEnvironmentTemplateTier <projectName>
<environmentTemplateName> <environmentTemplateTierName> ...

261

ElectricCommander

Example:
ectool createEnvironmentTemplateTier "default" "Dev1""Repository"
Back to Top

createEnvironmentTemplateTierMap
Creates a environment-template tier map for an application.
You must specify the projectName, applicationName, environmentProjectName, and
environmentTemplateName arguments.

Arguments

Descriptions
Name of the project that must be unique among all projects.

projectName
Argument Type: String
Name of the application.
applicationName
Argument Type: String
Name for the project to which the environment belongs.
environmentProjectName
Argument Type: String
Name of the environment template.
environmentTemplateName
Argument Type: String
Revision ID of the versioned object
applicationEntityRevisionId
Argument Type: UUID
(Optional)Name of the tier map associated with the environment
template. If you do not specify an tier map, ElectricFlow uses a tier
tierMapName

map with a hyphenated-application-and-environment name.


Argument type:String
(Optional)List of mappings between the application tiers and the

tierMappings

environment template tiers.


Argument Type: Map

Positional arguments
projectName, applicationName, environmentProjectName, environmentTemplateName

262

API Commands -Dynamic Enviroment

Response
Returns a tier map for an environment template.

ec-perl
syntax: $cmdr->createEnvironmentTemplateTierMap(<projectName>, <applicationName>,
<environmentProjectNam>, <environmentTemplateName>, {<optionals>});

Example:
$ec->createEnvironmentTemplateTierMap("default", "Undeploy", "Dev1", "Repositor
y");

ectool
syntax: ectool createEnvironmentTemplateTierMap <projectName> <applicationName>
<environmentProjectName> <environmentTemplateName> <optionals>

Example:
ectool createEnvironmentTemplateTierMap "default" "Undeploy" "Dev1" "Repository"
Back to Top

createHook
Creates a hook in a resource template, which can have one or more hooks. A hook stores a reference to a
procedure in an ElectricFlow project or plugin project. When a resource template is used to create a resource
pool, these procedures are invoked.
You must specify the hookName argument.

Arguments

Descriptions
Name of the hook that must be unique among all hooks in the

hookName

project.
Argument Type: String
(Optional) Broadcast flag
Use this flag to broadcast the hook name in the project.

broadcast

The broadcast value = <Boolean flag -0|1|true|false>.


Defaults to "true".
Argument type: Boolean

263

ElectricCommander

Arguments

Descriptions
(Optional)A plain text or HTML description for this object. If using
HTML, you must surround your text with <html> ... </html>

description

tags. The only HTML tags allowed in the text are: <a> <b> <br>
<div> <dl> <font> <i> <li> <ol> <p> <pre> <span>
<style> <table> <tc> <td> <th> <tr> <ul>.
This text is not interpreted by the ElectricCommander automation
platform.
Argument type:String
(Optional)Parameters that are passed to the procedure.

hookParameters
Argument type:Map
(Optional) Type of the hook:

hookType

PRE_PROVISIONING

POST_PROVISIONING

PRE_CONFIGUARTION

POST_CONFIGUARTION

PRE_TEARDOWN

POST_TEARDOWN

Argument Type: String


(Optional) Name of the procedure that the hook references.
procedureName
Argument Type: String
(Optional)Name of the plugin procedure. Use this argument when
the hook references a plugin procedure. The promoted version of
procedurePluginKey

the plugin is invoked by default.


Argument Type: String
(Optional)Name of the project to which the procedure belongs.
When you use a specific version of a plugin, this is the name of the

procedureProjectName

plugin project.
Argument Type: String
(Optional) Name of the resource template.

resourceTemplateName
Argument Type: String

264

API Commands -Dynamic Enviroment

Positional arguments
hookName

Response
Returns a hook for a resource template.

ec-perl
syntax: $cmdr->createHook(<hookName>, {<optionals>});

Example:
$ec->createHook("config", {hooktype => PRE_CONFIGUARTION, procedureName => "Serv
er Start", procedureProjectName => "Servers");

ectool
syntax: ectool createHook <hookName> ...

Example:
ectool createHook "config" --hookType PRE_CONFIGUARTION --procedureName "Server
Start" --procedureProjectName "Servers"
Back to Top

createResourceTemplate
Creates a resource template.
You must specify the projectName and resourceTemplateName.

Arguments

Descriptions
Name of the project that must be unique among all projects.

projectName
Argument Type: String
Name for the resource template that must be unique among all
resourceTemplateName

resource templates.
Argument Type: String
(Optional)Configuration Manager plugin parameters that are

cfgMgrParameters

passed from the configuration-manager plugin to ElectricFlow.


Argument Type: Map

265

ElectricCommander

Arguments

Descriptions
(Optional)Configuration Manager plugin key.

cfgMgrPluginKey
Argument Type: String
(Optional) Name of the cloud-provider plugin method.
cfgMgrProcedure
Argument Type: String
(Optional)Name of the project to which the configuration-manager
cfgMgrProjectName

plugin applies.
Argument Type: String
(Optional)Parameters that are passed from the cloud- provider

cloudProviderParameters

plugin to ElectricFlow.
Argument Type: Map
(Optional)Cloud-provider plugin key.

cloudProviderPluginKey
Argument Type: String
(Optional) Cloud-provider plugin method name.
cloudProviderProcedure
Argument Type: String
(Optional) Name of the cloud-provider plugin configuration.
cloudProviderConfig
Argument Type: String
(Optional)Name of the project to which the cloud-provider plugin
cloudProviderProjectName

applies.
Argument Type: String
(Optional)A plain text or HTML description for this object. If using
HTML, you must surround your text with <html> ... </html>

description

tags. The only HTML tags allowed in the text are: <a> <b> <br>
<div> <dl> <font> <i> <li> <ol> <p> <pre> <span>
<style> <table> <tc> <td> <th> <tr> <ul>.
This text is not interpreted by the ElectricCommander automation
platform.
Argument type:String

Positional arguments
resourceTemplateName, cloudProviderProcedure, cloudProviderConfig

266

API Commands -Dynamic Enviroment

Response
Returns a resource template.

ec-perl
syntax: $cmdr->createResourceTemplate(<projectName>, <resourceTemplateName>,
{<optionals>});

Example:
$ec->createResourceTemplate("default", "QA test", {cloudProviderProjectName => "
Deploy2"});

ectool
syntax: ectool createResourceTemplate <project Name> <resourceTemplateName>
<optionals>...

Example:
ectool createResourceTemplate "default" "QA test" --cloudProviderProjectName "De
ploy2"
Back to Top

deleteEnvironmentTemplate
Deletes an environment template.
You must specify the projectName and environmentTemplateName arguments.

Arguments

Descriptions
Name of the project that must be unique among all projects.

projectName
Argument Type: String
Name of the environment template.
environmentTemplateName
Argument Type: String

Positional arguments
projectName, environmentTemplateName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deleteEnvironmentTemplate(<projectName>, <environmentTemplateName>);

267

ElectricCommander

Example:
$ec->deleteEnvironmentTemplate("default", "Dev1");

ectool
syntax: ectool deleteEnvironmentTemplate <projectName> <environmentTemplateName> ...

Example:
ectool deleteEnvironmentTemplate "default" "Dev1"
Back to Top

deleteEnvironmentTemplateTier
Deletes a tier in an environment template.
You must specify the projectName, environmentTemplateName, and environmentTemplateTierName
arguments.

Arguments

Descriptions
Name of the project that must be unique among all projects.

projectName
Argument Type: String
Name of the environment template.
environmentTemplateName
Argument Type: String
Name of the environment template tier that must be unique among
environmentTemplateTierName

all tiers for the environment template.


Argument Type: String

Positional arguments
projectName, environmentTemplateName, environmentTemplateTierName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deleteEnvironmentTemplateTier(<projectName>,
<environmentTemplateName>, <environmentTemplateTierName>);

Example:
$ec->deleteEnvironmentTemplateTier("default", "Dev1", "Repository");

268

API Commands -Dynamic Enviroment

ectool
syntax: ectool deleteEnvironmentTemplateTier <projectName>
<environmentTemplateName> <environmentTemplateTierName> ...

Example:
ectool deleteEnvironmentTemplateTier "default" "Dev1" "Repository"
Back to Top

deleteEnvironmentTemplateTierMap
Deletes an environment-template tier map from an application.
You must specify the projectName, applicationName, environmentProjectName, and
environmentTemplateName arguments.

Arguments

Descriptions
Name of the project that must be unique among all projects.

projectName
Argument Type: String
Name of the application.
applicationName
Argument Type: String
Name for the project to which the environment template belongs.
environmentProjectName
Argument Type: String
Name of the environment template.
environmentTemplateName
Argument Type: String

Positional arguments
projectName, applicationName, environmentProjectName, environmentTemplateName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deleteEnvironmentTemplateTierMap(<projectName>, <applicationName>,
<environmentProjectName> <environmentTemplateName>);

269

ElectricCommander

Example:
$ec->deleteEnvironmentTemplateTierMap("default", "Undeploy", "Dev1", "Repositor
y");

ectool
syntax: ectool deleteEnvironmentTemplateTierMap <projectName> <applicationName>
<environmentProjectName> <environmentTemplateName> ...

Example:
ectool deleteEnvironmentTemplateTierMap "default" "Undeploy" "Dev1" "Repository"
Back to Top

deleteEnvironmentTemplateTierMapping
Deletes a tier mapping from a environment-template tier map. A tier mapping is a mapping of an application tier
to an environment template tier. Atier map has one or more mappings.
You must specify the projectName, applicationName, environmentProjectName,
environmentTemplateName, and applicationTierName arguments.

Arguments

Descriptions
Name of the project that must be unique among all projects.

projectName
Argument Type: String
Name of the application.
applicationName
Argument Type: String
Name for the project to which the environment belongs.
environmentProjectName
Argument Type: String
Name of the environment template.
environmentTemplateName
Argument Type: String
Name of the application tier.
applicationTierName
Argument Type: String

Positional arguments
projectName, applicationName, environmentProjectName, environmentTemplateName,
applicationTierName

270

API Commands -Dynamic Enviroment

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deleteEnvironmentTemplateTierMapping(<projectName>,
<applicationName>, <environmentProjectName> <environmentTemplateName>
<applicationTierName>);

Example:
$ec->deleteEnvironmentTemplateTierMapping("default", "Undeploy", "Dev1", "Reposi
tory", "Database");

ectool
syntax: ectool deleteEnvironmentTemplateTierMapping <projectName> <applicationName>
<environmentProjectName> <environmentTemplateName> <applicationTierName>...

Example:
ectool deleteEnvironmentTemplateTierMapping "default" "Undeploy" "Dev1" "Reposit
ory" "Database"
Back to Top

deleteHook
Deletes a hook associated with an entity.
You must specify the hookName argument.

Arguments

Descriptions
Name of the hook that must be unique among all hooks in the

hookName

project.
Argument Type: String
(Optional) Name of the project that owns the hook.

projectName
Argument Type: String
(Optional) Name of the resource template.
resourceTemplateName
Argument Type: String

Positional arguments
hookName

271

ElectricCommander

Response
None or a status OK message.

ec-perl
syntax:$cmdr->deleteHook(<hookName>, {<optionals>});

Example:
$ec->deleteHook("awsconfig", {resourceTemplateName => "AWS backup server"});

ectool
syntax: ectool deleteHook <hookName> ...

Example:
ectool deleteHook "awsconfig" --resourceTemplateName "AWS backup server"
Back to Top

deleteResourceTemplate
Deletes a resource template.
You must specify the projectName and resourceTemplateName.

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String
Name for the resource template that must be unique among all
resourceTemplateName

resource templates.
Argument Type: String

Positional arguments
projectName, resourceTemplateName

Response
None or a status OK message.

ec-perl
syntax:$cmdr->deleteResourceTemplate(<projectName>, <resourceTemplateName>);

Example:
$ec->deleteResourceTemplate("default", "QA Test");

272

API Commands -Dynamic Enviroment

ectool
syntax: ectool deleteResourceTemplate <projectName> <resourceTemplateName>

Example:
ectool deleteResourceTemplate "default" "QA Test"
Back to Top

getAvailableResourcesForEnvironment
Retrieve all non-dynamic resources or resource pools.

Arguments

Descriptions
(Optional) Flag to return resources or resource pools.

objectTypeToReturn
Argument Type: String

Response
None or a status OK message.

ec-perl
syntax:$cmdr->getAvailableResourcesForEnvironment({<optionals>});

Example:
$ec->getAvailableResourcesForEnvironment({objectTypeToReturn => "resource"});

ectool
syntax: ectool getAvailableResourcesForEnvironment ...

Example:
ectool getAvailableResourcesForEnvironment --objectTypeToReturn "resource"
Back to Top

getEnvironmentTemplate
Gets an environment template.
You must specify the projectName and environmentTemplateName arguments.

273

ElectricCommander

Arguments

Descriptions
Name of the project that must be unique among all projects.

projectName
Argument Type: String
Name of the environment template.
environmentTemplateName
Argument Type: String

Positional arguments
projectName, environmentTemplateName

Response
An environmentTemplate element.

ec-p erl
syntax:$cmdr->getEnvironmentTemplate(<projectName>, <environmentTemplateName>);

Example:
$ec->getEnvironmentTemplate("default", "Dev1");

ectool
syntax: ectool getEnvironmentTemplate <projectName> <environmentTemplateName> ...

Example:
ectool getEnvironmentTemplate "default" "Dev1"
Back to Top

getEnvironmentTemplateTier
Gets an environment tier in an environment template.
You must specify the projectName, environmentTemplateName, and environmentTemplateTierName
arguments.

Arguments

Descriptions
Name of the project that must be unique among all projects.

projectName
Argument Type: String

274

API Commands -Dynamic Enviroment

Arguments

Descriptions
Name of the environment template.

environmentTemplateName
Argument Type: String
Name of the environment template tier that must be unique among
environmentTemplateTierName

all tiers for the environment template.


Argument Type: String

Positional arguments
projectName, environmentTemplateName, environmentTemplateTierName

Response
An environmentTemplateTier element.

ec-perl
syntax:$cmdr-getEnvironmentTemplateTier(<projectName>, <environmentTemplateName>,
<environmentTemplateTierName>);

Example:
$ec->getEnvironmentTemplateTier("default", "Dev1", "Repository");

ectool
syntax: ectool createEnvironmentTemplateTier <projectName>
<environmentTemplateName> <environmentTemplateTierName>

Example:
ectool createEnvironmentTemplateTier "default" "Dev1" "Repository"
Back to Top

getEnvironmentTemplateTierMaps
Gets all the environment-template tier maps used by the specified application.
You must specify the projectNameand applicationName arguments.

Arguments

Descriptions
Name of the project that must be unique among all projects.

projectName
Argument Type: String

275

ElectricCommander

Arguments

Descriptions
Name of the application.

applicationName
Argument Type: String
(Optional)Revision IDof the versioned object.
applicationEntityRevisionId
Argument type:UUID
(Optional) <Boolean flag - 0|1|true|false>
orderByEnvironmentTemplateUs
age

If this is set to "true", the most recently used environment templates


is used.
Argument Type: Boolean

Positional arguments
projectName, applicationName

Response
One or more environmentTemplateTierMap elements.

ec-perl
syntax:$cmdr->getEnvironmentTemplateTierMaps(<projectName>, <applicationName>,
{<optionals>});

Example:
$ec-getEnvironmentTemplateTierMaps("default", "Undeploy");

ectool
syntax: ectool getEnvironmentTemplateTierMaps <projectName> <applicationName> ...

Example:
ectool getEnvironmentTemplateTierMaps "default" "Undeploy"
Back to Top

getEnvironmentTemplateTiers
Gets all the environment template tiers in the specified environment template.
You must specify the projectNameand environmentTemplateName arguments.

276

API Commands -Dynamic Enviroment

Arguments

Descriptions
Name of the project that must be unique among all projects.

projectName
Argument Type: String
Name of the environment template.
environmentTemplateName
Argument Type: String
(Optional) <Boolean flag - 0|1|true|false>
includeTemplateDetails

If this is set to "true", the response includes the template details.


Argument Type: Boolean

Positional arguments
projectName, environmentTemplateName

Response
One or more environmentTemplateTier elements.

ec-perl
syntax:$cmdr->getEnvironmentTemplateTiers(<projectName>, <environmentTemplateName>
{<optionals>});

Example:
$ec->getEnvironmentTemplateTiers("default", "Dev1");

ectool
syntax: ectool getEnvironmentTemplateTiers <projectName>
<environmentTemplateName> ...

Example:
ectool getEnvironmentTemplateTiers "default" "Dev1"
Back to Top

getEnvironmentTemplates
Gets all the environment templates in the specified project.
You must specify the projectName argument.

277

ElectricCommander

Arguments

Descriptions
Name of the project that must be unique among all projects.

projectName
Argument Type: String

Positional arguments
projectName

Response
One or more environmentTemplate elements.

ec-perl
syntax:$cmdr->getEnvironmentTemplates(<projectName>);

Example:
$ec->getEnvironmentTemplates("default");

ectool
syntax: ectool getEnvironmentTemplates <projectName>

Example:
ectool getEnvironmentTemplates "default"
Back to Top

getHook
Gets a hook associated in an entity.
You must specify the hookName argument.

Arguments

Descriptions
Name of the hook that must be unique among all hooks in the

hookName

project.
Argument Type: String
(Optional)Name of the project to which the procedure belongs.
When you use a specific version of a plugin, this is the name of the

projectName

plugin project.
Argument Type: String

278

API Commands -Dynamic Enviroment

Arguments

Descriptions
(Optional)Name of the resource template with the hook.

resourceTemplateName
Argument Type: String

Positional arguments
hookName

Response
Returns a hook for a resource template.

ec-perl
syntax:$cmdr->getHook(<hookName>, {<optionals>});

Example:
$ec->getHook("config", {resourceTemplateName => "Servers"});

ectool
syntax: ectool getHook <hookName> ...

Example:
ectool getHook "config" -- resourceTemplateName "Servers"
Back to Top

getHooks
Gets all the hook associated with an entity.

Arguments

Descriptions
(Optional)Name of the project to which the procedure belongs.
When you use a specific version of a plugin, this is the name of the

projectName

plugin project.
Argument Type: String
(Optional)Name of the resource template with the hook.

resourceTemplateName
Argument Type: String

Positional arguments
None

279

ElectricCommander

Response
Returns a hook for a resource template.

ec-perl
syntax:$cmdr->getHooks( {<optionals>});

Example:
$ec->getHooks({projectName => "default", resourceTemplateName => "AWS server
s"});

ectool
syntax: ectool getHooks ...

Example:
ectool getHooks --projectName "default" --resourceTemplateName "AWS servers"
Back to Top

getResourcePoolsInEnvironmentTier
Gets the list of resource pools in the specified environment tier.
You must specify the projectName, environmentName, and environmentTierName arguments.

Arguments

Descriptions
Name of the project that must be unique among all projects.

projectName
Argument Type: String
Name of the environment that must be unique among all
environmentName

environments.
Argument Type: String
Name of the environment tier that must be unique among all tiers

environmentTierName

for the environment.


Argument Type: String

Positional arguments
projectName, environmentName, environmentTierName

Response
One or more resourcePool elements.

280

API Commands -Dynamic Enviroment

ec-perl
syntax:$cmdr->getResourcePoolsInEnvironmentTier(<projectName>, <environmentName>,
<environmentTierName>);

Example
$cmdr->getResourcePoolsInEnvironmentTier("Default", "Production", "Web Server");

ectool
syntax:ectool getResourcePoolsInEnvironmentTier <projectName> <environmentName>
<environmentTierName>

Example
ectool getResourcePoolsInEnvironmentTier "Default" "Production" "Web Server"
Back to Top

getResourceTemplate
Gets the specified resource template.
You must specify the projectName and resourceTemplateName argument.

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String
Name for the resource template that must be unique among all
resourceTemplateName

resource templates.
Argument Type: String

Positional arguments
projectName, resourceTemplateName

Response
A resourceTemplate element.

ec-perl
syntax:$cmdr->getResourceTemplate(<projectName>, <resourceTemplateName>);

Example:
$ec->getResourceTemplate("default", "System Test");

281

ElectricCommander

ectool
syntax: ectool getResourceTemplate <projectName> <resourceTemplateName>

Example:
ectool getResourceTemplate "default" "System Test"
Back to Top

getResourceTemplates
Gets all the resource templates.

Arguments

Descriptions
(Optional)Name for the project that must be unique among all

projectName

projects.
Argument Type: String

Response
One or more resourceTemplate elements.

ec-perl
syntax:$cmdr->getResourceTemplates( {<optionals>} );

Example:
$ec->getResourceTemplates({projectName => "default"});

ectool
syntax: ectool getResourceTemplates <optionals>

Example:
ectool getResourceTemplates --projectName "default"
Back to Top

getResourceTemplatesInEnvironmentTempl
ateTier
Gets all the resource templates in the specified environment template tier.
You must specify the projectName, environmentTemplateName, and
environmentTemplateTierNamearguments.

282

API Commands -Dynamic Enviroment

Arguments

Descriptions
Name of the project that must be unique among all projects.

projectName
Argument Type: String
Name of the environment template.
environmentTemplateName
Argument Type: String
Name of the environment template tier that must be unique among
environmentTemplateTierName

all tiers for the environment template.


Argument Type: String

Positional arguments
projectName, environmentTemplateName, environmentTemplateTierName

Response
One or more resourceTemplate elements.

ec-perl
syntax:$cmdr->getResourceTemplatesInEnvironmentTemplateTier(<projectName>,
<environmentTemplateName>, <environmentTemplateTierName>);

Example:
$ec->getResourceTemplatesInEnvironmentTemplateTier("default", "Production", "Web
Server");

ectool
syntax: getResourceTemplatesInEnvironmentTemplateTier <projectName>
<environmentTemplateName> <environmentTemplateTierName>

Example:
ectool getResourceTemplatesInEnvironmentTemplateTier "default" "Production" "Web
Server"
Back to Top

getResourcesInEnvironmentTemplateTier
Gets all the resources in the specified environment template tier.
You must specify the projectName, environmentTemplateName,and
environmentTemplateTierNamearguments.

283

ElectricCommander

Arguments

Descriptions
Name for the project that must be unique among all projects.

projectName
Argument Type: String
Name of the environment template.
environmentTemplateName
Argument Type: String
Name for the environment template tier that must be unique
environmentTemplateTierName

among all tiers for the environment template.


Argument Type: String

Positional arguments
projectName, environmentTemplateName, environmentTemplateTierName

Response
One or more resource elements.

ec-perl
syntax:$cmdr->getResourcesInEnvironmentTemplateTier(<projectName>,
<environmentTemplateName>, <environmentTemplateTierName>);

Example:
$ec->getResourcesInEnvironmentTemplateTier("default", "Dev1", "Tomcat");

ectool
syntax:getResourcesInEnvironmentTemplateTier <projectName> <environmentTemplateName>
<environmentTemplateTierName>
Example:
ectool getResourcesInEnvironmentTemplateTier "default" "Dev1" "Tomcat"
Back to Top

modifyEnvTempTierResourceTempMapping
Modifies the resource count in an environment template tier.
You must specify the projectName, applicationName, environmentProjectName,
environmentTemplateName, and applicationTierName arguments.

284

API Commands -Dynamic Enviroment

Arguments

Descriptions
Number of resources to provision.

resourceCount
Argument Type: Integer
Name of the resource template that must be unique among all
resourceTemplateName

resource templates.
Argument Type: String
Name for the project that must be unique among all projects.

projectName
Argument Type: String
Name of the environment template.
environmentTemplateName
Argument Type: String
Name for the environment template tier that must be unique
environmentTemplateTierName

among all tiers for the environment template.


Argument Type: String

Positional arguments
resourceCount, resourceTemplateName, projectName, environmentTemplateName,
environmentTemplateTierName

Response
None or a status OK message.

ec-perl
syntax:$cmdr->modifyEnvTempTierResourceTempMapping(<resourceCount>,
<resourceTemplateName>, <projectName> <environmentTemplateName>
<environmentTemplateTierName>});

Example:
$ec->modifyEnvTempTierResourceTempMapping(5, "Servers", "default", Dev1", "Datab
ase");

ectool
syntax: ectool modifyEnvTempTierResourceTempMapping <resourceCount>
<resourceTemplateName> <projectName> <environmentTemplateName>
<environmentTemplateTierName>

Example:
ectool modifyEnvTempTierResourceTempMapping 5 "Servers" "default" Dev1" "Databas
e"
Back to Top

285

ElectricCommander

modifyEnvironmentTemplate
Creates an environment template.
You must specify the projectName and environmentTemplateName arguments.

Arguments

Descriptions
Name of the project that must be unique among all projects.

projectName
Argument Type: String
Name of the environment template.
environmentTemplateName
Argument Type: String
(Optional)A plain text or HTML description for this object. If using
HTML, you must surround your text with <html> ... </html>

description

tags. The only HTML tags allowed in the text are: <a> <b> <br>
<div> <dl> <font> <i> <li> <ol> <p> <pre> <span>
<style> <table> <tc> <td> <th> <tr> <ul>.
This text is not interpreted by the ElectricCommander automation
platform.
Argument type:String
New name for the environment template.

newName
Argument Type: String

Positional arguments
projectName, environmentTemplateName

Response
None or a status OK message.

ec-perl
syntax:$cmdr->modifyEnvironmentTemplate(<projectName>, <environmentTemplateName>,
{<optionals>});

Example:
$ec->modifyEnvironmentTemplate("default", "Dev1");

ectool
syntax: ectool modifyEnvironmentTemplate <projectName> <environmentTemplateName> ...

286

API Commands -Dynamic Enviroment

Example:
ectool modifyEnvironmentTemplate "default" "Dev1"
Back to Top

modifyEnvironmentTemplateTier
Gets all the environment template tiers in the specified environment template.
You must specify the projectName, environmentTemplateName, and environmentTemplateTierName
arguments.

Arguments

Descriptions
Name of the project that must be unique among all projects.

projectName
Argument Type: String
Name of the environment template.
environmentTemplateName
Argument Type: String
Name for the environment template tier that must be unique
environmentTemplateTierName

among all tiers for the environment template.


Argument Type: String
(Optional)A plain text or HTML description for this object. If using
HTML, you must surround your text with <html> ... </html>

description

tags. The only HTML tags allowed in the text are: <a> <b> <br>
<div> <dl> <font> <i> <li> <ol> <p> <pre> <span>
<style> <table> <tc> <td> <th> <tr> <ul>.
This text is not interpreted by the ElectricCommander automation
platform.
Argument type:String
New name for the environment template tier.

newName
Argument Type: String

Positional arguments
projectName, environmentTemplateName, environmentTemplateTierName

Response
None or a status OK message.

287

ElectricCommander

ec-perl
syntax:$cmdr->modifyEnvironmentTemplateTier(<projectName>,
<environmentTemplateName>, <environmentTemplateTierName>,{<optionals>});

Example:
$ec->modifyEnvironmentTemplateTier("default", "Dev1", "Database");

ectool
syntax: ectool modifyEnvironmentTemplateTier <projectName>
<environmentTemplateName> <environmentTemplateTierName> ...

Example:
ectool modifyEnvironmentTemplateTier "default" "Dev1" "Database"
Back to Top

modifyEnvironmentTemplateTierMap
Gets all the environment-template tier maps used by the specified application.
You must specify the projectName, applicationName, environmentProjectName, and
environmentTemplateName arguments.

Arguments

Descriptions
Name of the project that must be unique among all projects.

projectName
Argument Type: String
Name of the application.
applicationName
Argument Type: String
Name for the project to which the environment belongs.
environmentProjectName
Argument Type: String
Name of the environment template.
environmentTemplateName
Argument Type: String
(Optional)Revision ID of the versioned object.
applicationEntityRevisionId
Argument Type: UUID

288

API Commands -Dynamic Enviroment

Arguments

Descriptions
(Optional)Name of the tier map associated with the environment
template. If you do not specify an tier map, ElectricFlow uses a tier

tierMapName

map with a hyphenated-application-and-environment name.


Argument type:String
(Optional)List of mappings between the application tiers and the

tierMappings

environment template tiers.


Argument Type: Map

Positional arguments
projectName, applicationName, environmentProjectName, environmentTemplateName

Response
None or a status OK message.

ec-perl
syntax:$cmdr->modifyEnvironmentTemplateTierMap(<projectName>, <applicationName>,
<environmentProjectName>, <environmentTemplateName>, {<optionals>});

Example:
$ec-modifyEnvironmentTemplateTierMap("default", "Undeploy", "Beta", "Servers");

ectool
syntax: ectool modifyEnvironmentTemplateTierMap <projectName>
<applicationName> <environmentProjectName> <environmentTemplateName> ...

Example:
ectool modifyEnvironmentTemplateTierMap "default" "Undeploy" "Beta" "Servers"
Back to Top

modifyHook
Modifies an existing hook in a resource template.
You must specify the hookName, hookType, procedureName, and resourceTemplateName arguments.

289

ElectricCommander

Arguments

Descriptions
Name of the hook that must be unique among all hooks in the

hookName

project.
Argument Type: String
Type of the hook:

hookType

PRE_PROVISIONING

POST_PROVISIONING

PRE_CONFIGUARTION

POST_CONFIGUARTION

PRE_TEARDOWN

POST_TEARDOWN

Argument Type: String


Name of the procedure that the hook references.
procedureName
Argument Type: String
Name of the resource template.
resourceTemplateName
Argument Type: String
(Optional)A plain text or HTML description for this object. If using
HTML, you must surround your text with <html> ... </html>

description

tags. The only HTML tags allowed in the text are: <a> <b> <br>
<div> <dl> <font> <i> <li> <ol> <p> <pre> <span>
<style> <table> <tc> <td> <th> <tr> <ul>.
This text is not interpreted by the ElectricCommander automation
platform.
Argument type:String
(Optional)Parameters that are passed to the procedure.

hookParameter
Argument type:Map
newName

New name for the hook.


(Optional)Name of the plugin procedure. Use this argument when
the hook references a plugin procedure. The promoted version of

pluginKey

the plugin is invoked by default.


Argument Type: String

290

API Commands -Dynamic Enviroment

Arguments

Descriptions
(Optional)Name of the project to which the procedure belongs.
When you use a specific version of a plugin, this is the name of the

projectName

plugin project.
Argument Type: String
(Optional)Name of the resource template with the hook.

resourceTemplateName
Argument Type: String

Positional arguments
hookName, hookType, procedureName, resourceTemplateName

Response
None or a status OK message.

ec-perl
syntax:$cmdr->modifyHook(<hookName>, <hookType>, <procedureName>,
<resourceTemplateName>, {<optionals>});

Example:
$ec->modifyHook("config", PRE_CONFIGUARTION, "Server Start", "Servers", {newName
=> "prod_config"});

ectool
syntax: ectool modifyHook <hookName> <hookType> <procedureName> ...

Example:
ectool modifyHook "config" PRE_CONFIGUARTION "Server Start" "Servers" --newName
"prod_config"
Back to Top

Gets all the resource templates.

Arguments

Descriptions

None

Response
One or more resourceTemplate elements.

291

ElectricCommander

ec-perl
syntax:$cmdr->getResourceTemplates();

Example:
$ec->getResourceTemplates();

ectool
syntax: ectool getResourceTemplates

Example:
ectool getResourceTemplates
Back to Top

modifyResourceTemplate
Modifies the specified resource template.
You must specify the resourceTemplateName, cloudProviderProcedure, and cloudProviderConfig
argument.

Arguments

Descriptions
Name for the resource template that must be unique among all

resourceTemplateName

resource templates.
Argument Type: String
Name of the cloud-provider plugin method.

cloudProviderProcedure
Argument Type: String
Name of the cloud-provider plugin configuration.
cloudProviderConfig
Argument Type: String
(Optional)Name of the configuration-manager plugin
cfgMgrConfig

configuration.
Argument type:String
(Optional) Parameters that are passed from the configuration-

cfgMgrParameters

manager plugin to ElectricFlow.


Argument type:Map

292

API Commands -Dynamic Enviroment

Arguments

Descriptions
(Optional)Name of the configuration-manager plugin.

cfgMgrPluginKey
Argument Type: String
(Optional)Name of the configuration-manager plugin method.
cfgMgrProcedure
Argument Type: String
(Optional)Name of the project to which the configuration-manager
cfgMgrProjectName

plugin applies.
Argument Type: String
(Optional)Parameters that are passed from the cloud- provider

cloudProviderParameters

plugin to ElectricFlow.
Argument Type: Map
(Optional)Name of the cloud-provider plugin. Parameters that are

cloudProviderPluginKey

passed from the cloud-provider plugin to ElectricFlow.


Argument Type: String
(Optional)Name of the project to which the cloud-provider plugin

cloudProviderProjectName

applies.
Argument Type: String
(Optional)A plain text or HTML description for this object. If using
HTML, you must surround your text with <html> ... </html>

description

tags. The only HTML tags allowed in the text are: <a> <b> <br>
<div> <dl> <font> <i> <li> <ol> <p> <pre> <span>
<style> <table> <tc> <td> <th> <tr> <ul>.
This text is not interpreted by the ElectricCommander automation
platform.
Argument type:String
New name for the resource template.

newName
Argument type:String

Positional arguments
resourceTemplateName, cloudProviderProcedure, cloudProviderConfig

293

ElectricCommander

Response
None or a status OK message.

ec-perl
syntax:$cmdr->modifyResourceTemplate(<resourceTemplateName>
<cloudProviderProcedure>, <cloudProviderConfig>, {<optionals>});

Example:
$ec->modifyResourceTemplate("System Test", "Machine setup", "config1");

ectool
syntax: ectool modifyResourceTemplate <resourceTemplateName>
<cloudProviderProcedure> <cloudProviderConfig> ...

Example:
ectool modifyResourceTemplate "System Test" "Machine setup" "config1"
Back to Top

provisionEnvironment
Provisions an environment.
You must specify the projectName, environmentName, and environmentTemplateName arguments.

Arguments

Descriptions
Name of the project that must be unique among all projects

projectName
Argument Type: String
Name of the environment.
environmentName
Argument Type: String
Name for the environment template that must be unique among all
environmentTemplateName

environment templates.
Argument Type: String

294

API Commands -Dynamic Enviroment

Arguments

Descriptions
(Optional)Keep on error flag
Set this flag to "true" to keep the environment when an error occurs

keepOnError

.
The keepOnError value = <Boolean flag -0|1|true|false>.
Defaults to "false".
Argument type: Boolean
(Optional) Resource count for each environment template tier.

tierResourceCounts
Argument type:Map

Positional arguments
projectName, environmentName, environmentTemplateName

Response
None or a status OK message.

ec-perl
syntax:$cmdr->provisionEnvironment(<projectName>, <environmentName>,
<environmentTemplateName>, {<optionals>});

Example:
$ec->provisionEnvironment("default", "Dev_GroupA", "BuildServer");

ectool
syntax: ectool provisionEnvironment <projectName> <environmentName>
<environmentTemplateName> ...

Example:
ectool provisionEnvironment "default" "Dev_GroupA" "BuildServer"
Back to Top

provisionResourcePool
Provisions a resource pool.
You must specify the resourceCount, resourcePoolName, projectName, and resourceTemplateName
arguments.

295

ElectricCommander

Arguments

Descriptions
Number of resources to provision.

resourceCount
Argument Type: String
Name of the resource pool.
resourcePoolName
Argument Type: String
Name of the project that must be unique among all projects
projectName
Argument Type: String
Name for the resource template that must be unique among all
resourceTemplateName

resource templates.
Argument Type: String
(Optional)Keep on error flag
Set this flag to "true" to keep the environment when an error occurs

keepOnError

.
The keepOnError value = <Boolean flag -0|1|true|false>.
Defaults to "false".
Argument type: Boolean

Positional arguments
resourceCount, resourcePoolName, projectName, resourceTemplateName

Response
None or a status OK message.

ec-perl
syntax:$cmdr->provisionResourcePool(<resourceCount>, <resourcePoolName>,
<projectName>, <resourceTemplateName>,{<optionals>});

Example:
$ec->provisionResourcePool("12", "QE_build", "default",

"Servers");

ectool
syntax: ectool provisionResourcePool <resourceCount> <resourcePoolName>
<projectName> <resourceTemplateName> ...

Example:
ectool provisionResourcePool "12" "QE_build" "default" "Servers"
Back to Top

296

API Commands -Dynamic Enviroment

removeResourceFromEnvironmentTemplateT
ier
Removes a resource from the specified environment template tier.
You must specify the resourceName, projectName, environmentTemplateName, and
environmentTemplateTierNamearguments.

Arguments

Descriptions
Name of the resource that must be unique among all resources.

resourceName
Argument Type: String
Name for the project that must be unique among all projects.
projectName
Argument Type: String
Name of the environment template.
environmentTemplateName
Argument Type: String
Name for the environment template tier that must be unique
environmentTemplateTierName

among all tiers for the environment template.


Argument Type: String

Positional arguments
resourceName, projectName, environmentTemplateName, environmentTemplateTierName

Response
None or a status OK message.

ec-perl
syntax:$cmdr->removeResourceFromEnvironmentTemplateTier(<resourceName>,
<projectName>, <environmentTemplateName>, <environmentTemplateTierName>);

Example:
$ec->removeResourceFromEnvironmentTemplateTier("Resource1", "default", "Dev1", "
Tomcat");

ectool
syntax:removeResourceFromEnvironmentTemplateTier <resourceName> <projectName>
<environmentTemplateName> <environmentTemplateTierName>
Example:

297

ElectricCommander

ectool removeResourceFromEnvironmentTemplateTier "Resource1" "default" "Dev1" "T


omcat"
Back to Top

removeResourcePoolFromEnvironmentTier
Removes a resource pool from the specified environment tier.
You must specify the resourcePoolName, projectName, environmentName, and environmentTierName
arguments.

Arguments

Descriptions
Name of the resource pool that must be unique among all

resourcePoolName

resource pools.
Argument Type: String
Name of the project that must be unique among all projects.

projectName
Argument Type: String
Name of the environment that must be unique among all
environmentName

environments.
Argument Type: String
Name of the environment tier that must be unique among all tiers

environmentTierName

for the environment.


Argument Type: String

Positional arguments
resourcePoolName, projectName, environmentName, environmentTierName

Response
None or status OK message.

ec-perl
syntax:$cmdr->removeResourcePoolFromEnvironmentTier (<resourcePoolName>,
<projectName>, <environmentName>, <environmentTierName>);

Example
$cmdr->removeResourcePoolFromEnvironmentTier("pool1", "Default", "Production", "Web
Server");

298

API Commands -Dynamic Enviroment

ectool
syntax:ectool removeResourcePoolFromEnvironmentTier <resourcePoolName> <projectName>
<environmentName> <environmentTierName>

Example
ectool removeResourcePoolFromEnvironmentTier "pool1" "Default" "Production" "Web Se
rver"
Back to Top

removeResourceTemplateFromEnvironmentT
emplateTier
Removes a resource template from the specified environment template tier.
You must specify the resourceTemplateName, projectName, environmentTemplateName, and
environmentTemplateTierNamearguments.

Arguments

Descriptions
Name of the resource template that must be unique among all

resourceTemplateName

resource templates.
Argument Type: String
Name of the project that must be unique among all projects.

projectName
Argument Type: String
Name of the environment template.
environmentTemplateName
Argument Type: String
Name of the environment template tier that must be unique among
environmentTemplateTierName

all tiers for the environment template.


Argument Type: String

Positional arguments
resourceTemplateName , projectName, environmentTemplateName,
environmentTemplateTierName

Response
None or a status OK message.

299

ElectricCommander

ec-perl
syntax:$cmdr->removeResourceTemplateFromEnvironmentTemplateTier
(<resourceTemplateName>, <projectName>,
<environmentTemplateName>, <environmentTemplateTierName>);

Example:
$ec->removeResourceTemplateFromEnvironmentTemplateTier("Resource1", "default", "
Production", "WebServer");

ectool
syntax: removeResourceTemplateFromEnvironmentTemplateTier <resourceTemplateName>
<projectName> <environmentTemplateName> <environmentTemplateTierName>

Example:
ectool removeResourceTemplateFromEnvironmentTemplateTier"Resource1" "default" "P
roduction" "WebServer"
Back to Top

tearDown
Removes dynamic environments that are no longer needed.
You must specify the projectName.

Arguments

Descriptions
Name of the project that must be unique among all projects

projectName
Argument Type: String
(Optional) Name of the environment.
environmentName
Argument Type: String
(Optional) Name of the resource.
resourceName
Argument Type: String
(Optional) Name of the resource pool.
resourcePoolName
Argument Type: String

Positional arguments
projectName

Response
None or a status OK message.

300

API Commands -Dynamic Enviroment

ec-perl
syntax:$cmdr->tearDown (<projectName>, {<optionals>});

Example:
$ec->tearDown ("default", {environmentName => "Server backup"});

ectool
syntax: ectool tearDown <projectName> <optionals>

Example:
ectool tearDown "default" --environmentName "Server backup"
Back to Top

301

ElectricCommander

API Commands - Email Configuration Management


createEmailConfig
deleteEmailConfig
getEmailConfig
getEmailConfigs
modifyEmailConfig

createEmailConfig
Creates a new email configuration.
You must specify configName, mailFrom, and mailHost.

Arguments

Descriptions
The name of your email configuration.

configName
Argument type:String
A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the
description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type:String
The email address used as the email sender address for

mailFrom

notifications.
Argument type:String
The name of the email server host.

mailHost
Argument type:String
The port number for the mail server, but may not need to be
specified. The protocol software determines the default value (25
mailPort

for SMTP and 465 for SSMTP). Specify a value for this argument
when a non-default port is used.
Argument type:String

302

API Commands - Email Configuration Management

Arguments

mailProtocol

Descriptions
This is either SSMTP or SMTP (not case-sensitive). The default is
SMTP.
This can be an individual or a generic name like "Commander" name of the email user on whose behalf Commander sends email

mailUser

notifications.
Argument type:String
Password for the email user who is sending notifications.

mailUserPassword
Argument type:String

Positional arguments
configName

Response
None or status OK message.

ec-perl
syntax: $cmdr->createEmailConfig(<configName>, {<optionals>});

Example
$cmdr->createEmailConfig("testConfiguration",
{mailHost => "ectest-sol2",
mailFrom => 'commander@electric-cloud.com',
mailUser => "build@electric-cloud.com",
mailUserPassword => "mybuildmail"});

ectool
syntax: ectool createEmailConfig <configName> ...

Example
ectool createEmailConfig EmailConfig_test --mailHost ectest-sol2
--mailFrom commander@electric-cloud.com --mailUser "build@electric-cloud.com"
--mailUserPassword "mybuildmail" --description "This is a test for the email conf
ig object"
Back to Top

deleteEmailConfig
Deletes an email configuration.
You must specify a configName.

303

ElectricCommander

Arguments

Descriptions
The name of the email configuration you want to delete.

configName
Argument Type: String

Positional arguments
configName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deleteEmailConfig(<configName>);

Example
$cmdr->deleteEmailConfig("emailA");

ectool
syntax: ectool deleteEmailConfig <configName>

Example
ectool deleteEmailConfig emailA
Back to Top

getEmailConfig
Retrieves an email configuration by name.
You must specify a configName.

Arguments

Descriptions
The name of the email configuration.

configName
Argument Type: String

Positional arguments
configName

Response
Returns one emailConfig element.
Note: The mailUserPasswordattribute value is not returned or displayed by the getEmailConfigsand
getEmailConfig commands for security reasons.

304

API Commands - Email Configuration Management

ec-perl
syntax: $cmdr->getEmailConfig(<configName>);

Example
$cmdr->getEmailConfig("EmailConfig_test");

ectool
syntax: ectool getEmailConfig <configName>

Example
ectool getEmailConfig EmailConfig_test
Back to Top

getEmailConfigs
Retrieves all email configurations.

Arguments

Descriptions

None

Positional arguments
None

Response
Returns one or more emailConfig elements.
Notes:
1. The mailUserPasswordattribute value is not returned or displayed by the getEmailConfigsand
getEmailConfig commands for security reasons.
2. The configIndexattribute is managed internally by ElectricCommander and cannot be used
in any of the email configuration APIs. It is used internally to identify the order of emailConfig
objects within the list.

ec-perl
syntax: $cmdr->getEmailConfigs();

Example
$cmdr->getEmailConfigs();

ectool
syntax: ectool getEmailConfigs

305

ElectricCommander

Example
ectool getEmailConfigs
Back to Top

modifyEmailConfig
Modifies an existing email configuration.
You must specify the configName.

Arguments

Descriptions
The name of your email configuration.

configName
Argument Type: String
A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the
description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>.
Argument Type: String
The email address used as the email "sender" address for

mailFrom

notifications.
Argument Type: String
The name of the email server host.

mailHost
Argument Type: String
The port number for the mail server, but may not need to be
specified. The protocol software determines the default value (25
mailPort

for SMTP and 465 for SSMTP).


Specify a value for this argument when a non-default port is used.
Argument Type: Integer
This is either SSMTP or SMTP (not case-sensitive). The default is

mailProtocol

SMTP.
Argument Type: String

306

API Commands - Email Configuration Management

Arguments

Descriptions
The name of the email user, which can be an individual or a

mailUser

generic name such as "Commander".


Argument Type: String
The password for the email user.

mailUserPassword
Argument Type: String
New name of the email configuration.
newName
Argument Type: String

Positional arguments
configName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->modifyEmailConfig(<configName>, {<optionals>});

Example
$cmdr->modifyEmailConfig("testConfiguration",
{mailFrom => "test@my-company.com"});

ectool
syntax: ectool modifyEmailConfig <configName> ...

Example
ectool modifyEmailConfig testconfiguration --mailFrom test@my-company.com
--description "This is a Secure SMTP email config object for testing"
Back to Top

307

ElectricCommander

API Commands - Email Notifier Management


createEmailNotifier
createEventSubscription on page 312
deleteEmailNotifier
deleteEventSubscription on page 316
getEmailNotifier
getEmailNotifiers
getEventSubscription on page 322
getEventSubscriptions on page 325
modifyEmailNotifier
modifyEventSubscription on page 331
sendEmail

createEmailNotifier
Creates an email notifier attached to the specified object, such as a job, job step, project, procedure, application
process or process step, component process or process step, or a workflow.
You must specify a notifierName and object locators for a job, job step, procedure, or procedure step.

Arguments

Descriptions
The name of the email notifier.

notifierName
Argument type: String
The name of the application that is related to the target email
container. The email notifier is attached to a process or process
applicationName

step.
Argument type: String
The name of the component that is related to the target email
container. The email notifier is attached to a process or process

componentName

step.
Argument type: String
Only send mail if the condition evaluates to "true". The condition is
a string subject to property expansion. The notification will NOT be

condition

sent if the expanded string is "false" or "0". If no condition is


specified, the notification is ALWAYS sent.
Argument type: String

308

API Commands - Email Notifier Management

Arguments

Descriptions
If specified, this argument must be the name of an emailConfig
object. If it is not specified, the default is the name of the first
emailConfig object defined for the Commander server
(emailConfig objects are "ordered" Commander entities).

configName

Note: When using this argument, you must also include the
formattingTemplate or the formattingTemplateFile
argument .
Argument type: String
A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the

description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type: String
A mandatory argument for a create operation. A space-separated
list of valid email addresses, email aliases, or ElectricCommander

destinations

user names, or a string subject to property expansion that expands


into such a list.
Argument type: String
Names of the environment.

environmentNames
Argument type: Collection
Use one of these values: <onStart|onCompletion>.

eventType

onStartTriggers an event when the job or job step


begins.

onCompletionTriggers an event when the job ends,


regardless of the results.

The default is onCompletion.


Argument type: EventType

309

ElectricCommander

Arguments

Descriptions
A template for formatting email messages when an event
[notification] is triggered by the emailNotifier. Make sure the

formattingTemplate

content is formatted correctly, such as no illegal characters or


spacing.
Argument type: String
This option is supported only in Perl and ectool bindings - it is
not part of the XML protocol.
Contents of the formatting template fileis read and stored in the

formattingTemplateFile

"formatting template" field. This is an alternative argument for -formattingTemplateand is useful if the "formatting template"
field spans multiple lines.
A list of groups that receive the notification.

groupNames
Argument type: Collection
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system
jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID
The unique identifier for a job step that is assigned automatically

jobStepId

when the job step is created.


Argument type: UUID
The notification type that is stored to the ec_notificationType

notificationType

property.
Argument type: NotificationType
The name of the procedure. When using this argument, you must

procedureName

also enter the projectName.


Argument type: String
The name of the process that contains of the email notifier.

processName
Argument type: String
The name of the process step that contains of the email notifier.
processStepName
Argument type: String

310

API Commands - Email Notifier Management

Arguments

Descriptions
The name of the project. When using this argument, you must also

projectName

enter the procedureName.


Argument type: String
The name of the state definition.

stateDefinitionName
Argument type: String
The name of the state.
stateName
Argument type: String
The name of the step. When using this argument, you must also
stepName

enter projectName and procedureName.


Argument type: String
The names of the users who receive the notification.

userNames
Argument type: Collection
The name of the workflow definition.
workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String

Positional arguments
notifierName

Response
None or status OK message.

ec-perl
syntax: $cmdr->createEmailNotifier(<notifierName>, {<optionals>});

Example
$cmdr->createEmailNotifier("testNotifier",
{eventType => "onStart",
condition => "$[/javascript if(myJobStep.outcome == 'warning') 'true'; els
e 'false';]",
destinations => 'user1@abc.com user2@abc.com emailAlias1@abc.com',
configName => "testConfiguration",
projectName => "Project_test",

311

ElectricCommander

procedureName => "Procedure_test",


formattingTemplate => "Subject: Job started Notification: Job: $[/myJob/jobName] $[
/myEvent/type]
Job: $[/myJob/jobName] $[/myEvent/type] at $[/myEvent/time]",});

ectool
syntax: ectool createEmailNotifier <notifierName> ...

Example
ectool createEmailNotifier testNotifier --condition "$[/javascript if(myJobStep.out
come
== 'warning') 'true'; else 'false';]"
--destinations "user1@abc.com user2@abc.com emailAlias1@abc.com"
--configName EmailConfig_test --formattingTemplate "Notification: Job:
$[/myJob/jobName]
$[/myEvent/type] Job: $[/myJob/jobName] $[/myEvent/type] at $[/myEvent/time]"
--projectName Project_test
--procedureName Procedure_test
--description "This is a test email notifier for Job completion"
Back to Top

createEventSubscription
Creates a list of event subscriptions.
You must specify a notifierName .

Arguments

Descriptions
The name of the email notifier.

notifierName
Argument type: String
The name of the application that is related to the target email
container. The email notifier is attached to a process or process
applicationName

step.
Argument type: String
The name of the component that is related to the target email
container. The email notifier is attached to a process or process

componentName

step.
Argument type: String

312

API Commands - Email Notifier Management

Arguments

Descriptions
A list of groups that receive the notification.

groupNames
Argument type: Collection
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system
jobId

also accepts a job name assigned to the job by its name template.

Argument type: UUID


The unique identifier for a job step that is assigned automatically
jobStepId

when the job step is created.


Argument type: UUID
The name of the procedure. When using this argument, you must

procedureName

also enter projectName.


Argument type: String
The name of the process.

processName
Argument type: String
The name of the process step.
processStepName
Argument type: String
The name of the project. When using this argument, you must also
projectName

enter procedureName.
Argument type: String
The name of the state definition.

stateDefinitionName
Argument type: String
The name of the state.
stateName
Argument type: String
The name of the step. When using this argument, you must also
stepName

enter projectName and procedureName.


Argument type: String

313

ElectricCommander

Arguments

Descriptions
The names of the users who receives the notification.

userNames
Argument type: Collection
The name of the workflow definition.
workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String

Positional arguments
notifierName

Response
None or status OK message.

ec-perl
syntax: $cmdr->createEventSubscription (<notifierName>, {<optionals>});

Example
$cmdr->createEventSubscription ("testNotifier",
{applicationName => "myApp"});

ectool
syntax:ectool createEventSubscription <notifierName> ...

Example
ectool createEventSubscription testNotifier --applicationName myApp
Back to Top

deleteEmailNotifier
Deletes an email notifier from an object.
You must specify a notifierName, and you must specify locator arguments to find the email notifier you want to
delete.

314

API Commands - Email Notifier Management

Arguments

Descriptions
The name of the email notifier that you want to delete.

notifierName
Argument type: String
The name of the application that is related to the target email
container. The email notifier is attached to a process or process
applicationName

step.
Argument type: String
The name of the component that is related to the target email
container. The email notifier is attached to a process or process

componentName

step.
Argument type: String
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.
rgument type: UUID
The unique identifier for a job step that is assigned automatically

jobStepId

when the job step is created.


Argument type: UUID
The name of the procedure. When using this argument, you must

procedureName

also enter projectName.


Argument type: String
Name of the process.

processName
Argument type: String
Name of the process step.
processStepName
Argument type: String
Name of the project.
projectName
Argument type: String
Name of the state definition.
stateDefinitionName
Argument type: String

315

ElectricCommander

Arguments

Descriptions
Name of the state.

stateName
Argument type: String
Name of the step. When using this argument, you must also enter
stepName

projectName and procedureName.


Argument type: String
The name of the workflow definition.

workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String

Positional arguments
notifierName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deleteEmailNotifier(<notifierName>, { ...});

Example
$cmdr->deleteEmailNotifier(emailNotifier_stepTest, {projectName => "Project_test",
procedureName => "Procedure_test", stepName => "Step_test2"});

ectool
syntax: ectool deleteEmailNotifier <notifierName> ...

Example
ectool deleteEmailNotifier emailNotifier_stepTest --projectName Project_test
--procedureName Procedure_test --stepName Step_test2
Back to Top

deleteEventSubscription
Deletes a list of event subscriptions.
You must specify a notifierName, and you must specify locator arguments to find the email notifier you want to
delete.

316

API Commands - Email Notifier Management

Arguments

Descriptions
The name of the email notifier.

notifierName
Argument type: String
The name of the application that is related to the target email
container. The email notifier is attached to a process or process
applicationName

step.
Argument type: String
The name of the component that is related to the target email
container. The email notifier is attached to a process or process

componentName

step.
Argument type: String
A list of groups that receive the notification.

groupNames
Argument type: Collection
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system
jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID
The unique identifier for a job step that is assigned automatically

jobStepId

when the job step is created.


Argument type: String
The name of the procedure. When using this argument, you must

procedureName

also enter projectName.


Argument type: String
Name of the process.

processName
Argument type: String
Name of the process step.
processStepName
Argument type: String

317

ElectricCommander

Arguments

Descriptions
The name of the project. When using this argument, you must also

projectName

enter procedureName.
Argument type: String
The name of the state definition.

stateDefinitionName
Argument type: String
The name of the state.
stateName
Argument type: String
Name of the step. When using this argument, you must also enter
stepName

projectName and procedureName.


Argument type: String
A list of names of the users who receives the notification.

userNames
Argument type: Collection
The name of the workflow definition.
workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String

Positional arguments
notifierName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deleteEventSubscription (<notifierName>, { ...});

Example
$cmdr->deleteEventSubscription (mySubscription, {applicationName => myAppEvent});

ectool
syntax: ectool deleteEventSubscription<notifierName> ...

Example
ectool deleteEventSubscription mySubscription --applicationName myAppEvent

318

API Commands - Email Notifier Management

Back to Top

getEmailNotifier
Retrieves an email notifier from a property sheet container.
You must specify a notifierName and object locators to identify the object where the notifier is attached.

Arguments

Descriptions
The name of the email notifier.

notifierName
Argument type: String
The name of the application that is related to the target email
container. The email notifier is attached to a process or process
applicationName

step.
Argument type: String
The name of the component that is related to the target email
container. The email notifier is attached to a process or process

componentName

step.
Argument type: String
The unique Commander-generated identifier (a UUID) for a job

jobId

that is assigned automatically when the job is created. The system


also accepts a job name assigned to the job by its name template.

jobStepId

The unique identifier for a job step, assigned automatically when


the job step is created.
The name of the procedure. When using this argument, you must

procedureName

also enter projectName.


Argument type: String
Name of the process.

processName
Argument type: String
Name of the process step.
processStepName
Argument type: String

319

ElectricCommander

Arguments

Descriptions
The name of the project . When using this argument, you must also

projectName

enter procedureName.
Argument type: String
The name of the state definition.

stateDefinitionName
Argument type: String
The name of the state.
stateName
Argument type: String
Name of the step. When using this argument, you must also enter
projectName and procedureName.

stepName

Argument type: String


The name of the workflow definition.
workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String

Positional arguments
notifierName

Response
Returns one emailNotifier element.

ec-perl
syntax: $cmdr->getEmailNotifier(<notifierName>, {<optionals>});

Example
$cmdr->getEmailNotifier("Error", {projectName => "Test",
procedureName => "Build"});

ectool
syntax: ectool getEmailNotifier <notifierName> ...

Example
ectool getEmailNotifier Error --projectName Test --procedureName Build
--procedureName Procedure_test
Back to Top

320

API Commands - Email Notifier Management

getEmailNotifiers
Retrieves all email notifiers defined for the specified property sheet container.
You must specify one or more object locators.

Arguments

Descriptions
The name of the application that is related to the target email
container. The email notifier is attached to a process or process

applicationName

step.
Argument type: String
The name of the component that is related to the target email
container. The email notifier is attached to a process or process

componentName

step.
Argument type: String
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID
The unique identifier for a job step that is assigned automatically

jobStepId

when the job step is created.


Argument type: UUID
The name of the procedure. When using this argument, you must

procedureName

also enter projectName.


Argument type: String
Name of the process.

processName
Argument type: String
Name of the process step.
processStepName
Argument type: String
The name of the project . When using this argument, you must also
projectName

enter procedureName.
Argument type: String

321

ElectricCommander

Arguments

Descriptions
The name of the state definition.

stateDefinitionName
Argument type: String
The name of the state.
stateName
Argument type: String
Name of the step. When using this argument, you must also enter
stepName

projectName and procedureName.


Argument type: String
The name of the workflow definition.

workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String

Positional arguments
Arguments to locate the notifier, beginning with the top-level object locator.

Response
Returns one or more emailNotifier elements.

ec-perl
syntax: $cmdr->getEmailNotifiers({<optionals>});

Example
$cmdr->getEmailNotifiers({projectName => "Test",
procedureName => "Build"});

ectool
syntax: ectool getEmailNotifiers ...

Example
ectool getEmailNotifiers --projectName Project_test
--procedureName Procedure_test
Back to Top

getEventSubscription
Get an event subscription for the specified user or group.

322

API Commands - Email Notifier Management

You must specify a notifierName.

Arguments

Descriptions
The name of the email notifier.

notifierName
Argument type: String
The name of the application that is related to the target email
container. The email notifier is attached to a process or process
applicationName

step.
Argument type: String
The name of the component that is related to the target email
container. The email notifier is attached to a process or process

componentName

step.
Argument type: String
The name of the group that receives the notification.

groupName
Argument type: String
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system
jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID
The unique identifier for a job step that is assigned automatically

jobStepId

when the job step is created.


Argument type: UUID
The name of the procedure. When using this argument, you must

procedureName

also enter projectName.


Argument type: String
Name of the process.

processName
Argument type: String
Name of the process step.
processStepName
Argument type: String

323

ElectricCommander

Arguments

Descriptions
The name of the project . When using this argument, you must also

projectName

enter procedureName.
Argument type: String
The name of the state definition.

stateDefinitionName
Argument type: String
The name of the state.
stateName
Argument type: String
Name of the step. When using this argument, you must also enter
stepName

projectName and procedureName.


Argument type: String
The names of the users who receives the notification.

userNames
Argument type: String
The name of the workflow definition.
workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String

Positional arguments
notifierName

Response
Returns an event subscription for a user or group.

ec-perl
syntax:$cmdr->getEventSubscription (<notifierName>, {<optionals>});

Example
$cmdr->getEventSubscription("Error", {groupName => "Dev"});

ectool
syntax: ectool getEventSubscription <notifierName> ...

Example
ectool getEventSubscription Error --groupName "Dev"

324

API Commands - Email Notifier Management

Back to Top

getEventSubscriptions
Retrieves a list event subscriptions for a specified event.
You must specify a notifierName.

Arguments

Descriptions
The name of the email notifier.

notifierName
Argument type: String
The name of the application that is related to the target email
container. The email notifier is attached to a process or process
applicationName

step.
Argument type: String
The name of the component that is related to the target email
container. The email notifier is attached to a process or process

componentName

step.
Argument type: String
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.
Argument type: String
The unique identifier for a job step that is assigned automatically

jobStepId

when the job step is created.


Argument type: String
The name of the procedure. When using this argument, you must

procedureName

also enter projectName.


Argument type: String
Name of the process.

processName
Argument type: String

325

ElectricCommander

Arguments

Descriptions
Name of the process step.

processStepName
Argument type: String
The name of the project . When using this argument, you must also
projectName

enter procedureName.
Argument type: String
The name of the state definition.

stateDefinitionName
Argument type: String
The name of the state.
stateName
Argument type: String
Name of the step. When using this argument, you must also enter
stepName

projectName and procedureName.


Argument type: String
The name of the workflow definition.

workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String

Positional arguments
notifierName

Response
Returns an event subscription for a specific event.

ec-perl
syntax:$cmdr->getEventSubscriptions (<notifierName>, {<optionals>});

Example
$cmdr->getEventSubscriptions("Error", {applicationName => "Pet Store"});

ectool
syntax: ectool getEventSubscriptions <notifierName> ...

Example
ectool getEventSubscriptions Error --applicationName "Pet Store"

326

API Commands - Email Notifier Management

Back to Top

modifyEmailNotifier
Modifies an email notifier in a property sheet container specified by an emailNotifierSelector.
Note: Email notifiers are evaluated and sent based on the privileges of the notifier's owner. "Owner" can be
changed to the current user if that user has sufficient privileges to have deleted the notifier object and recreated
it.
Modify privilege on the "admin" system ACL is required.
You must specify a notifierName.

Arguments

Descriptions
The name of your email notifier.

notifierName
Argument type: String
The name of the application that is related to the target email
container. The email notifier is attached to a process or process
applicationName

step.
Argument type: String
The name of the component that is related to the target email
container. The email notifier is attached to a process or process

componentName

step.
Argument type: String
Only send mail if the condition evaluates to "true ." The condition is
a string subject to property expansion. Notification will not be sent

condition

if the expanded string is "false" or "0". If no condition is specified,


the notification is always sent.
Argument type: String

327

ElectricCommander

Arguments

Descriptions
If specified, this argument must be the name of an emailConfig
object. If it is not specified, the default is the name of the first
emailConfig object defined for the Commander server
(emailConfig objects are "ordered" Commander entities).

configName

Note: When using this argument, you must also include the
formattingTemplate or the formattingTemplateFile
argument .
Argument type: String

A plain text or HTML description for this object.


If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the
description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>.
Argument type: String
A space-separated list of valid email addresses, email aliases, or
ElectricCommander user names, or a string subject to property

destinations

expansion that expands into such a list.


Note: This argument is mandatory for the "create" operation.
Argument type: String
The names of the environments.

environmentNames
Argument type: Collection
Use one of these values: <onStart|onCompletion>.

eventType

onStartTriggers an event when the job or job step


begins.

onCompletionTriggers an event when the job ends,


regardless of the results.

The default is onCompletion.


Argument type: EventType

328

API Commands - Email Notifier Management

Arguments

Descriptions
A template for formatting email messages when an event
[notification] is triggered by the emailNotifier. Make sure the
content is formatted correctly, such as no illegal characters or

formattingTemplate

spacing.
Argument type: String

This option is supported only in Perl and ectool bindings - it is


not part of the XML protocol.
formattingTemplateFile

Contents of the formatting template fileis read and stored in the


"formatting template" field. This is an alternative argument for
formattingTemplateand is useful if the "formatting template"
field spans multiple lines.
The list of the groups that receives the notification.

groupNames
Argument type: Collection
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system
jobId

also accepts a job name assigned to the job by its name template.
Argument type: String
The unique identifier for a job step that is assigned automatically

jobStepId

when the job step is created.


Argument type: String
New name of the email notifier.

newName
Argument type: String
The notification type that is stored to the ec_notificationType
notificationType

property.
Argument type: NotificationType
The name of the procedure. When using this argument, you must

procedureName

also enter the projectName.


Argument type: String

329

ElectricCommander

Arguments

Descriptions
The name of the process that contains of the email notifier.

processName
Argument type: String
The name of the process step that contains of the email notifier.
processStepName
Argument type: String
The name of the project. When using this argument, you must also
projectName

enter the procedureName.


Argument type: String
The name of the state definition.

stateDefinitionName
Argument type: String
The name of the state.
stateName
Argument type: String
Name of the step. When using this argument, you must also enter
stepName

projectName and procedureName.


Argument type: String
The names of the users who receives the notification.

userNames
Argument type: Collection
The name of the workflow definition.
workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String

Positional arguments
notifierName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->modifyEmailNotifier(<notifierName>, {<optionals>});

330

API Commands - Email Notifier Management

Example
$cmdr->modifyEmailNotifier("testNotifier",
{eventType => "onCompletion",
projectName => "Project_test",
procedureName => "Procedure_test",});

ectool
syntax: ectool modifyEmailNotifier <notifierName> ...

Example
ectool modifyEmailNotifier testNotifier --eventType onCompletion
--projectName Project_test
--procedureName Procedure_test
Back to Top

modifyEventSubscription
Modifies a list of event subscriptions.
You must specify a notifierName.

Arguments

Descriptions
The name of the email notifier.

notifierName
Argument type: String
The name of the application that is related to the target email
container. The email notifier is attached to a process or process
applicationName

step.
Argument type: String
The name of the component that is related to the target email
container. The email notifier is attached to a process or process

componentName

step.
Argument type: String
The list of the groups that receives the notification.

groupNames

Argument type: Collection

331

ElectricCommander

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID
The unique identifier for a job step that is assigned automatically

jobStepId

when the job step is created.


Argument type: UUID
The notification type that is stored to the ec_notificationType

notificationType

property.
Argument type: NotificationType
The name of the procedure. When using this argument, you must

procedureName

also enter the projectName.


Argument type: String
The name of the process that contains of the email notifier.

processName
Argument type: String
The name of the process step that contains of the email notifier.
processStepName
Argument type: String
The name of the project. When using this argument, you must also
projectName

enter the procedureName.


Argument type: String
The name of the state definition.

stateDefinitionName
Argument type: String
The name of the state.
stateName
Argument type: String
Name of the step. When using this argument, you must also enter
stepName

projectName and procedureName.


Argument type: String

332

API Commands - Email Notifier Management

Arguments

Descriptions
The names of the users who receives the notification.

userNames
Argument type: Collection
The name of the workflow definition.
workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String

Positional arguments
notifierName

Response
Returns an event subscription for a user or group.

ec-perl
syntax:$cmdr->modifyEventSubscription (<notifierName>, {<optionals>});

Example
$cmdr->modifyEventSubscription("Error", {componentName => "Config files"});

ectool
syntax: ectool modifyEventSubscription <notifierName> ...

Example
ectool getEventSubscription Error --componentName "Config files"
Back to Top

sendEmail
Facilitates sending an email from the command-line or a Command Job Step without setting up an Email
Notifier.
This API is more dynamic than an email notifier because you do not need to setup some kind of a
template beforehand. This API also makes sending email attachments easier than using a notifier template.
Instead of (or in addition to) specifying a configName, any of the configuration options for an email
configuration can be specified as options.
These options are: mailHost,mailPort, mailFrom, mailUser, and mailUserPassword.
Note: If both a configName and some or all of the configuration options are specified, the specified options
override values stored in the configuration. In this case, the user must have both modify and execute
permission on the configuration.

333

ElectricCommander

Specify the options you need to create the type of email message you want to send.

Arguments

Descriptions
One or more client-side files to send as attachments. The filename
extension is examined to determine the content type. You can

attachment

enter this argument more than once to specify multiple


attachments.
Argument type: Collection
A "Bcc" recipient for the email message. The recipient can be a
user name, group name or complete email address. You can enter

bcc

this argument more than once to specify multiple recipients.


Argument type: Collection
A "Cc" recipient for the email message. The recipient can be a user
name, group name or complete email address. You can enter this

cc

argument more than once to specify multiple recipients.


Argument type: Collection
The name of the email configuration. If no configuration is
specified, the configuration named "default" is used.

configName

Note: The user must have execute permission on the


configuration.
Argument type: String
An RFC822 email header line (for example: "reply-to:

header

user@host.com"). This option can be specified multiple times.


Argument type: Collection
The body of a simple HTML message.

html
Argument type: String

htmlFile

334

Reads the specified client-side file and uses it as the body of a


simple HTML message.

API Commands - Email Notifier Management

Arguments

Descriptions
Inline attachments in this format: <contentId>=<fileName>
[<contentId>=<fileName> ...].
One or more inline attachments specified as a contentId and a
client-side filename. The filename extension is examined to
determine the content-type. The contentId can be referenced in
an HTML body using the cid:protocol.

inline

For example:
<img src=cid:myImage"> could reference
--inlinemyImage=image.jpg
You can enter this argument more than once to add multiple
attachments.
Argument type: Collection
The email address used in the "From" header to use when sending
Commander notification email. When the email configuration is

mailFrom

specified, this value overrides the value in the configuration.


Argument type: String
The name of the email server host to use when the configName is
not specified. When the email configuration is specified, this value

mailHost

overrides the value in the configuration.


Argument type: String
The mail server port to use when the configName is not specified.
When the email configuration is specified, this value overrides the

mailPort

value in the configuration.


Argument type: Integer
The name of the mail protocol that must be SMTP or SMTPS.
When the email configuration is specified, this value overrides the

mailProtocol

value in the configuration.


Argument type: String
The name of the email user for whom ElectricCommander sends
email notifications. Commander also uses it when authenticating

mailUser

to the mail server. When the email configuration is specified, this


value overrides the value in the configuration.
Argument type: String

335

ElectricCommander

Arguments

Descriptions
The password that ElectricCommander uses when when
authenticating to the mail server. When the email configuration is

mailUserPassword

specified, this value overrides the value in the configuration.


Argument type: String
The multipart message mode:
<none|mixed|related|mixedRelated>

multipartMode

none Non-multipart message

mixedSingle-root multipart element of type "mixed". Texts,


inline elements, and attachments will be added to this root
element.

related Multipart message with a single root multipart


element of "related" type. Texts, inline elements, and
attachments will be added to this root element. It works on
most mail clients, except Lotus Notes.

mixedRelatedMultipart "mixed" element with a nested


multipart "related" element. Texts and inline elements will
be added to the nested "related' element, while
attachments will be added to the "mixed' root element. It
works on most mail clients other than Mac Mail and some
situations on Outlook. If you experience problems, use the
"related" value.

Note: multipartMode defaults to none unless there are


multiple parts, in which case it defaults to mixedRelated. If
both text and html arguments are specified, both values are
sent as alternates in a multipart message.
Argument type: MultipartMode
A raw RFC 822 email message including headers to use as the
raw

basis for the email message. Additional options can be applied to


this message.
Argument type: String

rawFile

Reads the specified client-side file and uses it as the entire mail
message, including headers.
The subject of the email message.

subject
Argument type: String

336

API Commands - Email Notifier Management

Arguments

Descriptions
The body of a simple text message.

text
Argument type: String

textFile

Reads the specified client-side file and uses it as the body of a


simple text message.
A "To" recipient for the email message. The recipient can be a
user, group name or complete email address. You can enter this

to

argument more than once to specify multiple recipients.


Argument type: Collection

Positional arguments
None

Response
None or status OK message.

ec-perl
syntax: $cmdr->sendEmail
Note: The to, cc, bcc, header, and attachment options can have multiple values specified as
an array. The inline option can have multiple values specified as an array of hashes with contentId
and fileName values.

Example
$cmdr->sendEmail({
configName => 'config1',
subject => 'Test message',
to => ['user1', 'user2'],
html => '<html><body>Some stuff <img src=cid:image1/body/html',
inline => [{contentId => 'image1', fileName => 'image1.jpg'},
{contentId => 'image2', fileName => 'image2.jpg'}],
attachment => ['report1.html', 'report2.pdf']
})

ectool
syntax: ectool sendEmail
Note:Options that take multiple values may be specified as a single option with each value as a separate
argument or as multiple options, each with a single argument.

Examples
ectool sendEmail \
--to user1 \
--to user2 \

337

ElectricCommander

--subject Test \
--html '<html><body>Some stuff <img src="cid:image1"></body></html>' \
--inline image1=image1.jpg \
--inline image2=image2.jpg \
--attachment report1.html \
--attachment report2.pdf

ectool sendEmail \
--to user1 user2 \
--subject Test \
--html '<html><body>Some stuff <img src="cid:image1"></body></html>' \
--inline image1=image1.jpg image2=image2.jpg \
--attachment report1.html report2.pdf
Back to Top

338

API Commands - Environment

API Commands - Environment


createEnvironment on page 339
createEnvironmentInventoryItem on page 340
deleteEnvironment on page 342
deleteEnvironmentInventoryItem on page 343
getEnvironment on page 344
getEnvironmentApplications on page 345
getEnvironmentInventory on page 345
getEnvironmentInventoryItem on page 346
getEnvironmentInventoryItems on page 347
getEnvironments on page 348
modifyEnvironment on page 349
modifyEnvironmentInventoryItem on page 350

createEnvironment
Creates a new environment.
Required Arguments
projectName
Description: Name for the project that must be unique among all projects.
Argument Type: String
environmentName
Description: Name of the environment that must be unique among all projects.
Argument Type: String
Optional Arguments
applicationName
Description: Create environment from the specified application that must be unique among all projects.
Argument Type: String
applicationProjectName
Description: Name of the project that contains the application.
Argument Type: String

339

ElectricCommander

description
Description: Comment text describing this object; not interpreted by ElectricCommander.
Argument Type: String
environmentEnabled
Description: True to enable the environment.
Argument Type: Boolean
Response
Returns an environment element.
ec-perl
Syntax:
$<object>->createEnvironment(<projectName>, <environmentName>,
{<optionals>});
Example:
$ec->createEnvironment("Default", "aEnv", {environmentEnabled => "true", descrip
tion => "aDescription"});
ectool
Syntax:
ectool createEnvironment <projectName> <environmentName> [optionals...]
Example:
ectool createEnvironment default newEnv --environmentEnabled true --description
exampleText

createEnvironmentInventoryItem
Creates a new environment inventory item.
Required Arguments
projectName
Description: Name for the project that must be unique among all projects.
Argument Type: String
environmentName
Description: Name of the environment.
Argument Type: String
applicationName
Description: Name of the application that owns the inventory item.

340

API Commands - Environment

Argument Type: String


componentName
Description: Component that owns the inventory item.
Argument Type: String
resourceName
Description: Resource where the item is installed.
Argument Type: String
Optional Arguments
applicationTierName
Description: Name of the application tier.
Argument Type: String
artifactName
Description: Artifact name for the inventory item.
Argument Type: String
artifactVersion
Description: Artifact version for the inventory item.
Argument Type: String
artifactSource
Description: Source of the artifact.
Argument Type: String
artifactUrl
Description: URL of the artifact.
Argument Type: String
description
Description: Comment text describing this object; not interpreted by ElectricCommander.
Argument Type: String
status
Description: Status of the item.
Argument Type: String
Response
Returns an environment inventory item.

341

ElectricCommander

ec-perl
Syntax:
$<object>->createEnvironmentInventoryItem(<projectName>, <environmentName>,
<applicationName>, <componentName>, <resourceName>, {<optionals>});
Example:
$ec->createEnvironmentInventoryItem("Default", "aEnv", "App1", "ComponentA",
"ResourceA", {artifactName =>"Artifact1", artifactVersion=>"V3", description =>
"aDescription"});
ectool
Syntax:
ectool createEnvironmentInventoryItem <projectName> <environmentName>
<applicationName> <componentName> <resourceName> [optionals...]
Example:
ectool createEnvironmentInventoryItem Default aEnv App1 ComponentA ResourceA
-- artifactName Artifact1 --artifactVersion V3 --description aDescription

deleteEnvironment
Deletes an environment.
Required Arguments
projectName
Description: Name for the project; must be unique among all projects.
Argument Type: String
environmentName
Description: Name of the environment; must be unique among all projects.
Argument Type: String
Optional Arguments
None
Response
None or a status OK message.
ec-perl
Syntax:
$<object>->deleteEnvironment(<projectName>, <environmentName>);
Example:
$cmdr->deleteEnvironment("Default", "envToDelete");

342

API Commands - Environment

ectool
Syntax:
ectool deleteEnvironment <projectName>
<environmentName>
Example:
ectool deleteEnvironment default envToDelete

deleteEnvironmentInventoryItem
Delete an inventory item.
Required Arguments
projectName
Description: Name for the project; must be unique among all projects.
Argument Type: String
environmentName
Description: Name of the environment.
Argument Type: String
applicationName
Description: Name of the application that owns the inventory item.
Argument Type: String
componentName
Description: Name of the component that owns the inventory item.
Argument Type: String
resourceName
Description: Name of the resource where the item is installed.
Argument Type: String
Optional Arguments
None
Response
None or a status OK message.
ec-perl
Syntax:
$<object>->deleteEnvironmentInventoryItem(<projectName>, <environmentName>,
<applicationName>, <componentName>, <resourceName>);

343

ElectricCommander

Example:
$cmdr->deleteEnvironmentInventoryItem("Default", "Env1A", "AppTest1",
"Component1", "Server1");
ectool
Syntax:
ectool deleteEnvironmentInventoryItem <projectName> <environmentName>
<applicationName> <componentName> <resourceName>
Example:
ectool deleteEnvironmentInventoryItem "Default" "Env1A" "AppTest1" "Component1"
"Server1"

getEnvironment
Retrieves an environment by name.
Required Arguments
projectName
Description: Name for the project; must be unique among all projects.
Argument Type: String
environmentName
Description: Name of the environment; must be unique among all projects.
Argument Type: String
Optional Arguments
None
Response
Retrieves an environment element.
ec-perl
Syntax:
$<object>->getEnvironment(<projectName>, <environmentName>);
Example:
$ec->getEnvironment("Default", "aEnv");
ectool
Syntax:
ectool getEnvironment <projectName> <environmentName>
Example:
ectool getEnvironment default newEnv

344

API Commands - Environment

getEnvironmentApplications
Retrieves a list of applications installed on the given environment.
projectName
Description: Name for the project; must be unique among all projects.
Argument Type: String
environmentName
Description: Name of the environment.
Argument Type: String
Optional Arguments
None
Response
Retrieves a list of applications for the specified environment.
ec-perl
Syntax:
$<object>->getEnvironmentApplications(<projectName>, <environmentName>);
Example:
$ec->getEnvironmentApplications("Default", "aEnv");
ectool
Syntax:
ectool getEnvironmentApplications <projectName> <environmentName>
Example:
ectool getEnvironmentApplications default newEnv

getEnvironmentInventory
Retrieves a per-component grouped list of inventory items.
Required Arguments
projectName
Description: Name for the project; must be unique among all projects.
Argument Type: String
environmentName
Description: Name of the environment.
Argument Type: String

345

ElectricCommander

applicationName
Description: Name of the application.
Argument Type: String
Optional Arguments
None
Response
Retrieves a per-component grouped list of inventory items.
ec-perl
Syntax:
$<object>->getEnvironmentInventory(<projectName>, <environmentName>,
<applicationName>);
Example:
$ec->getEnvironmentInventory("Default", "aEnv", "App1");
ectool
Syntax:
ectool getEnvironmentInventory <projectName> <environmentName> <applicationName>
Example:
ectool getEnvironmentInventory default newEnv App1

getEnvironmentInventoryItem
Retrieves an inventory item.
Required Arguments
projectName
Description: Name for the project; must be unique among all projects.
Argument Type: String
environmentName
Description: Name of the environment.
Argument Type: String
applicationName
Description: Name of the application that owns the inventory item.
Argument Type: String
componentName
Description: Name of the component that owns the inventory item.

346

API Commands - Environment

Argument Type: String


resourceName
Description: Name of the resource where the item is installed.
Argument Type: String
Optional Arguments
None
Response
Retrieves an inventory item.
ec-perl
Syntax:
$<object>->getEnvironmentInventoryItem(<projectName>,
<environmentName>, <applicationName>, <componentName>,
<resourceName>);
Example:
$ec->getEnvironmentInventoryItem("Default", "aEnv", "App1", "Component1", "Serve
r1");
ectool
Syntax:
ectool getEnvironmentInventoryItem <projectName> <environmentName>
<applicationName> <componentName> <resourceName>
Example:
ectool getEnvironmentInventoryItem default newEnv App1 Component1 Server1

getEnvironmentInventoryItems
Retrieves all inventory items for a given environment.
Required Arguments
projectName
Description: Name for the project; must be unique among all projects.
Argument Type: String
environmentName
Description: Name of the environment.
Argument Type: String
Optional Arguments
None

347

ElectricCommander

Response
Retrieves all inventory items for the specified environment.
ec-perl
Syntax:
$<object>->getEnvironmentInventoryItems(<projectName>,
<environmentName>);
Example:
$ec->getEnvironmentInventoryItems("Default", "aEnv");
ectool
Syntax:
ectool getEnvironmentInventoryItems <projectName> <environmentName>
Example:
ectool getEnvironmentInventoryItems default newEnv

getEnvironments
Retrieves all environments in a project.
Required Arguments
projectName
Description: Name for the project; must be unique among all projects.
Argument Type: String
Optional Arguments
None
Response
Retrieves zero or more environment elements.
ec-perl
Syntax:
$<object>->getEnvironments(<projectName>);
Example:
$ec->getEnvironments("Default");
ectool
Syntax:
ectool getEnvironments <projectName>
Example:
ectool getEnvironments default

348

API Commands - Environment

modifyEnvironment
Modifies an environment.
Required Arguments
projectName
Description: Name for the project; must be unique among all projects.
Argument Type: String
environmentName
Description: Name of the environment; must be unique among all projects.
Argument Type: String
Optional Arguments
description
Description: Comment text describing this object; not interpreted at all by ElectricCommander.
Argument Type: String
environmentEnabled
Description: True to enable the environment.
Argument Type: Boolean
newName
Description: New name for an existing object that is being renamed.
Argument Type: String
Response
Retrieves an updated environment element.
ec-perl
Syntax:
$<object>->modifyEnvironment(<projectName>, <environmentName>,
{<optionals>});
Example:
$ec->modifyEnvironment("Default", "aEnv", {newName => "upDatedName",
description => "aNewDescription"});
ectool
Syntax:
ectool modifyEnvironment <projectName> <environmentName>
[optionals...]

349

ElectricCommander

Example:
ectool modifyEnvironment default testEnv --newName modEnv
--description exampleText

modifyEnvironmentInventoryItem
Modifies an existing environment inventory item.
Required Arguments
projectName
Description: Name for the project; must be unique among all projects.
Argument Type: String
environmentName
Description: Name of the environment.
Argument Type: String
applicationName
Description: Name of the application that owns the inventory item.
Argument Type: String
componentName
Description: Name of the component that owns the inventory item.
Argument Type: String
resourceName
Description: Name of the resource where the item is installed.
Argument Type: String
Optional Arguments
applicationTierName
Description: Name of the application tier.
Argument Type: String
artifactName
Description: Name of the artifact for the inventory item.
Argument Type: String
artifactSource
Description: Source of the artifact.

350

API Commands - Environment

Argument Type: String


artifactUrl
Description: URL of the artifact.
Argument Type: String
artifactVersion
Description: Version of the artifact for the inventory item.
Argument Type: String
description
Description: Comment text describing this object; not interpreted by ElectricCommander.
Argument Type: String
status
Description: Inventory deployment status.
Argument Type: JobOutcome
Response
Retrieves an updated environment inventory item.
ec-perl
Syntax:
$<object>->modifyEnvironmentInventoryItem(<projectName>, <environmentName>,
<applicationName>, <componentName>, <resourceName>, <artifactName>,
<artifactVersion> {<optionals>});
Example:
$ec->modifyEnvironmentInventoryItem("Default", "aEnv", "App1", "Component1",
"Server1", "Artifact1", "V3");
ectool
Syntax:
ectool modifyEnvironmentInventoryItem <projectName> <environmentName>
<applicationName> <componentName> <resourceName> <artifactName>
<artifactVersion> [optionals...]

Example:
ectool modifyEnvironmentInventoryItem default testEnv App1 Component1 Server1
Artifact1 V3

351

ElectricCommander

API Commands - Environment Tier


createEnvironmentTier on page 352
deleteEnvironmentTier on page 353
getEnvironmentTier on page 354
getEnvironmentTiers on page 355
modifyEnvironmentTier on page 355

createEnvironmentTier
Creates a new environment tier.
Required Arguments
projectName
Description: Name for the project; must be unique among all projects.
Argument Type: String
environmentName
Description: Name of the environment which must be unique among all environments for the project; must
be unique among all projects.
Argument Type: String
environmentTierName
Description: Name of the environment tier; must be unique among all tiers for the environment.
Argument Type: String
Optional Arguments
description
Description: Comment text describing this object; not interpreted at all by ElectricCommander.
Argument Type: String
Response
Returns an environment tier element.
ec-perl
Syntax:
$<object>->createEnvironmentTier(<projectName>, <environmentName>, <environmentT
ierName>, {<optionals>});
Example:

352

API Commands - Environment Tier

$ec->createEnvironmentTier("Default", "newEnv", "envTier2", {description => "Des


cription"});
ectool
Syntax:
ectool createEnvironmentTier <projectName> <environmentName>
<environmentTierName> [optionals...]
Example:

deleteEnvironmentTier
Deletes an environment tier.
Required Arguments
projectName
Description: Name of the project; must be unique among all projects.
Argument Type: String
environmentName
Description: Name of the environment that must be unique among all environments for the project; must be
unique among all projects.
Argument Type: String
environmentTierName
Description: Name of the environment tier; must be unique among all tiers for the environment.
Argument Type: String
Optional Arguments
None
Response
None or a status OK message.
ec-perl
Syntax:
$<object>->deleteEnvironmentTier(<projectName>, <environmentName>, <environmentT
ierName>);
Example:
$ec->deleteEnvironmentTier("Default", "newEnv", "tierToDelete");
ectool
Syntax:
ectool deleteEnvironmentTier <projectName> <environmentName>
<environmentTierName>

353

ElectricCommander

Example:
ectool deleteEnvironmentTier default newEnv

tierToDelete

getEnvironmentTier
Retrieves an environment tier by name.
Required Arguments
projectName
Description: Name of the project; must be unique among all projects.
Argument Type: String
environmentName
Description: Name of the environment which must be unique among all environments for the project; must
be unique among all projects.
Argument Type: String
environmentTierName
Description: Name of the environment tier; must be unique among all tiers for the environment.
Argument Type: String
Optional Arguments
None
Response
Retrieves an environment tier element.
ec-perl
Syntax:
$<object>->getEnvironmentTier(<projectName>, <environmentName>, <environmentTier
Name>);
Example:
$ec->getEnvironmentTier("Default", "newEnv", "envTier2");
ectool
Syntax:
ectool getEnvironmentTier <projectName> <environmentName> <environmentTierName>
Example:
ectool getEnvironmentTier default newEnv envTier1

354

API Commands - Environment Tier

getEnvironmentTiers
Retrieves all environment tiers in an environment.
Required Arguments
projectName
Description: Name of the project; must be unique among all projects.
Argument Type: String
environmentName
Description: Name of the environment that must be unique among all environments for the project; must be
unique among all projects.
Argument Type: String
Optional Arguments
None
Response
Retrieves zero or more environment tier elements.
ec-perl
Syntax:
$<object>->getEnvironmentTiers(<projectName>, <environmentName>);
Example:
$ec->getEnvironmentTiers("Default", "newEnv");
ectool
Syntax:
ectool getEnvironmentTiers <projectName> <environmentName>
Example:
ectool getEnvironmentTiers default newEnv

modifyEnvironmentTier
Modifies an environment tier.
Required Arguments
projectName
Description: Name of the project; must be unique among all projects.
Argument Type: String
environmentName

355

ElectricCommander

Description: Name of the environment which must be unique among all environments for the project; must
be unique among all projects.
Argument Type: String
environmentTierName
Description: Name of the environment tier; must be unique among all tiers for the environment.
Argument Type: String
Optional Arguments
description
Description: Comment text describing this object; not interpreted at all by ElectricCommander.
Argument Type: String
newName
Description: New name for an existing object that is being renamed.
Argument Type: String
Response
Retrieves an updated environment tier element.
ec-perl
Syntax:
$<object>->modifyEnvironmentTier(<projectName>, <environmentName>, <environmentT
ierName>, {<optionals>});
Example:
$ec->modifyEnvironmentTier("Default", "newEnv", "envTier2", {newName => "envTier
B", description => "New_Description"});
ectool
Syntax:
ectool modifyEnvironmentTier <projectName> <environmentName> <environmentTierNam
e> [optionals...]
Example:
ectool modifyEnvironmentTier default newEnv
ext --newName envTierA

356

envTier1 --description new_exampleT

API Commands - Gateways and Zones Management

API Commands - Gateways and Zones Management


createGateway

createZone

deleteGateway

deleteZone

getGateway

getZone

getGateways

getZones
modifyZone

modifyGateway

createGateway
Creates a new gateway.
Scenario: You have two zones, ZoneA and ZoneB. ResourceA in ZoneA is accessible from ResourceB in
ZoneB, and converselycommunication between specified gateway resources is enabled with host/port
information recorded in each resource object. Other resources in each zone are restricted to talking to
resources within their zone only. Creating a gateway between ResourceA and ResourceB to link the two zones
enables resources from one zone to communicate with the other using ResourceA and ResourceB.
You must specify gatewayName.

Arguments

Descriptions
The name of the gateway that must be unique among all gateway

gatewayName

names.
Argument type:String
(Optional) A plain text or HTML description for this object. If using
HTML, you must surround your text with <html> ... </html>

description

tags. The only HTML tags allowed in the text are: <a> <b> <br>
<div> <dl> <font> <i> <li> <ol> <p> <pre> <span>
<style> <table> <tc> <td> <th> <tr> <ul>.
Argument type:String
(Optional) <Boolean flag - 0|1|true|false > If set to 1 or "true",

gatewayDisabled

the gateway is disabled.


Argument type:Boolean

357

ElectricCommander

Arguments

Descriptions
(Optional) The domain name or IP of the agent where Resource1
resides. This host name is used by Resource2 to communicate

hostName1

with Resource1. Do not specify this option is you want to use the
host name from the Resource1 definition.
Argument type:String
(Optional) The domain name or IP of the agent where Resource2
resides. This host name is used by Resource1 to communicate

hostName2

with Resource2. Do not specify this option is you want to use the
host name from the Resource2 definition.
Argument type:String
(Optional) The port number used by Resource1. The default is the

port1

port number used by the resource.


Argument type:Integer
(Optional) The port number used by Resource2. The default is the

port2

port number used by the resource.


Argument type: Integer
(Optional) Name of first resource in the gateway specification. Do
not include spaces in the resource name.

resourceName1

Other resources in this resource's zone forward messages through


this resource to agents in the resourceName2 zone.
Argument type:String
(Optional) Name of second resource in the gateway specification.
Do not include spaces in the resource name.

resourceName2

Other resources in this resource's zone forward messages through


this resource to agents in the resourceName1 zone.
Argument type:String

Positional arguments
gatewayName

Response
Returns a gateway object.

358

API Commands - Gateways and Zones Management

ec-perl
syntax: $cmdr->createGateway (<gatewayName>, {optionals>});

Example
$cmdr->createGateway ("AB_Gateway",
{description => "Gateway linking ZoneA and ZoneB",
resourceName1 => "ResourceA",
resourceName2 => "ResourceB"});

ectool
syntax: ectool createGateway <gatewayName> ...

Example
ectool createGateway AB_Gateway --description "Gateway linking ZoneA and ZoneB" --r
esourceName1 "ResourceA" --resourceName2 "ResourceB"
ectool createGateway AB_Gateway --description "Gateway linking ZoneA and ZoneB"
--resourceName1 "ResourceA"
--resourceName2 "ResourceB"

Back to Top

deleteGateway
Deletes a gateway.
You must enter a gatewayName.

Arguments

Descriptions
The name of the gateway to delete.

gatewayName
Argument type:String

Positional arguments
gatewayName

Response
None

ec-perl
syntax: $cmdr->deleteGateway (<gatewayName>);

Example
$cmdr->deleteGateway ("AB_Gateway");

359

ElectricCommander

ectool
syntax: ectool deleteGateway <gatewayName>

Example
ectool deleteGateway "AB_Gateway"

Back to Top

getGateway
Finds a gateway by name.
You must specify a gatewayName.

Arguments

Descriptions
The name of the gateway.

gatewayName
Argument type:String

Positional arguments
gatewayName

Response
Returns one gateway element.

ec-perl
syntax: $cmdr->getGateway (<gatewayName>);

Example
$cmdr->getGateway ("AB_Gateway");

ectool
syntax: ectool getGateway <gatewayName>

Example
ectool getGateway AB_Gateway

Back to Top

getGateways
Retrieves all gateways.

360

API Commands - Gateways and Zones Management

Arguments

Descriptions

None

Positional arguments
None.

Response
Returns one or more gateway elements.

ec-perl
syntax: $cmdr->getGateways();

Example
$cmdr->getGateways();

ectool
syntax: ectool getGateways

Example
ectool getGateways

Back to Top

modifyGateway
Modifies an existing gateway.
You must specify a gatewayName.

Arguments

Descriptions
The name of the gateway.

gatewayName
Argument type:String
A plain text or HTML description for this object. If using HTML, you
must surround your text with <html> ... </html> tags. The only
description

HTML tags allowed in the text are: <a> <b> <br> <div> <dl>
<font> <i> <li> <ol> <p> <pre> <span> <style>
<table> <tc> <td> <th> <tr> <ul>.
Argument type:String

361

ElectricCommander

Arguments

Descriptions
<Boolean flag - 0|1|true|false > If set to 1 or "true," the

gatewayDisabled

gateway is disabled.
Argument type:Boolean
The domain name or IP address of the agent where Resource1
resides. This host name is used by Resource2 to communicate

hostName1

with Resource1. Do not specify this option is you want to use the
host name from the Resource1 definition.
Argument type:String
The domain name or IP address of the agent where Resource2
resides. This host name is used by Resource1 to communicate

hostName2

with Resource2. Do not specify this option is you want to use the
host name from the Resource2 definition.
Argument type:String
New name of the gateway.

newName
Argument type:String
The port number used by Resource1. The default is the port
port1

number used by the resource.


Argument type:Integer
The port number used by Resource2. The default is the port

port2

number used by the resource.


Argument type:Integer
Name of first resource in the gateway specification. Do not include
spaces in the resource name.

resourceName1

Other resources in this resource's zone forward messages through


this resource to agents in the resourceName2 zone.
Argument type:String
Name of second resource in the gateway specification. Do not
include spaces in the resource name.

resourceName2

Other resources in this resource's zone forward messages through


this resource to agents in the resourceName1 zone.
Argument type:String

362

API Commands - Gateways and Zones Management

Positional arguments
gatewayName

Response
An updated gateway object.

ec-perl
syntax: $cmdr->modifyGateway (<gatewayName>, {...});

Example
$cmdr->modifyGateway ("AB_Gateway",
{description=> "Gateway linking zoneA and zoneB",
resourceName1=> "ResourceA",
resourceName2=> "ResourceB"});,

ectool
syntax: ectool modifyGateway <gatewayName> ...

Example
ectool modifyGateway AB_Gateway --description "Gateway linking ZoneA and ZoneB"
--resourceName1 "ResourceA"
--resourceName2 "ResourceB"

Back to Top

createZone
Creates a new zone.
You must specify a zoneName.

Arguments

Descriptions
The unique name of the zone.

zoneName
Argument type:String
A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the
description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>.
Argument type:String

363

ElectricCommander

Positional arguments
zoneName

Response
Returns a zone object.

ec-perl
syntax: $cmdr->createZone (<zoneName>, {...});

Example
$cmdr->createZone("DevZone", {description => "Zone containing resources that the de
v group uses."});

ectool
syntax: ectool createZone <zoneName> ...

Example
ectool createZone DevZone --description "Zone containing resources that the dev gro
up uses."

Back to Top

deleteZone
Deletes an existing zone.
You must specify a zoneName.

Arguments

Descriptions
The name of the zone to delete.

zoneName
Argument type:String

Positional arguments
zoneName

Response
None

ec-perl
syntax: $cmdr->deleteZone (<zoneName>);

Example
$cmdr->deleteZone ("DevZone");

364

API Commands - Gateways and Zones Management

ectool
syntax: ectool deleteZone <zoneName>

Example
ectool deleteZone DevZone

Back to Top

getZone
Finds a zone by name.
You must specify a zoneName.

Arguments

Descriptions
The name of the zone.

zoneName
Argument type:String

Positional arguments
zoneName

Response
Returns a zone element, including a list of resources belonging to the zone.

ec-perl
syntax: $cmdr->getZone (<zoneName>);

Example
$cmdr->getZone ("DevZone");

ectool
syntax: ectool getZone <zoneName>

Example
ectool getZone DevZone

Back to Top

getZones
Retrieves all zones.

365

ElectricCommander

Arguments

Descriptions

None

Positional arguments
None

Response
Returns a zone object.

ec-perl
syntax: $cmdr->getZones();

Example
$cmdr->getZones();

ectool
syntax: ectool getZones

Example
ectool getZones

Back to Top

modifyZone
Modifies an existing zone.
You must specify a zoneName.

Arguments

Descriptions
The name of this zone.

zoneName
Argument type:String
A plain text or HTML description for this object. If using HTML, you
must surround your text with <html> ... </html> tags. The only
description

HTML tags allowed in the text are: <a> <b> <br> <div> <dl>
<font> <i> <li> <ol> <p> <pre> <span> <style>
<table> <tc> <td> <th> <tr> <ul>.
Argument type:String

366

API Commands - Gateways and Zones Management

Arguments

Descriptions
New name of the zone.

newName
Argument type:String

Positional arguments
zoneName

Response
Returns an updated zone element.

ec-perl
syntax: $cmdr->modifyZone (<zoneName>, {...});

Example
$cmdr->modifyZone ("DevZone", {description => "Zone containing resources that the d
ev group uses."});

ectool
syntax: ectool modifyZone <zoneName> ...

Example
ectool modifyZone DevZone --description "Zone containing resources that the dev gro
up uses."

Back to Top

367

ElectricCommander

API Commands - Job Management


abortAllJobs
abortJob
abortJobStep
deleteJob
findJobSteps
getJobDetails
getJobInfo
getJobNotes
getJobs

getJobsForSchedule
getJobStatus
getJobStepDetails
getJobStepStatus
getJobSummaries
getJobSummary
moveJobs
runProcedure
setJobName

External Job APIs


completeJob
completeJobStep
createJob
createJobStep

modifyJob
modifyJobStep
waitForJob

abortAllJobs
Aborts all running jobs.

Arguments

Descriptions
<Boolean flag - 0|1|true|false > If this is set to 1, the job aborts
immediately. A zero value allows jobs to terminate in an orderly

force

way, executing steps marked always run".


Argument type: Boolean
A string added to the aborted job/jobstep that describes or
records the reason for the abort. The server records this value, but

reason

places no meaning on the string, which is similar to a text


description.
Argument type: String

Positional arguments
None

Response
None or status OK message.

368

API Commands - Job Management

ec-perl
syntax: $cmdr->abortAllJobs({...});

Example
$cmdr->abortAllJobs({force => 1});

ectool
syntax: ectool abortAllJobs ...

Example
ectool abortAllJobs --force 1

Back to Top

abortJob
Aborts a running job.
You must enter a jobId.

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID
<Boolean flag - 0|1|true|false> If this is set to 1, the job aborts
immediately. A zero value allows jobs to terminate in an orderly

force

way, executing steps marked "always run".


Argument type: Boolean
A string added to the aborted job/jobstep that describes or
records the reason for the abort. The server records this value, but

reason

places no meaning on the string, which is similar to a text


description.
Argument type: String

Positional arguments
jobId

369

ElectricCommander

Response
None or status OK message.

ec-perl
syntax: $cmdr->abortJob(<jobId>, {...});

Example
$cmdr->abortJob(4fa765dd-73f1-11e3-b67e-b0a420524153, {force => 1});

ectool
syntax: ectool abortJob <jobId> ...

Example
ectool abortJob 4fa765dd-73f1-11e3-b67e-b0a420524153 --force 1

Back to Top

abortJobStep
Aborts any type of step, including a command step or subprocedure step.
Aborting a subprocedure step also aborts all steps of the subprocedure. Steps marked "always run" will still
run to completion unless the "force" flag is specified.
You must enter a jobStepId.

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
step that is assigned automatically when the job step is created.

jobStepId

The system also accepts a job step name assigned to the job step
by its name template.
Argument type: UUID
<Boolean flag - 0|1|true|false> If this is set to 1, the job aborts
immediately. A zero value allows jobs to terminate in an orderly

force

way, for example, executing steps marked "always run".


Argument type: Boolean

370

API Commands - Job Management

Arguments

Descriptions
A string added to the aborted job/jobstep that describes or
records the reason for the abort. The server records this value, but

reason

places no meaning on the string, which is similar to a text


description.
Argument type: String

Positional arguments
jobStepId

Response
None or status OK message.

ec-perl
syntax: $cmdr->abortJobStep(<jobStepId>, {...});

Example
$cmdr->abortJobStep(5da765dd-73f1-11e3-b67e-b0a420524153, {force => 1});

ectool
syntax: ectool abortJobStep <jobStepId> ...

Example
ectool abortJobStep 5da765dd-73f1-11e3-b67e-b0a420524153

Back to Top

deleteJob
Deletes a job from the ElectricCommander database.
You must specify a jobId.

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID

Positional arguments
jobId

371

ElectricCommander

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deleteJob(<jobId>);

Example
$cmdr->deleteJob(4fa765dd-73f1-11e3-b67e-b0a420524153);

ectool
syntax: ectool deleteJob <jobId>

Example
ectool deleteJob 4fa765dd-73f1-11e3-b67e-b0a420524153

Back to Top

findJobSteps
Returns a list of job steps from a single job or from a single subprocedure job step. This command is used by
the
Job Details web page in the Commander UI. The elements in the list are returned in their natural job order.
You must specify either a jobId or a jobStepId, but not both.

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID
The unique Commander-generated identifier (a UUID) for a job
step that is assigned automatically when the job step is created.
The system also accepts a job step name assigned to the job step

jobStepId

by its name template.


Argument type: UUID

372

API Commands - Job Management

Arguments

Descriptions
A list of zero or more filter criteria definitions used to define objects
to find.

filter

See the findObjects API for complete description for using


filters.
Argument type: Collection
<full object count>
This specifies the number of full job steps (not just the IDs)
returned in the response. Returned job steps will be from the

numObjects

beginning of the list. If numObjects is not specified, all job steps in


the list of object IDs are returned. Any and all job steps can be
retrieved using the getObjects command.
Argument type: Integer
This is an unordered list of property names that specify additional
top-level properties to return for each object. See the code

selects

example for findObjects for instructions on forming the list and


passing it to the ElectricCommander Perl API.
Argument type: Collection

Positional arguments
jobId or jobStepId

Response
One or more jobStep elements.

ec-perl
syntax: $cmdr->findJobSteps({<optionals>});

Example 1
my $xPath = $cmdr->findJobSteps(
{jobId
=> "4fa765dd-73f1-11e3-b67e-b0a420524153",
select => [{propertyName => 'charEncoding'},
{propertyName => 'abc'}]});
print "Return data from Commander:\n" .
$xPath-> findnodes_as_string("/"). "\n";

Example 2
my $xPath = $cmdr->findJobSteps({jobStepId => "5da765dd-73f1-11e3-b67e-b0a42052415
3"});
print "Return data from Commander:\n" .
$xPath-> findnodes_as_string("/"). "\n";

373

ElectricCommander

ectool
Not supported.

Back to Top

getJobDetails
Retrieves complete information about a job, including details from each job step.
You must specify a jobId.

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID
<Boolean flag - 0|1|true|false>

structureOnly

This reduces the amount of information returned to minimal


structural information.
Argument type: Boolean

Positional arguments
jobId

Response
One jobelement, including one or more jobStep elements.

ec-perl
syntax: $cmdr->getJobDetails(<jobId>, {<optionals>});

Example
$cmdr->getJobDetails(4fa765dd-73f1-11e3-b67e-b0a420524153, {structureOnly => 1});

ectool
syntax: ectool getJobDetails <jobId> ...

Example
ectool getJobDetails 4fa765dd-73f1-11e3-b67e-b0a420524153 --structureOnly 1

Back to Top

374

API Commands - Job Management

getJobInfo
Retrieves all information about a job, except for job step information.
You must specify a jobId.

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID

Positional arguments
jobId

Response
One job element.

ec-perl
syntax: $cmdr->getJobInfo(<jobId>);

Example
$cmdr->getJobInfo(4fa765dd-73f1-11e3-b67e-b0a420524153);

ectool
syntax: ectool getJobInfo <jobId>

Example
ectool getJobInfo 4fa765dd-73f1-11e3-b67e-b0a420524153

Back to Top

getJobNotes
Retrieves the notes property sheet from a job.
You must specify a jobId.

375

ElectricCommander

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID

Positional arguments
jobId

Response
A propertySheet element that contains the job.

ec-perl
syntax: $cmdr->getJobNotes(<jobId>);

Example
$cmdr->getJobNotes(4fa765dd-73f1-11e3-b67e-b0a420524153);

ectool
syntax: ectool getJobNotes <jobId>

Example
ectool getJobNotes 4fa765dd-73f1-11e3-b67e-b0a420524153

Back to Top

getJobs
Retrieves summary information for a list of jobs. By default, all jobs are returned.
Notes:
If you use sortKey or sortOrder, you must use both arguments together.
You can use firstResult and maxResults together or separately to select a limited sublist of jobs for the
result set.

376

API Commands - Job Management

Arguments

Descriptions
The first row to return in the results.

firstResult

This is the <index number>0-based index that identifies the first


element returned from filtered, sorted result set.
Argument type: Integer
This number, <result count>, sets the maximum number of

maxResults

returned jobs.
Argument type: Integer
How to sort the results:

sortKey

<jobId|jobName|start|finish|procedureName>.
Argument type: String
The order in which to sort the results:<ascending|descending>.

sortOrder
Argument type: String
Filter jobs by this status: <running|completed|runnable>.
status
Argument type: String

Positional arguments
None

Response
One or more jobelements. A jobelement contains summary information only.

ec-perl
syntax: $cmdr->getJobs({...});

Examples
How do I get the first 10 jobs (index 0-9)?
$cmdr-> getJobs ({maxResults=>10});

How do I get the next 10 jobs (index 10-19)?


$cmdr-> getJobs({firstResult=>10, maxResults=>10});

How do I get the most recent job by start time?


$cmdr-> getJobs({sortKey=>'start', sortOrder=>'descending', maxResults=>1});

377

ElectricCommander

ectool
syntax: ectool getJobs ...

Examples
How do I get the first 10 jobs (index 0-9)?
ectool getJobs --maxResults 10

How do I get the next 10 jobs (index 10-19)?


ectool getJobs --firstResult 10 --maxResults 10

How do I get the most recent job by start time?


ectool getJobs --sortKey start --sortOrder descending --maxResults 1

Back to Top

getJobsForSchedule
Retrieves jobs started by a specific schedule.
You must specify a projectName and scheduleName.

Arguments

Descriptions
The name for the project that must be unique among all projects.

projectName
Argument type: String
The name for the schedule that must be unique among all
scheduleName

schedules for the project.


Argument type: String

Positional arguments
projectName, scheduleName

Response
Returns an XML stream containing any number of jobelements. The jobelements contain
summary information only.

ec-perl
syntax: $cmdr->getJobsForSchedule(<projectName>, <scheduleName>);

Example
$cmdr->getJobsForSchedule('Test', 'ea1');

378

API Commands - Job Management

ectool
syntax: ectool getJobsForSchedule <projectName> <scheduleName>

Example
ectool getJobsForSchedule Test ea1

Back to Top

getJobStatus
Retrieves the status of a job.
You must specify the jobId.

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID

Positional arguments
jobId

Response
Values for status and outcome as follows:
Possible values for status:
pending - The job is not yet runnable--it is waiting for other steps to complete first. A job should
not stay in this state for longer than a few seconds.
runnable - The job is ready to run, but it is waiting for a resource to become available.
running - The job is assigned to a resource and is executing the step command.
completed - The job finished executing.
Possible values for outcome: The outcome is accurate only if the job status is "completed."
success - The job finished successfully.
warning - The job completed with no errors, but encountered some suspicious conditions.
error - The job has finished execution with errors.

ec-perl
syntax: $cmdr->getJobStatus(<jobId>);

379

ElectricCommander

Example
$cmdr->getJobStatus(4fa765dd-73f1-11e3-b67e-b0a420524153);

ectool
syntax: ectool getJobStatus <jobId>

Example
ectool getJobStatus 4fa765dd-73f1-11e3-b67e-b0a420524153

Back to Top

getJobStepDetails
Retrieves details for a job step.
You may never need to use this command. This information is available for all job steps in a job by using the
getJobDetailscommand. The getJobStepDetailscommand can be used to refresh data for a single step if
you
need an update in real time.
You must specify jobStepId.

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
step that is assigned automatically when the job step is created.
The system also accepts a job step name assigned to the job step

jobStepId

by its name template.


Argument type: UUID

<Boolean flag - <0|1|true|false>


structureOnly

This reduces the amount of information returned to minimal


structural information.
Argument type: Boolean

Positional arguments
jobStepId

Response
A jobStep element.

380

API Commands - Job Management

ec-perl
syntax: $cmdr->getJobStepDetails(<jobStepId>, {...});

Example
$cmdr->getJobStepDetails(5da765dd-73f1-11e3-b67e-b0a420524153);

ectool
syntax: ectool getJobStepDetails <jobStepId> ...

Example
ectool getJobStepDetails 5da765dd-73f1-11e3-b67e-b0a420524153

Back to Top

getJobStepStatus
Retrieves the status of a job step.
You must specify the jobStepId.

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
step that is assigned automatically when the job step is created.
The system also accepts a job step name assigned to the job step

jobStepId

by its name template.


Argument type: UUID

Positional arguments
jobStepId

Response
A status tag - for example: <status>completed</status>
Possible values for status:
pending - The job step is not yet runnable--it is waiting for other steps to complete first. A job
should not stay in this state for longer than a few seconds.
runnable - The job step is ready to run, but it is waiting for a resource to become available.
running - The job step is assigned to a resource and is executing the step command.
completed - The job step finished executing.

381

ElectricCommander

ec-perl
syntax: $cmdr->getJobStepStatus(<jobStepId>, {...});

Example
$cmdr->getJobStepStatus(5da765dd-73f1-11e3-b67e-b0a420524153);

ectool
syntax: ectool getJobStepStatus <jobStepId>

Example
ectool getJobStepStatus 5da765dd-73f1-11e3-b67e-b0a420524153

Back to Top

getJobSummaries
Returns summary information about jobs.

382

API Commands - Job Management

Arguments

Descriptions
Specify filters in a space-separated list: filter1 filter2 ...
A list of zero or more filter criteria definitions used to define objects
to find.
Each element of the filter list is a hash reference containing one
filter criterion. You may specify several filter criteria, in which case
an object must meet all filter criteria to be included in the result.
See the code example below for instructions on forming the list
and passing it to the ElectricCommander Perl API.
Two types of filters:
"property filters" - used to select objects based on the value of the
object's intrinsic or custom property
"boolean filters" ("and", "or", "not") - used to combine one or more
filters using boolean logic.
Each "property filter" consists of a property name to test and an
operator to use for comparison. The property can be either an
intrinsic property defined by Commander or a custom property
added by the user. Each operator takes zero, one, or two operands

filters

to compare against the desired property.


Property filter operators are:
between (2 operands)
contains (1)
equals (1)
greaterOrEqual (1)
greaterThan (1)
in (1)
lessOrEqual(1)
lessThan (1)
like (1)
notEqual (1)
notLike (1)
isNotNull (0)
isNull (0)
A boolean filter is a boolean operator and an array of one or more
filters that are operands. Each operand can be either a property
filter or a boolean filter.
Boolean operators are:
not (1 operand)
and (2 or more operands)

383

ElectricCommander

Arguments

Descriptions
or (2 or more operands)
Argument type: Collection
<Boolean flag - 0|1|true|false>
When this argument is set to 1, the step will include the last

includeLastSuccess

successful job if it was not already included.


Argument type: Boolean
Maximum number of failed steps to return.

maxFailedSteps
Argument type: Integer
Maximum number of jobs to return.
maxJobs
Argument type: Integer
Maximum number of running steps to return.
maxRunningSteps
Argument type: Integer

Positional arguments
None

Response
Asummary of the job steps with the specified properties.

ec-perl
syntax:$cmdr->getJobSummaries ( {...});

Example
$cmdr->getJobSummaries ( {maxFailedSteps => 6} );

ectool
syntax:ectool getJobSummaries ...

Example
ectool getJobSummaries --maxFailedSteps 6

Back to Top

getJobSummary
Returns a job and its job steps with only the specified job and job step properties.

384

API Commands - Job Management

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID
A comma-separated list of intrinsic job properties to include in the

jobProperties

output.
Argument type: String
A comma-separated list of intrinsic job step properties to include in

jobStepProperties

the output.
Argument type: String

Positional arguments
None.

Response
Asummary of the job step with the specified properties.

ec-perl
syntax:$cmdr->getJobSummary ({<optionals ...>});

Example
$cmdr->getJobSummary ( {jobId => 5da765dd-73f1-11e3-b67e-b0a420524153} );

ectool
syntax:ectool getJobSummary [optionals ...]

Example
ectool getJobSummary --jobId 5da765dd-73f1-11e3-b67e-b0a420524153

Back to Top

moveJobs
Moves jobs from one project to another project.
You must specify sourceProject and destinationProject.

385

ElectricCommander

Arguments

Descriptions
Name of the project that contains the jobs you want to move.

sourceProject
Argument type: String
New project that will contain the jobs.
destinationProject
Argument type: String

Positional arguments
sourceProject, destinationProject

Response
None or a status OK message.

ec-perl
syntax: $cmdr->moveJobs(<sourceProject>, <destinationProject>);

Example
$cmdr->moveJobs("ProjectA", "ProjectB");

ectool
syntax: ectool moveJobs <sourceProject> <destinationProject> ...

Example
ectool moveJobs "ProjectA" "ProjectB"

Back to Top

runProcedure
Creates and starts a new job using a procedure directly or a procedure specified indirectly through a schedule.
Returns a new job ID. If the pollInterval option is provided, wait until the job completes up to a maximum
of timeout seconds (if also provided). If the scheduleNameoption is provided, the parameters provided by
that schedule will be used.
runProcedure credentials - two types of credentials can be passed to runProcedure:
l

Impersonation credentials

Credential parameters

Impersonation credentials
Impersonation credentials are used to set the top level impersonation credential for a job. If specified, the
impersonation credential [on the job] is used as the default impersonation credential for all steps in the job.

386

API Commands - Job Management

The impersonation credential can be specified in two ways. If the credentialNameargument is supplied,
the job looks for the named credential specified. If the user has execute permission on the specified
credential,
runProcedure is allowed to start the job.
If the userName and password arguments are supplied, the job creates a transient credential to contain
the pair. The transient credential is used by the job and then discarded when the job completes.
Only one of credentialName or userName should be specified. If both are specified, only userName is
used.
Neither can be specified if the procedure being run already has a credential defined on the procedure or
the project.
Credential parameters
If the procedure defines one or more credential parameters, runProcedure must specify a credential to
use for each parameter. The actualParameter argument identifies the credential name to use for the
parameter, and the credential argument specifies the user name for each defined credential. For each
credential specified, ectool prompts for a password.
For example, for a procedure named 'proc1' with a single credential parameter named 'param1'. The
following command could be used to pass a transient credential where the user name is 'joe' and the
password
is 'plumber':
$ ectool runProcedure test --procedureName proc1 \
--actualParameter param1=cred1 --credential cred1=joe
cred1 password: plumber
Multiple parameters or credentials can be specified by having additional name=value pairs after the
actualParameter or credential arguments. The same credential can be specified as the value for
more than one actual parameter.
You must specify a projectName and either a procedureName or a scheduleName.
Note: The pollInterval and timeout arguments are used to control whether runProcedurereturns
immediately or waits until the job completes.
If pollInterval is used and timeout is not used, pollInterval will time out in 60 seconds.

Arguments

Descriptions
The name for the project that must be unique among all projects.

projectName
Argument type: String

387

ElectricCommander

Arguments

Descriptions
Specifies the values to pass as parameters to the called
procedure. Each parameter value is specified with an
actualParameterName and a value. The
actualParameterName must match the name of a formal

actualParameter

parameter on the called procedure.


Used in conjunction with procedureName to set the value of the
actual parameters. Do not use this argument with scheduleName.
Argument type: Map
Use the following syntax to specify a credential:

credentials

<credName>=<userName> [<credName>=<userName> ...]].


Argument type: Collection
credentialName can be one of two forms:
relative
(for example, "cred1") - the credential is assumed to be in the

credentialName

project that contains the request target object.


absolute
(for example, "/projects/BuildProject/credentials/cred1") - the
credential can be from any specified project, regardless of the
target objects project.
This argument is used to specify the name of the destination

destinationProject

project.
Argument type: String
The password for the user running the procedure.

password
Argument type: String
Priorities take effect when two or more job steps in different jobs
are waiting for the same resource. When the resource is available,
it will be used by the job step that belongs to the job with the
highest priority. If the priority level is the same, the resource will be
priority

used by the job step that belongs to the job with the lowest job ID
number. If the job steps are in the same job, the resource will be
used first by the step with the lowest job step ID number.
Priority values are: low|normal|high|highest.
Argument type: JobPriority

388

API Commands - Job Management

Arguments

Descriptions
The name for the procedure; must be unique within the project.

procedureName
Argument type: String
The name for the schedule; must be unique among all schedules
for the project. Use this option if you want to use the parameters
scheduleName

from an existing specific schedule.


Argument type: String
The name of the user who is running the procedure.

userName
Argument type: String
If this option is not specified, runProcedurereturns immediately. If
it is specified, runProcedurewaits until the job completes. This
pollInterval

argument requires setting a value in secondsto determine how


often ectool queries the Commander server for job status, but this
is not an indefinite activity - set the timeout value to extend the
pollInterval for longer than 60 seconds if needed.
This argument requires a value set in seconds. If pollInterval is
specified, this timeout causes runProcedureto stop waiting for

timeout

the job to complete. It does not stop the job itself.


If pollInterval is used and timeout is not used,
pollIntervalwill timeout in 60 seconds.

Positional arguments
projectName, procedureName, scheduleName

Response
The new job ID number.

ec-perl
syntax: $cmdr->runProcedure(<project name>, {<optionals});

Example
$cmdr->runProcedure("Sample Project", {procedureName => "Delay",
actualParameter => {actualParameterName => "Delay Time", value => 10}});
$xpath = $ec->runProcedure("BSHTest",
{procedureName => "FakeMotoBuild",
actualParameter => [
{actualParameterName => "builddir", value => $cwd},
{actualParameterName => "board", value => $board},
{actualParameterName => "myview", value => $cwv},
{actualParameterName => "resourcetouse",

389

ElectricCommander

value => $resourcetouse},


]});

ectool
syntax: ectool runProcedure <project name> <procedureName> ...

Examples
ectool runProcedure <project name> --procedureName <procedure name>
--scheduleName <schedule name>
ectool runProcedure "Sample Project" --procedureName "Delay"
--actualParameter "Delay Time=10"

Back to Top

setJobName
Sets the name of a running job.
You must specify jobId and newName.
Notes:
The jobId can be omitted if the command is run as part of an ElectricCommander step.
A job cannot be renamed after it has completed.

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID
New name of the job.

newName
Argument type: String

Positional arguments
jobId, newName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->setJobName(<jobId>, <newName>);

390

API Commands - Job Management

Examples
$cmdr->setJobName(4fa765dd-73f1-11e3-b67e-b0a420524153, "Delay Test_541"); (from th
e command line)
$cmdr->setJobName("TestJob_252"); (from a step's command)

ectool
syntax: ectool setJobName <jobId> <newName> ...

Examples
ectool setJobName 4fa765dd-73f1-11e3-b67e-b0a420524153 "Delay Test"_541 (from the c
ommand line)
ectool setJobName "TestJob"_252

Back to Top

External Job APIs


What are external job APIs and do you need them?

Overview
ElectricCommander includes a powerful built-in scheduler for both managing execution and real-time reporting
for a "running" process. Most Commander Installations choose to use its built-in scheduler because it is more
powerful than most in-house built and other scheduling solutions.
However, there are use cases where an external scheduler may be appropriate, for example, an LSF Grid
engine. Often, such systems are quite mature and may have been in use for many years. An organizations
reliance on an LSF Grid system can mandate it remain as the driving scheduler. Many schedulers lack the
richness in their graphical user interface, which is an area where Commander excelsespecially as it applies
to monitoring the status of complex processes and workflows as they progress in real-time through the
Commander system. The Commander GUI also provides powerful auditing capabilities for reviewing results of
complex process runs.
External Job APIs are designed to leverage the Commander GUI to display results for jobs running on external
schedulers. The external scheduler can issue calls through these APIs to provide a representation of this same
job within the Commander Jobs page. Commander users and the external scheduler can then monitor the
complete integrated system through a single interfacethe Commander GUI.
The external system need not be a formal scheduler. In fact, even a simple script might be able to leverage the
External Job Step API. For example, a build script could issue API calls at its beginning and end so the build is
represented in Commander as a job.
Using the API does NOT consume agent resources. The API simply allows for graphical representation of
external jobs within Commander.

391

ElectricCommander

completeJob
Completes an externally managed job. Marks the job root step so the job is marked "completed" when all child
steps are completed, and updates the run time for the root step.
You must specify a jobId.

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID
<Boolean flag - 0|1|true|false> If true, all external steps
belonging to the job will be marked "complete".

This arguments determines whether all external steps under the


force

job should be recursively marked "complete".


Note: If this API is called on a job launched with
runProcedure, there is no effect unless force is enabled, in
which case only external steps are affected.
Argument type: Boolean
Overall outcome for a job or step:
success - The job finished successfully.
warning - The job completed with no errors, but
encountered some suspicious conditions.

outcome

error - The job has finished execution with errors.

If specified, the outcome overrides any previously propagated


outcome value.
Argument type: JobOutcome

Positional arguments
jobId

Response
None or status OK message.

392

API Commands - Job Management

ec-perl
syntax: $cmdr->completeJob(<jobId>);

Example
$cmdr->completeJob(1234);

ectool
syntax: ectool completeJob <jobId>

Example
ectool completeJob 1234

Back to Top

completeJobStep
Completes an externally managed job step. Marks the job step "completed" when all child steps are completed
and updates the step run time.
You must specify a jobStepId.

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
step that is assigned automatically when the job step is created.
The system also accepts a job step name assigned to the job step

jobStepId

by its name template.


Argument type: UUID

The exit code of a job step.


exitCode
Argument type: Integer
<Boolean flag - 0|1|true|false> If true, all external steps under
the job should be recursively marked "complete".
Note: If this API is called on a job launched with runProcedure,
force

there is no effect unless force is enabled, in which case only


external steps are affected.
Argument type: Boolean

393

ElectricCommander

Arguments

Descriptions
Overall outcome for a job or step:
success - The job step finished successfully.
warning - The job step completed with no errors, but

outcome

encountered some suspicious conditions.


error - The job step has finished execution with errors.
skipped - The job step was skipped.
Argument type: JobOutcome

Positional arguments
jobStepId

Response
None or status OK message.

ec-perl
syntax: $cmdr->completeJobStep(<jobStepId>);

Example
$cmdr->completeJobStep(5da765dd-73f1-11e3-b67e-b0a420524153);

ectool
syntax: ectool completeJobStep <jobStepId>

Example
ectool completeJobStep 5da765dd-73f1-11e3-b67e-b0a420524153

Back to Top

createJob
Creates an externally managed job that will serve as a container for external job steps.
You must specify projectName or destinationProject.

394

API Commands - Job Management

Arguments

Descriptions
If specified, determines the project where the job will reside. You
must have modify permission on the destination project.
projectName or destinationProject must be specified to

destinationProject

determine the project where the job is created,


destinationProject is preferred.
Argument type: String
If specified, the job name will be generated by expanding this
argument value.

jobNameTemplate

Note: The job name is generated by expanding the


jobNameTemplate argument or the jobNameTemplate from
the procedure or the system default.
Argument type: String
If specified, projectName and procedureName are used as a
template for the job. You must have execute permission on the
procedure.

procedureName

Note:
The job name is generated by expanding the
jobNameTemplate argument or the jobNameTemplate from
the specified procedure or the system default.
Argument type: String
The name of the project where this job will reside. You must have
modify permission on the destination project.
projectName or destinationProject must be specified to

projectName

determine the project where the job is created. If both are


specified, destinationProject is preferred.
Argument type: String

395

ElectricCommander

Arguments

Descriptions
The starting status for the
job:pending|runnable|scheduled|running>.
The status argument determines the "starting" job status. This is
useful if you want to immediately go into a specific status without
having to use modifyJob to update the status. Defaults to
pending.

status

Possible values for status:


l

pendingThe job is not yet runnable.

runnableThe job is ready to run.

scheduledThe job is scheduled to run.

runningThe job is executing.

Argument type: JobStatus

Positional arguments
None

Response
The new job ID number.

ec-perl
syntax: $cmdr->createJob({<optionals>});

Example
$cmdr->createJob({projectName => "Sample Project"});

ectool
syntax: ectool createJob ...

Example
ectool createJob --projectName "Sample Project"

Back to Top

createJobStep
Use this API to add Commander managed job steps to a running job or job step and to create externally
managed steps (if "external" is set).

396

API Commands - Job Management

You must specify the parent job step using either the jobStepId or parentPath arguments (COMMANDER_
JOBSTEPID implicitly sets jobStepId). The parent job step status must not be completed.

Arguments

Descriptions
Specifies the values to pass as parameters to the called
procedure. Each parameter value is specified with an
actualParameterName and a value. The

actualParameter

actualParameterName must match the name of a formal


parameter on the called procedure.
For more information about parameters, click here.
Argument type: Map
If set to 1, indicates this job step will run even if the job is aborted
before the job step completes. A useful argument for running a
"cleanup" step that should run whether the job step is successful or

alwaysRun

not. The value for alwaysRun is a <Boolean flag 0|1|true|false>. Defaults to "false".
Argument type: Boolean
Use this flag to run the same job step on several resources at the
same time. The job step is "broadcast" to all resources listed in the
resourceName argument.

broadcast

The broadcast value = <Boolean flag -0|1|true|false>. This


argument is applicable only to command job steps. Defaults to
"false".
Argument type: Boolean
The command to run. This argument is applicable to command job

command

steps only.
Argument type: String
If empty or non-zero, the job step will run. If set to "0", the job step
is skipped. A useful setting during procedure development or
when re-running a job that has already completed some of the job

condition

steps. Also, this argument is useful for conditional execution of


steps based on properties set by earlier steps.
Argument type: String

397

ElectricCommander

Arguments

Descriptions
The credential to use for impersonation on the agent.
credentialName can be one of two forms:
relative
(for example, "cred1") - the credential is assumed to be in the
project that contains the request target object.

credentialName

absolute
(for example, "/projects/BuildProject/credentials/cred1") - the
credential can be from any specified project, regardless of the
target objects project.
Argument type: String
Refers to one or more credentials to attach to this job step. These
are "dynamic" credentials, captured when a job is created.
Dynamic credentials are stored on the server temporarily until the

credentials

job completes and then discarded. For more information about


credentials, see the Credentials and User Impersonation Help
topic.
Argument type: Collection
A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the

description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type: String

398

API Commands - Job Management

Arguments

Descriptions
Determines what happens to the procedure if the step fails:

errorHandling

failProcedure- The current procedure continues, but the


overall
status is error (default).

abortProcedure- Aborts the current procedure, but


allows
already-running steps in the current procedure to complete.

abortProcedureNow- Aborts the current procedure and


terminatesrunning steps in the current procedure.

abortJob- Aborts the entire job, terminates running steps,


but allows alwaysRunsteps to run.

abortJobNow- Aborts the entire job and terminates all


running steps, including alwaysRun steps.

ignore - Continues as if the step succeeded.

Argument type: ErrorHandling


If set to 1, indicates this job step should acquire and retain this
resource exclusively. The value for exclusive is a
exclusive

<Boolean flag -0|1|true|false>. Defaults to "false".


Note: Setting exclusive, sets exclusiveMode to "job".
Argument type: Boolean
Use one of the following options:
l

None - the "default", which does not retain a resource.

Job - keeps the resource for the duration of the job step. No
other job can use this resource, regardless of its step limit,
until this job completes or "Release Exclusive" is used in a
job step. Future steps for this job will use this resource in
preference to other resources--if this resource meets the
needs of the job steps and its step limit is not exceeded.

Step - keeps the resource for the duration of the job step.

Call - keeps the resource for the duration of the procedure


that called this job step, which is equivalent to 'job' for top
level steps.

exclusiveMode

Argument type: ExclsiveMode

399

ElectricCommander

Arguments

Descriptions
If set, indicates this job step is an external step. Commander will
not schedule or run agent commands for external steps, but
instead, represents a step managed outside of Commander. The
typical usage is with an external Job (see createJob). The status

external

of an external job step is set using modifyJobStep, and it can be


completed using completeJobStep. The value for external is a
<Boolean flag - 0|1|true|false>. Default is "false".
Argument type: Boolean
The unique Commander-generated identifier (a UUID) for the
parent job step that is assigned automatically when the job step is
created. The system also accepts a job step name assigned to the

jobStepId

job step by its name template.


If both jobStepId and parentPath are specified, parentPath
is preferred.
Argument type: UUID
The name of the job step.

jobStepName
Argument type: String
A custom log file name produced by running the job step. By
logFileName

default, Commander assigns a unique name for this file.


Argument type: String
If set, indicates this job step should run at the same time as
adjacent job steps marked to run as parallel also. The value for

parallel

parallel is a <Boolean flag -0|1|true|false>. Defaults to


"false".
Argument type: Boolean
The path of the parent job step. If both jobStepId and

parentPath

parentPath are specified, parentPath is preferred.


Argument type: String

400

API Commands - Job Management

Arguments

Descriptions
The name of a program to run after a job step completes. This
program looks at the job step output to find errors and warnings.
Commander includes a customizable program called "postp" for

postProcessor

this purpose. The value for postProcessor is a command string


for invoking a post-processor program in the platform shell for the
resource (cmd for Windows, sh for UNIX).
Argument type: String

401

ElectricCommander

Arguments

Descriptions

The precondition property (if it exists) is copied to the job step


when the step is created. When the job step is eligible to transition
from pending to runnable, the precondition is evaluated. If the
precondition result is empty, false, or "0", the step remains in the
pending state. Any other value allows the step to proceed to the
runnable state.
Note: A precondition property allows steps to be created
with"pause", which then pauses the procedure. In a paused state,
all currently running steps continue, but no additional steps will
start.
Set this property to make a step wait until one or more dependent
conditions are met. When a job step is eligible to transition from
pending to runnable, a precondition is evaluated.
A precondition is a fixed text or text embedding property reference
that is evaluated to TRUE or FALSE. An empty string, a \"0\" or
\"false\" is interpreted as FALSE. Any other result string is
interpreted as TRUE. The step will block until the precondition is
TRUE.
precondition

Argument type: String

Precondition example:
Assume we defined these 4 steps:
1. Build object files and executables
2. Build installer
3. Run unit tests
4. Install bits on test system
Step 1 is an ordinary serial step.
Steps 2 and 3 can run in parallel because they depend only on
step 1's completion.
Step 4 depends on step 2, but not step 3.
You can achieve optimal step execution order with
preconditions:

402

Make steps 2-4 run in parallel.

Step 2 needs a job property set at the end of its step to


indicate step 2 is completing
(/myJob/buildInstallerCompleted=1).

API Commands - Job Management

Arguments

Descriptions
l

Set a precondition in step 4:


$[/myJob/buildInstallerCompleted]

The name of the procedure that will contain this job step.
procedureName
Argument type: String
The name of the project that contains the procedure where you are
projectName

adding a new job step.


Argument type: String
<Boolean flag - 0|1|true|false> Declares whether or not this
job step will release its resource, which is currently held
"exclusively".

releaseExclusive

Note: Setting this flag to "true" is the same as setting


releaseMode to release.
Argument type: Boolean
Use one of the following options:
l

none - the "default" - no action if the resource was not


previously marked as "retain."

release - releases the resource at the end of this job step.


If the resource for the job step was previously acquired with
"Retain exclusive" (either by this job step or some
preceding job step), the resource exclusivity is canceled at
the end of this job step. The resource is released in the
normal way so it may be acquired by other jobs.

releaseToJob - allows a job step to promote a "step


exclusive" resource to a Job exclusive resource.

releaseMode

Argument type: ReleaseMode


Name for the resource; must be unique among all resources.
resourceName
Argument type: String

403

ElectricCommander

Arguments

Descriptions
Where shell is the name of a program used to execute commands
contained in the "command" field. The name of a temporary file
containing commands will be appended to the end of this
invocation line. Normally, this file is a command shell, but it can be

shell

any other command line program. The default is to use the


standard shell for the platform it runs on (cmd for Windows, sh for
UNIX). Applicable to command steps only.
Argument type: String
<pending|runnable|scheduled|running>
The status argument determines the "starting" job status. This is
useful if you want to immediately go into a specific status without
having to use modifyJobStep to update the status. Defaults to
pending.
Possible values for status:

status
l

pendingThe job step is not yet runnable.

runnableThe job step is ready to run.

scheduledThe job step is scheduled to run.

runningThe job step is executing.

Argument type: JobStatus

The name of the new job step you are creating. You can use any
stepName

name of your choice.


Argument type: String
The name of the nested procedure to call when this job step runs.
If a subprocedure is specified, do not include the command or

subprocedure

commandFile options.
Argument type: String
If a subprocedureargument is used, this is the name of the
project where that subprocedure is found. By default, the current

subproject

project is used.
Argument type: String

404

API Commands - Job Management

Arguments

Descriptions
The maximum length of time the job step is allowed to run. After
the time specified, the job step will be aborted.

timeLimit

The time limit is specified in units that can be hours, minutes, or


seconds.
Argument type: String
Specify hours|minutes|seconds for time limit units.

timeLimitUnits
Argument type: TimeLimitUnits
The Commander agent sets this directory as the current working
directory, when running the command contained in the job step. If
no working directory is specified in the job step, Commander uses
the directory it created for the job in the Commander workspace as
workingDirectory

the working directory.


Note: If running a job step on a proxy resource, this directory
must exist on the proxy target.
Argument type: String
The name of the workspace where this job step log files will be

workspaceName

stored.
Argument type: String

Positional arguments
jobStepId or parentPath

Response
Returns a jobStep object.

ec-perl
syntax: $cmdr->createJobStep({<optionals>});

Examples
$cmdr->createJobStep ({parentPath => "/jobs/123", external => "1"});
$cmdr->createJobStep ({jobStepId => "5da765dd-73f1-11e3-b67e-b0a420524153", externa
l => "1"});
# Create a job step that calls a subprocedure and passes a parameter credential
# coolProcedure is a procedure within the Default project with one parameter
# credential named sshCredentialParameter.

405

ElectricCommander

$cmdr->createJobStep(
{
projectName => 'Default',
subprocedure => 'coolProcedure',
actualParameter => [
{
actualParameterName => 'sshCredentialParameter',
value => 'sshCredentialParameter'
}
],
credential => [
{
credentialName => 'sshCredentialParameter',
userName => 'sshUser',
password => 'super_secure_sshPassword'
}

]
}
);

# Create two parallel job steps and send them to the Commander server using the bat
ch API.
# Create the batch API object
my $batch = $ec->newBatch('parallel');
# Create multiple requests
my @reqIds = (
$batch->createJobStep(
{
parallel

=> '1',

projectName

=> 'Default',

subprocedure

=> 'coolProcedure',

actualParameter => [
{
actualParameterName => 'input',

406

API Commands - Job Management

value

=> 'helloWorld'

}
],
}
),
$batch->createJobStep(
{
parallel

=> '1',

projectName

=> 'Default',

subprocedure

=> 'coolProcedure',

actualParameter => [
{
actualParameterName => 'input',
value

=> 'helloWorld'

}
],
}
),
);
# Send off the requests
$batch->submit();

ectool
syntax: ectool createJobStep ...

Examples
ectool createJobStep --parentPath /jobs/123 --external 1
ectool createJobStep --jobStepId 5da765dd-73f1-11e3-b67e-b0a420524153 --external 1
ectool createJobStep --parallel 1 --projectName Default --subprocedure
coolProcedure --actualParameter input=helloWorld

Back to Top

modifyJob
Modifies the status of an externally managed job.

407

ElectricCommander

You must specify a jobId.

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID
<pending|runnable|scheduled|running>

This argument determines the current status of the job, and also
sets related timing values.

status

Possible values for status:


l

pendingThe job is not yet runnable.

runnableThe job is ready to run.

scheduledThe job is scheduled to run.

runningThe job is executing.

Argument type: JobStatus

Positional arguments
jobId

Response
The jobId element.

ec-perl
syntax: $cmdr->modifyJob (<jobId>, {<optionals>});

Example
$cmdr->modifyJob (4fa765dd-73f1-11e3-b67e-b0a420524153, {status => "running"});

ectool
syntax: ectool modifyJob <jobId> ...

Example
ectool modifyJob 4fa765dd-73f1-11e3-b67e-b0a420524153 --status "running"

Back to Top

408

API Commands - Job Management

modifyJobStep
Modifies the status of an externally managed job step.
You must specify a jobStepId.

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
step that is assigned automatically when the job step is created.

jobStepId

The system also accepts a job step name assigned to the job step
by its name template.
Argument type: UUID
Specifies the values to pass as parameters to the called
procedure. Each parameter value is specified with an
actualParameterName and a value. The

actualParameter

actualParameterName must match the name of a formal


parameter on the called procedure.
For more information about parameters, click here.
Argument type: Map
If set to 1, indicates this job step will run even if the job is aborted
before the job step completes. A useful argument for running a
"cleanup" step that should run whether the job step is successful or

alwaysRun

not. The value for alwaysRun is a <Boolean flag 0|1|true|false>. Defaults to "false".
Argument type: Boolean
Use this flag to run the same job step on several resources at the
same time. The job step is "broadcast" to all resources listed in the
resourceName argument.

broadcast

The broadcast value = <Boolean flag -0|1|true|false>. This


argument is applicable only to command job steps. Defaults to
"false".
Argument type: Boolean
The command to run. This argument is applicable to command job

command

steps only.
Argument type: String

409

ElectricCommander

Arguments

Descriptions
If empty or non-zero, the job step will run. If set to "0", the job step
is skipped. A useful setting during procedure development or
when re-running a job that has already completed some of the job

condition

steps. Also, this argument is useful for conditional execution of


steps based on properties set by earlier steps.
Argument type: String
Determines what happens to the procedure if the step fails:

errorHandling

failProcedure- The current procedure continues, but the


overall
status is error (default).

abortProcedure- Aborts the current procedure, but


allows
already-running steps in the current procedure to complete.

abortProcedureNow- Aborts the current procedure and


terminatesrunning steps in the current procedure.

abortJob- Aborts the entire job, terminates running steps,


but allows alwaysRunsteps to run.

abortJobNow- Aborts the entire job and terminates all


running steps, including alwaysRun steps.

ignore - Continues as if the step succeeded.

Argument type: ErrorHandling


If set to 1, indicates this job step should acquire and retain this
resource exclusively. The value for exclusive is a
exclusive

<Boolean flag -0|1|true|false>. Defaults to "false".


Note: Setting exclusive, sets exclusiveMode to "job".
Argument type: Boolean

410

API Commands - Job Management

Arguments

Descriptions
Use one of the following options:
l

None - the "default", which does not retain a resource.

Job - keeps the resource for the duration of the job step. No
other job can use this resource, regardless of its step limit,
until this job completes or "Release Exclusive" is used in a
job step. Future steps for this job will use this resource in
preference to other resources--if this resource meets the
needs of the job steps and its step limit is not exceeded.

Step - keeps the resource for the duration of the job step.

Call - keeps the resource for the duration of the procedure


that called this job step, which is equivalent to 'job' for top
level steps.

exclusiveMode

Argument type: ExclsiveMode


A custom log file name produced by running the job step. By
logFileName

default, Commander assigns a unique name for this file.


Argument type: String
If set, indicates this job step should run at the same time as
adjacent job steps marked to run as parallel also. The value for

parallel

parallel is a <Boolean flag -0|1|true|false>. Defaults to


"false".
Argument type: Boolean
The name of a program to run after a job step completes. This
program looks at the job step output to find errors and warnings.
Commander includes a customizable program called "postp" for

postProcessor

this purpose. The value for postProcessor is a command string


for invoking a post-processor program in the platform shell for the
resource (cmd for Windows, sh for UNIX).
Argument type: String

411

ElectricCommander

Arguments

Descriptions

The precondition property (if it exists) is copied to the job step


when the step is created. When the job step is eligible to transition
from pending to runnable, the precondition is evaluated. If the
precondition result is empty, false, or "0", the step remains in the
pending state. Any other value allows the step to proceed to the
runnable state.
Note: A precondition property allows steps to be created
with"pause", which then pauses the procedure. In a paused state,
all currently running steps continue, but no additional steps will
start.
Set this property to make a step wait until one or more dependent
conditions are met. When a job step is eligible to transition from
pending to runnable, a precondition is evaluated.
A precondition is a fixed text or text embedding property reference
that is evaluated to TRUE or FALSE. An empty string, a \"0\" or
\"false\" is interpreted as FALSE. Any other result string is
interpreted as TRUE. The step will block until the precondition is
TRUE.
precondition

Argument type: String

Precondition example:
Assume we defined these 4 steps:
1. Build object files and executables
2. Build installer
3. Run unit tests
4. Install bits on test system
Step 1 is an ordinary serial step.
Steps 2 and 3 can run in parallel because they depend only on
step 1's completion.
Step 4 depends on step 2, but not step 3.
You can achieve optimal step execution order with
preconditions:

412

Make steps 2-4 run in parallel.

Step 2 needs a job property set at the end of its step to


indicate step 2 is completing
(/myJob/buildInstallerCompleted=1).

API Commands - Job Management

Arguments

Descriptions
l

Set a precondition in step 4:


$[/myJob/buildInstallerCompleted]

<Boolean flag - 0|1|true|false> Declares whether or not this


job step will release its resource, which is currently held
"exclusively".
releaseExclusive

Note: Setting this flag to "true" is the same as setting


releaseMode to release.
Argument type: Boolean
Use one of the following options:
l

none - the "default" - no action if the resource was not


previously marked as "retain."

release - releases the resource at the end of this job step.


If the resource for the job step was previously acquired with
"Retain exclusive" (either by this job step or some
preceding job step), the resource exclusivity is canceled at
the end of this job step. The resource is released in the
normal way so it may be acquired by other jobs.

releaseToJob - allows a job step to promote a "step


exclusive" resource to a Job exclusive resource.

releaseMode

Argument type: ReleaseMode


Name for the resource; must be unique among all resources.
resourceName
Argument type: String
Where shell is the name of a program used to execute commands
contained in the "command" field. The name of a temporary file
containing commands will be appended to the end of this
invocation line. Normally, this file is a command shell, but it can be
shell

any other command line program. The default is to use the


standard shell for the platform it runs on (cmd for Windows, sh for
UNIX). Applicable to command steps only.
Argument type: String

413

ElectricCommander

Arguments

Descriptions
<pending|runnable|scheduled|running>
The status argument determines the "starting" job status. This is
useful if you want to immediately go into a specific status without
having to use modifyJobStep to update the status. Defaults to
pending.
Possible values for status:

status
l

pendingThe job step is not yet runnable.

runnableThe job step is ready to run.

scheduledThe job step is scheduled to run.

runningThe job step is executing.

Argument type: JobStatus

The name of the nested procedure to call when this job step runs.
If a subprocedure is specified, do not include the command or
subprocedure

commandFile options.
Argument type: String
If a subprocedureargument is used, this is the name of the
project where that subprocedure is found. By default, the current

subproject

project is used.
Argument type: String
The maximum length of time the job step is allowed to run. After
the time specified, the job step will be aborted.

timeLimit

The time limit is specified in units that can be hours, minutes, or


seconds.
Argument type: String
Specify hours|minutes|seconds for time limit units.

timeLimitUnits
Argument type: TimeLimitUnits

414

API Commands - Job Management

Arguments

Descriptions
The Commander agent sets this directory as the current working
directory, when running the command contained in the job step. If
no working directory is specified in the job step, Commander uses
the directory it created for the job in the Commander workspace as
the working directory.

workingDirectory

Note: If running a job step on a proxy resource, this directory


must exist on the proxy target.
Argument type: String
The name of the workspace where this job step log files will be
stored.

workspaceName

Argument type: String

Positional arguments
jobStepId

Response
Returns a modified jobStep

object.

ec-perl
syntax: $cmdr->modifyJobStep (<jobStepId>, {<optional>});

Example
$cmdr->modifyJobStep (4fa765dd-73f1-11e3-b67e-b0a420524153, {status => "running"});

ectool
syntax: ectool modifyJobStep <jobStepId> ...

Example
ectool modifyJobStep 4fa765dd-73f1-11e3-b67e-b0a420524153 --status "running"

Back to Top

waitForJob
Waits until the specified job reaches a given status or the timeout expires. Returns the result from the final
getJobStatus query.

415

ElectricCommander

Arguments

Descriptions
The job to wait for.
The unique Commander-generated identifier (a UUID) for a job

jobId

that is assigned automatically when the job is created. The system


also accepts a job name assigned to the job by its name template.
Argument type: UUID
The status to wait for. Must be either "running" or "completed"

finalStatus

(default is "completed").
Argument type: String
The number of seconds to wait before giving up on a request.

timeout
Argument type: Integer

Positional arguments
jobId

Response
Returns the result from the final getJobStatus query.

ec-perl
syntax:$cmdr->waitForJob (<jobStepId>, {<optional>);

Example
$cmdr->waitForJob ("4fa765dd-73f1-11e3-b67e-b0a420524153", {status => "running"});

Back to Top

416

API Commands - Parameter Management

API Commands - Parameter Management


attachParameter
createActualParameter
createFormalParameter
deleteActualParameter
deleteFormalParameter
detachParameter
getActualParameter
getActualParameters
getFormalParameter
getFormalParameters
modifyActualParameter
modifyFormalParameter

attachParameter
Attaches a formal parameter to a step.
Attaching a parameter allows a step to use the credential (passed in a parameter) as an actual parameter to a
subprocedure
call or directly in a getFullCredential call in a command step. For more information about parameters, click
here.
You must specify projectName, procedureName, stepName, and formalParameterName.

Arguments

Descriptions
The name of the project containing the step. The name must be

projectName

unique among all projects.


Argument Type: String

procedureName

stepName

formalParameterName

The name of the procedure containing the step.


The name of the step to which the parameter credential is
attached.
The name of the parameter with a credential reference.

Positional arguments
projectName, procedureName, stepName, formalParameterName

417

ElectricCommander

Response
None or status OK message.

ec-perl
syntax: $cmdr->attachParameter(<projectName>, <procedureName>, <stepName>,
<formalParameterName>);

Example
$cmdr->attachParameter("Test Proj", "Run Build", "Get Sources", "SCM Credential"});

ectool
syntax: ectool attachParameter <projectName> <procedureName> <stepName>
<formalParameterName>

Example
ectool attachParameter "Test Proj" "Run Build" "Get Sources" "SCM Credential
Back to Top

createActualParameter
Creates a new actual parameter for a step that calls a nested procedure. The parameter is passed to the nested
procedure when the step runs. At run time, the actual parameter name must match the name of a formal
parameter in the nested procedure.
Passing Actual Parameters
You can use actual parameters in three types of API calls:
l

calling runProcedure to start a new job

setting up a schedule

creating or modifying a subprocedure step

For example, when you call runProcedure using ectool, set the actual parameters to the procedure on the
command line using the optional argument --actualParameter, followed by a list of name/value pairs.
The following is an example of calling a procedure named MasterBuild:
ectool runProcedure "project A" --procedureName "MasterBuild"
--actualParameter Branch=main Type=Debug
To make this call using the Perl API, define a list. Each element of the list is an anonymous hash reference
that specifies one of the actual parameters. Now you can pass a reference to the list as the value of the
actualParameter argument.
Here is the same example called via the Perl API:
# Run the procedure
$xPath = $cmdr->runProcedure("project A",
{procedureName => "MasterBuild",
actualParameter => [
{actualParameterName => 'Branch',

418

API Commands - Parameter Management

value => 'main'},


actualParameterName => 'Type',
value => 'Debug'},
]});
Specifying most arguments to the createStep API in Perl is fairly intuitive; like any other API,
you specify key-value pairs in a hash argument for all optional parameters. However, specifying actual
parameters is more involved because actual parameters are not arbitrary key-values characterizing the step.
Instead, they are key-values characterizing actual parameters to the step. See the following
createStep request in XML:
<createStep>
<projectName>MyProject</projectName>
<procedureName>MyProcedure</procedureName>
<stepName>Step1</stepName>
<actualParameter>
<actualParameterName>parm1</actualParameterName>
<value>myval</value>
</actualParameter>
<actualParameter>
<actualParameterName>parm2</actualParameterName>
<value>val2</value>
</actualParameter>
</createStep>
Each actual parameter key-value is under an <actualParameter> element. Code this in the optional
arguments hash in
the Perl API like this:
{ ..., => ..., actualParameter => [{actualParameterName
value
{actualParameterName
value
...

=>
=>
=>
=>
=>

'parm1',
'myval'},
'parm2',
'val2'}],
...}

In other words, the value of the actualParameter key in the optional arguments hash is a list of hashes, each
representing one actual parameter. If the sub-procedure call takes only one actual parameter, the value of the
actualParameter key can be specified as just the hash representing the one parameter:
actualParameter => {actualParameterName => 'parm1',
value => 'myval'}
You must specify projectName, procedureName, stepName, and actualParameterName.

Arguments

Descriptions
The name of the project containing the procedure. The project

projectName

name must be unique among all projects.


Argument type: String

419

ElectricCommander

Arguments

Descriptions
The name of the procedure containing the step.

procedureName
Argument type: String
The name of the step that calls a subprocedure.
stepName
Argument type: String
The name of the parameter. This name must be unique within the
step, and at run time, it must match the name of a formal parameter
actualParameterName

in the subprocedure.
Argument type: String
The name of the application when the actual parameter is on an

applicationName

application process step.


Argument type: String
The name of the component when the actual parameter is on a

componentName

component process step.


Argument type: String
The name of the process when the actual parameter is on a

processName

process step.
Argument type: String
The name of the process step when if the actual parameter is on a

processStepName

process step.
Argument type: String
The name of the schedule.

scheduleName
Argument type: String
The name of the state definition.
stateDefinitionName
Argument type: String
The name of the transition definition.
transitionDefinitionName
Argument type: String

420

API Commands - Parameter Management

Arguments

Descriptions
This value is passed to the subprocedure as the value of the

value

matching formal parameter.


Argument type: String
The name of the workflow definition.

workflowDefinitionName
Argument type: String

Positional arguments
projectName, procedureName, stepName, actualParameterName

Response
None or status OK message.

ec-perl
syntax: $cmdr->createActualParameter(<projectName>, <procedureName>, <stepName>,
<actualParameterName>, {<optionals>});

Example
$cmdr->createActualParameter("Sample Project", "CallSub", "Step1", "Extra Parm",
{value => "abcd efg"});

ectool
syntax: ectool <projectName> <procedureName> <stepName> <actualParameterName>

Example
ectool createActualParameter "Sample Project" "CallSub" "Step1" "Extra Parm"
--value "abcd efg"
Back to Top

createFormalParameter
Creates a new formal parameter.

Arguments

Descriptions
The name of the project containing the procedure. The project

projectName

name must be unique among all projects.


Argument type: String

421

ElectricCommander

Arguments

Descriptions
The name of the procedure containing the parameter.

procedureName
Argument type: String
The name for the formal parameter that is used when the
formalParameterName

procedure is invoked to specify a value for the parameter.


Argument type: String
(Optional) The name of the application when the actual parameter

applicationName

is on an application process step.


Argument type: String
(Optional) The name of the component when the actual parameter

componentName

is on a component process step.


Argument type: String
(Optional) This value is used for the formal parameter when a

defaultValue

value is not provided and the procedure is invoked.


Argument type: String
(Optional) A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the

description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type: String
(Optional) <Boolean flag - 0|1|true|false> If 1 or true,
expansion for this parameter is deferred. The parameter value is
not expanded when the procedure call is expanded, but it can be

expansionDeferred

expanded from a command step instead.


The default is false, and the formal parameter is expanded
immediately.
Argument type: Boolean
(Optional) The display label.

label
Argument type: String

422

API Commands - Parameter Management

Arguments

Descriptions
(Optional) The display order index starting at 1.

orderIndex
Argument type: Integer
(Optional) The name of the process when the formal parameter is
processName

on a process.
Argument type: String
(Optional) <Boolean flag - 0|1|true|false> If 1 or true, this
parameter is required. The procedure will not execute unless a

required

value is given for it.


Argument type: Boolean
(Optional) The name of the state definition.

stateDefinitionName
Argument type: String
(Optional) The name of a workflow state.
stateName
Argument type: String
(Optional) The type can be any string value. This argument is used
primarily by the web interface to represent custom form elements.
type

When the type is the credential string value, the server expect a
credential as the parameter value.
Argument type: String
(Optional) The name of the workflow definition.

workflowDefinitionName
Argument type: String
(Optional) The name of a workflow.
workflowName
Argument type: String

Positional arguments
In ElectricCommander 5.0 and later, projectName and formalParameterName.
In releases earlier than ElectricCommander 5.0, projectName, procedureName, and
formalParameterName.
For workflow state parameters: projectName, formalParameterName, workflowDefinitionName
and stateDefinitionName

423

ElectricCommander

Response
None or status OK message.

ec-perl
syntax: $cmdr->createFormalParameter(<projectName>, <formalParameterName>,
{<optionals>});
For backward compatibility with releases earlier than ElectricCommander 5.0, you can also enter:
syntax: $cmdr->createFormalParameter(<projectName>, <procedureName>,
<formalParameterName>, {<optionals>});

Example
$cmdr->createFormalParameter("Sample Project", "Branch Name", {required => 1 });

Examples using parameters to create a check box, radio button, and drop-down box
Check box example:
$ec->createFormalParameter(
$newProjectName,
"$buildprocedurename",
'CheckoutSources',
{
type => "checkbox",
required => 0,
defaultValue => 'true',
description => "If checked, update the sandbox from Subversion (turn
off for debugging only)."
}
);
$ec->setProperty("/projects/$newProjectName/procedures/$buildprocedurename/
ec_customEditorData/parameters/CheckoutSources/checkedValue", "true");
$ec->setProperty("/projects/$newProjectName/procedures/$buildprocedurename/
ec_customEditorData/parameters/CheckoutSources/uncheckedValue", "false");
$ec->setProperty("/projects/$newProjectName/procedures/$buildprocedurename/
ec_customEditorData/parameters/CheckoutSources/initiallyChecked", "0");
Radio button example:
$ec->createFormalParameter(
$newProjectName,
"$buildprocedurename",
'BuildType',
{
type =>"radio",
required => 1,
defaultValue => '2',
description => "Select type of build"
}
);
$ec->setProperty("/projects/$newProjectName/procedures/$buildprocedurename/
ec_customEditorData/parameters/BuildType/options/optionCount", "2");
$ec->setProperty("/projects/$newProjectName/procedures/$buildprocedurename/
ec_customEditorData/parameters/BuildType/options/type", "list");
$ec->setProperty("/projects/$newProjectName/procedures/$buildprocedurename/
ec_customEditorData/parameters/BuildType/options/option1/text", "one");

424

API Commands - Parameter Management

$ec->setProperty("/projects/$newProjectName/procedures/$buildprocedurename/
ec_customEditorData/parameters/BuildType/options/option1/value", "1");
$ec->setProperty("/projects/$newProjectName/procedures/$buildprocedurename/
ec_customEditorData/parameters/BuildType/options/option2/text", "two");
$ec->setProperty("/projects/$newProjectName/procedures/$buildprocedurename/
ec_customEditorData/parameters/BuildType/options/option2/value", "2");
Drop-down menu example:
$ec->createFormalParameter(
$newProjectName,
"$buildprocedurename",
'BuildType',
{
type =>"type",
required => 1,
defaultValue => '1',
description => "Select type of build"
}
);
$ec->setProperty("/projects/$newProjectName/procedures/$buildprocedurename/
ec_customEditorData/parameters/BuildType/options/optionCount", "2");
$ec->setProperty("/projects/$newProjectName/procedures/$buildprocedurename/
ec_customEditorData/parameters/BuildType/options/type", "list");
$ec->setProperty("/projects/$newProjectName/procedures/$buildprocedurename/
ec_customEditorData/parameters/BuildType/options/option1/text", "one");
$ec->setProperty("/projects/$newProjectName/procedures/$buildprocedurename/
ec_customEditorData/parameters/BuildType/options/option1/value", "1");
$ec->setProperty("/projects/$newProjectName/procedures/$buildprocedurename/
ec_customEditorData/parameters/BuildType/options/option2/text", "two");
$ec->setProperty("/projects/$newProjectName/procedures/$buildprocedurename/
ec_customEditorData/parameters/BuildType/options/option2/value", "2");

ectool
For procedure parameters:
syntax: ectool createFormalParameter <projectName> <formalParameterName> ...
For backward compatibility with releases earlier than ElectricCommander 5.0, you can also enter:
syntax:ectool createFormalParameter <projectName> <procedureName>
<formalParameterName> ...

Example
ectool createFormalParameter "Sample Project" "Branch Name" --required 1
For workflow state parameters:
syntax: ectool createFormalParameter --formalParameterName <name>
--projectName <name> --workflowDefinitionName <name> --stateDefinitionName <name>

Example
ectool createFormalParameter --formalParameterName "Active users"
--projectName "Usage Report" --workflowDefinitionName "Usage
Workflow" --stateDefinitionName "Active and running"

425

ElectricCommander

Example using parameters to create a check box


You must create the ec_customEditorData property to add other parameters to the check box.
Back to Top

deleteActualParameter
Deletes an actual parameter.
You must specify a projectName, procedureName, stepName, and actualParameterName.

Arguments

Descriptions
The name of the project that contains this actual parameter. The

projectName

name must be unique among all projects.


Argument type: String
The name of the procedure that contains the step with this

procedureName

parameter.
Argument type: String
The name of the step that contains the actual parameter.

stepName
Argument type: String
The name of the actual parameter to delete.
actualParameterName
Argument type: String
The name of the application when the actual parameter is on an
applicationName

application process step.


Argument type: String
The name of the component when the actual parameter is on a

componentName

component process step.


Argument type: String
The name of the process when the actual parameter is on a

processName

process step.
Argument type: String

426

API Commands - Parameter Management

Arguments

Descriptions
The name of the process step when the actual parameter is on a

processStepName

process step.
Argument type: String
The name of the schedule containing the actual parameter.

scheduleName
Argument type: String
The name of the state definition.
stateDefinitionName
Argument type: String
The name of the transition definition.
transitionDefinitionName
Argument type: String
The name of the workflow definition.
workflowDefinitionName

Positional arguments
projectName, procedureName, stepName, actualParameterName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deleteActualParameter(<projectName>, <procedureName>, <stepName>,
<actualParameterName>);

Example
$cmdr->deleteActualParameter('Sample Project', 'CallSub', 'Step1', 'Different Par
m');

ectool
syntax: ectool deleteActualParameter <projectName> <procedureName> <stepName>
<actualParameterName> [optionals...]

Example
ectool deleteActualParameter "Sample Project" "CallSub" "Step1" "Different Parm"
Back to Top

427

ElectricCommander

deleteFormalParameter
Deletes a formal parameter.
You must specify projectName, procedureName, and formalParameterName.

Arguments

Descriptions
The name of the project that contains the procedure or parameter

projectName

to delete. The name must be unique among all projects.


Argument type: String
The name of the procedure that contains this parameter.

procedureName
Argument type: String
The name of the formal parameter to delete.
formalParameterName
Argument type: String
The name of the application when the formal parameter is on an
applicationName

application process step.


Argument type: String
The name of the component when the formal parameter is on a

componentName

component process step.


Argument type: String
The name of the process when the formal parameter is on a

processName

process step.
Argument type: String
The name of the state definition.

stateDefinitionName
Argument type: String
The name of the workflow state.
stateName
Argument type: String
The name of the workflow definition.
workflowDefinitionName
Argument type: String

428

API Commands - Parameter Management

Arguments

Descriptions
The name of a workflow.

workflowName
Argument type: String

Positional arguments

In ElectricCommander 5.0 and later, projectName and formalParameterName.


In releases earlier than ElectricCommander 5.0, projectName, procedureName, and
formalParameterName.

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deleteFormalParameter(<projectName>, <formalParameterName>);
For backward compatibility with releases earlier than ElectricCommander 5.0, you can also enter:
syntax:$cmdr->deleteFormalParameter(<projectName>, <procedureName>,
<formalParameterName>);

Example
$cmdr->deleteFormalParameter("Sample Project", "Build Name");

ectool
syntax: ectool deleteFormalParameter <projectName> <formalParameterName>
[optionals...]
For backward compatibility with releases earlier than ElectricCommander 5.0, you can also enter:
syntax:ectool deleteFormalParameter <projectName> <procedureName>
<formalParameterName> [optionals...]

Example
ectool deleteFormalParameter "Sample Project" "Build Name"
Back to Top

detachParameter
Detaches a formal parameter from a step.
You must specify projectName, procedureName, stepName, and formalParameterName.

429

ElectricCommander

Arguments

Descriptions
The name of the project that contains this parameter. The name

projectName

must be unique among all projects.


Argument type: String
The name of the procedure that contains this parameter.

procedureName
Argument type: String
The name of the step where this parameter is currently attached.
stepName
Argument type: String
The name of the formal parameter to detach.
formalParameterName
Argument type: String

Positional arguments
projectName, procedureName, stepName, formalParameterName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->detachParameter(<projectName>, <procedureName>, <stepName>,
<formalParameterName>);

Example
$cmdr-> detachParameter("Test Proj", "Run Build", "Get Sources", "SCM Credential");

ectool
syntax: ectool detachParameter <projectName> <procedureName> <stepName>
<formalParameterName>

Example
ectool detachParameter "Test Proj" "Run Build" "Get Sources" "SCM Credential"
Back to Top

getActualParameter
Retrieves an actual parameter by its name. For more information about parameters, click here.
You must specify an actualParameterName. If you need actual parameters on a step, the following 3
arguments
must be used together to specify a step: projectName, procedureName, and stepName.

430

API Commands - Parameter Management

Arguments

Descriptions
The name of the actual parameter.

actualParameterName
Argument type: String
The revision ID of the versioned object.
applicationEntityRevisionId
Argument type: UUID
The name of the application when the actual parameter is on an
application process step. The name must be unique among all
applicationName

projects.
Argument type: String
The name of the component when the actual parameter is on a

componentName

component process step.


Argument type: String
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID
The unique identifier for a job step that is assigned automatically
when the job step is created.

jobStepId

You enter this argument to query a subprocedure call to the job


step's parameter.
Argument type: UUID
The name of the procedure when the actual parameter is on a

procedureName

procedure step.
Argument type: String
The name of the process when the actual parameter is on a

processName

process step.
Argument type: String
The name of the process step when the actual parameter is on a

processStepName

process step.
Argument type: String

431

ElectricCommander

Arguments

Descriptions
The name of the project to query for the parameter on a schedule

projectName

or procedure step.
Argument type: String
The name of the schedule to query for the parameter on a

scheduleName

schedule.
Argument type: String
The name of the workflow state definition.

stateDefinitionName
Argument type: String
The name of the workflow state.
stateName
Argument type: String
The name of the step to query for the parameter on the step.
stepName
Argument type: String
The name of the workflow transition definition.
transitionDefinitionName
Argument type: String
The name of the workflow transition.
transitionName
Argument type: String
The name of the workflow definition.
workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String

Positional arguments
actualParameterName

Response
One actualParameter element.

ec-perl
syntax: $cmdr->getActualParameter(<actualParameterName>, {...});

432

API Commands - Parameter Management

Example
$cmdr->getActualParameter("Extra Parm",
{"projectName" => "Sample Project",
"procedureName" => "CallSub",
"stepName" => "Step1"});

ectool
syntax: ectool getActualParameter <actualParameterName> [optionals...]

Example
getActualParameter "Extra Parm" --projectName "Sample Project"
--procedureName "CallSub" --stepName "Step1"
Back to Top

getActualParameters
Retrieves all actual parameters from a job, step, schedule, state, or transition. For more information about
parameters, click here.
You must specify object locators to find the parameter. To find parameters on a step, you must use
projectName, procedureName, and stepName to specify the step.

Arguments

Descriptions
The revision ID of the versioned object.

applicationEntityRevisionId
Argument type: UUID
The name of the application when the actual parameters are on
an application process step. The name must be unique among all
applicationName

projects.
Argument type: String
The name of the component when the actual parameters are on a

componentName

component process step.


Argument type: String
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.

Argument type: UUID

433

ElectricCommander

Arguments

Descriptions
The unique identifier for a job step that is assigned automatically

jobStepId

when the job step is created.


Argument type: UUID
The name of the procedure containing the parameters.

procedureName
Argument type: String
The name of the process when the actual parameters are on a
processName

process step.
Argument type: String
The name of the process step when the actual parameters are on

processStepName

a process step.
Argument type: String
The name of the project containing the parameters.

projectName
Argument type: String
The name of the schedule containing parameters.
scheduleName
Argument type: String
The name of the workflow state definition.
stateDefinitionName
Argument type: String
The name of the workflow state.
stateName
Argument type: String
The name of the step containing parameters.
stepName
Argument type: String
The name of the workflow transition definition.
transitionDefinitionName
Argument type: String
The name of the workflow transition.
transitionName
Argument type: String

434

API Commands - Parameter Management

Arguments

Descriptions
The name of the workflow definition.

workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String

Positional arguments
Arguments to locate the parameter, beginning with the top-level object locator.

Response
Zero or more actualParameter elements.

ec-perl
syntax: $cmdr->getActualParameters{{...});

Example
$cmdr-> getActualParameters({"projectName" => "Sample Project",
"procedureName" => "CallSub",
"stepName" => "Step1"});

ectool
syntax: ectool getActualParameters [optionals...]

Example
ectool getActualParameters --projectName "Sample Project"
--procedureName "CallSub" --stepName "Step1"
Back to Top

getFormalParameter
Retrieves a formal parameter by its name.
You must specify projectName and formalParameterName.

Arguments

Descriptions
The name of the project containing the procedure. The name must

projectName

be unique among all projects.


Argument type: String

435

ElectricCommander

Arguments

Descriptions
The name of the procedure containing the formal parameter.

procedureName
Argument type: String
The name for the formal parameter that is used when the
procedure is invoked to specify a value for the parameter.
formalParameterName
Argument type: String

The name of the application when the formal parameter is on an


applicationName

application process step.


Argument type: String
The name of the component when the formal parameter is on a

componentName

component process step.


Argument type: String
The name of the process when the formal parameter is on a

processName

process step.
Argument type: String
The name of the workflow state definition.

stateDefinitionName
Argument type: String
The name of the workflow state.
stateName
Argument type: String
The name of the workflow definition.
workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String

Positional arguments
In ElectricCommander 5.0 and later, projectName and formalParameterName.
In releases earlier than ElectricCommander 5.0, projectName, procedureName, and
formalParameterName.

436

API Commands - Parameter Management

Response
One formalParameter element.

ec-perl
syntax: $cmdr->getFormalParameter(<projectName>, <formalParameterName>);
For backward compatibility with releases earlier than ElectricCommander 5.0, you can also enter:
syntax:$cmdr->getFormalParameter(<projectName>, <procedureName>,
<formalParameterName>);

Example
$cmdr->getFormalParameter("Test", "Get Sources");

ectool
syntax: ectool getFormalParameter <projectName> <formalParameterName> [optionals...]
For backward compatibility with releases earlier than ElectricCommander 5.0, you can also enter:
syntax:ectool getFormalParameter <projectName> <procedureName> <formalParameterName>

Example
ectool getFormalParameter Test "Get Sources"
Back to Top

getFormalParameters
Retrieves all formal parameters from a procedure, schedule, step, or state definition.
You must specify locator arguments to identify a procedure, schedule, or subprocedure step. If the locators
identify a schedule or step, the formal parameters of the called procedure are returned.

Arguments

Descriptions
The name of the project containing the parameters. The name

projectName

must be unique among all projects.


Argument type: String
The revision ID of the versioned object.

applicationEntityRevisionId
Argument type: UUID
The name of the application when the formal parameters are on an
applicationName

application process step.


Argument type: String

437

ElectricCommander

Arguments

Descriptions
The name of the component when the formal parameters are on a

componentName

component process step.


Argument type: String
The name of the procedure when the formal parameters are on a
procedure. When using this argument, you must also enter

procedureName

projectName.
Argument type: String
The name of the process when the formal parameters are on a

processName

process step.
Argument type: String
The name of the schedule. When using this argument, you must

scheduleName

also enter projectName.


Argument type: String
The name of the workflow state definition.

stateDefinitionName
Argument type: String
The name of the workflow state.
stateName
Argument type: String
The name of the step. When using this argument, you must also
enter
stepName

projectName and procedureName.


Argument type: String
The name of the workflow definition.

workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String

Positional arguments
projectName and Arguments to locate the formal parameter, beginning with the top-level object locator.

438

API Commands - Parameter Management

Response
An XML stream containing zero or more formalParameter elements.

ec-perl
syntax: $cmdr->getFormalParameters(<projectName>, {<optionals>});

Example
$cmdr->getFormalParameters("Test", {procedureName => "Build"});

ectool
syntax: ectool getFormalParameters <projectName> [optionals...]

Example
getFormalParameters Test --procedureName Build
Back to Top

modifyActualParameter
Modifies an existing actual parameter. An actual parameter is a name/value pair passed to a subprocedure.
This command supports renaming the actual parameter and setting its value.
For more information about parameters, click here.
In releases earlier than ElectricCommander 5.0, you must enter projectName, procedureName, and
actualParameterName to modify procedure parameters.
In ElectricCommander 5.0, you must enter projectName, procedureName, stepName, and
actualParameterName to modify procedure parameters.
You must enter projectName, actualParameterName, workflowDefinitionName and
stateDefinitionName for workflow state parameters.

Arguments

Descriptions
The name of the project containing this parameter. The name must

projectName

be unique among all projects.


Argument type: String
The name of the procedure containing the step with this

procedureName

parameter.
Argument type: String
The name of the step containing this parameter.

stepName
Argument type: String

439

ElectricCommander

Arguments

Descriptions
The name of the actual parameter to modify.

actualParameterName
Argument type: String
The name of the application when the actual parameters are on an
applicationName

application process step.


Argument type: String
The name of the component when the actual parameters are on a

componentName

component process step.


Argument type: String
New name of the parameter.

newName
Argument type: String
The name of the process when the actual parameters are on a
processName

process step.
Argument type: String
The name of the process step when the actual parameters are on

processStepName

a process step.
Argument type: String
The name of the schedule.

scheduleName
Argument type: String
The name of the workflow state definition.
stateDefinitionName
Argument type: String
The name of the workflow transition definition.
transitionDefinitionName
Argument type: String
Changes the current value on an actual parameter. This value is
passed to the subprocedure as the value of the matching formal
value

parameter.
Argument type: String

440

API Commands - Parameter Management

Arguments

Descriptions
The name of the workflow definition.

workflowDefinitionName
Argument type: String

Response
None or a status OK message.

ec-perl
syntax: $cmdr->modifyActualParameter(<projectName>, <procedureName>, <stepName>,
<actualParameterName>, {<optionals>});

Example
$cmdr->modifyActualParameter("Sample Project", "CallSub", "Step1", "Extra Parm",
{newName => "myParm"});

ectool
syntax: ectool modifyActualParameter <projectName> <procedureName> <stepName>
<actualParameterName> [optionals...]

Example
ectool modifyActualParameter "Sample Project" "CallSub" "Step1" "Extra Parm"
--newName "Different Parm"
Back to Top

modifyFormalParameter
Modifies an existing formal parameter.
In releases earlier than ElectricCommander 5.0, you must enter projectName, procedureName, and
formalParameterName to modify procedure parameters.
In ElectricCommander 5.0, you must enter projectName and formalParameterName to modify procedure
parameters.
You must enter projectName, formalParameterName, workflowDefinitionName and
stateDefinitionName for workflow state parameters.

441

ElectricCommander

Arguments

Descriptions
The name of the project containing this parameter. The name must

projectName

be unique among all projects.


Argument type: String
The name of the procedure containing this parameter.

procedureName
Argument type: String
The name for this formal parameter. It is used when the procedure
formalParameterName

is invoked to specify a value for the parameter.


Argument type: String
The name of the application when the formal parameters are on an

applicationName

application process step.


Argument type: String
The name of the component when the formal parameters are on a

componentName

component process step.


Argument type: String
This value is used for the formal parameter if one is not provided

defaultValue

when the procedure is invoked.


Argument type: String
A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the

description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type: String
(Optional) <Boolean flag - 0|1|true|false> If 1 or true,
expansion for this parameter is deferred. The parameter value is
not expanded when the procedure call is expanded, but it can be

expansionDeferred

expanded from a command step instead.


The default is false, and the formal parameter is expanded
immediately.
Argument type: Boolean

442

API Commands - Parameter Management

Arguments

Descriptions
The display label.

label
Argument type: String
New name for the parameter.
newName
Argument type: String
The display order index starting at 1.
orderIndex
Argument type: Integer
The name of the process when the formal parameter is on a
processName

process step.
Argument type: String
<Boolean flag - 0|1|true|false> If 1 or true, this parameter is
required. The procedure will not execute unless a value is given

required

for it.
Argument type: Boolean
The name of the state definition.

stateDefinitionName
Argument type: String
The name of a workflow state.
stateName
Argument type: String
The type can be any string value. This argument is used primarily
by the web interface to represent custom form elements. When the
type

type is the credential string value, the server expect a credential as


the parameter value.
Argument type: String
The name of the workflow definition.

workflowDefinitionName
Argument type: String
The name of a workflow.
workflowName
Argument type: String

Positional arguments
In ElectricCommander 5.0, for procedure parameters: projectName and formalParameterName.

443

ElectricCommander

In releases earlier than ElectricCommander 5.0, for procedure parameters: projectName,


procedureName, and formalParameterName.
For workflow state parameters: projectName, formalParameterName, workflowDefinitionName
and stateDefinitionName

Response
None or a status OK message.

ec-perl
For procedural parameters in ElectricCommander 5.0 and later:
syntax: $cmdr->modifyFormalParameter(<projectName>, <formalParameterName>,
{<optionals>});
For backward compatibility with releases earlier than ElectricCommander 5.0, you can also enter:
syntax:$cmdr->modifyFormalParameter(<projectName>, <procedureName>,
<formalParameterName>, {<optionals>});

Example
$cmdr->modifyFormalParameter("Sample Project", "Branch Name",
{defaultValue => "main"});

ectool
For procedural parameters in ElectricCommander 5.0 and later:
syntax: ectool modifyFormalParameter <projectName> <formalParameterName>
[optionals...]
For backward compatibility with releases earlier than ElectricCommander 5.0, you can also enter:
syntax: ectool modifyFormalParameter <projectName> <procedureName>
<formalParameterName> ...

Example
ectool modifyFormalParameter "Sample Project" "Branch Name"
--defaultValue main
For workflow state parameters:
syntax: ectool modifyFormalParameter --formalParameterName <name>
--projectName <name> --workflowDefinitionName <name> --stateDefinitionName <name>

Back to Top

444

API Commands - Plugin Management

API Commands - Plugin Management


createPlugin on page 445
deletePlugin
getPlugin
getPlugins
installPlugin
modifyPlugin
promotePlugin
uninstallPlugin

createPlugin
Creates a plugin from an existing project.
You must specify a key, version, and projectName.

Arguments

Descriptions
Version independent name for the plugin.

key
Argument type: String
Version of the plugin.
version
Argument type: String
Name of the project.
projectName
Argument type: String
(Optional) Name of the plugin author.
author
Argument type: String
(Optional) A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the
description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type: String

445

ElectricCommander

Arguments

Descriptions
(Optional) Label that appears in plugin lists.

label
Argument type: String

Positional arguments
key, version, and projectName

Response
Returns a plugin object.

ec-perl
syntax: $cmdr->createPlugin(<key>, <version>, <projectName>, {<optionals>});

Example
$cmdr->createPlugin("SCM-P4", "2.1.3", "default", {author => "jdoe"});

ectool
syntax: ectool createPlugin <key> <version> <projectName> [optionals...]

Example
ectool createPlugin SCM-P4 2.1.3 default --author jdoe
Back to Top

deletePlugin
Deletes an existing plugin object without deleting the associated project or files.
You must specify a pluginName.

Arguments

Descriptions
The name of the plugin you want to delete.

pluginName
Argument type: String

Positional arguments
pluginName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deletePlugin(<pluginName>);

446

API Commands - Plugin Management

Example
$cmdr->deletePlugin("TheWidget-1.0");

ectool
syntax: ectool deletePlugin <pluginName>

Example
ectool deletePlugin TheWidget-1.0
Back to Top

getPlugin
Retrieves an installed plugin.
You must specify the pluginName.

Arguments

Descriptions
The name of the plugin to find. If the name is specified without a
version number, the currently promoted version is returned if

pluginName

possible.
Argument type: String

Positional arguments
pluginName

Response
One plugin element, which includes the plugin ID, name, time created, label, owner, key,
version, and so on.

ec-perl
syntax: $cmdr->getPlugin(<pluginName>);

Example
$cmdr->getPlugin("TheWidget");

ectool
syntax: ectool getPlugin <pluginName>

Example
ectool getPlugin TheWidget
Back to Top

447

ElectricCommander

getPlugins
Retrieves all installed plugins.

Arguments

Descriptions

None

Positional arguments
None

Response
Zero or more plugin elements.

ec-perl
syntax: $cmdr->getPlugins();

Example
$cmdr->getPlugins();

ectool
syntax: ectool getPlugins

Example
ectool getPlugins
Back to Top

installPlugin
Installs a plugin from a JAR file. Extracts the JAR contents on the server and creates a project and a plugin.
You must specify the url.

448

API Commands - Plugin Management

Arguments

Descriptions
The location of the plugin JAR file to install.
If the location refers to a file on the client machine, the file will be
uploaded to the server.

url

If the location refers to a remote accessible file (for example, via an


http://url), the server will download it.
If the location is a file: reference, the file will be read directly
from the specified location on the server file system.
Argument type: String
<Boolean flag - 0|1|true|false> Specifying false causes an
existing plugin with the same key and version to be overwritten

force

with the new plugin contents, otherwise an error is returned.


Argument type: Boolean

Positional arguments
url

Response
One plugin element.

ec-perl
syntax: $cmdr->installPlugin(<url>, {...});

Example
$cmdr->installPlugin("./myPlugin.jar")

ectool
syntax: ectool installPlugin <url> ...

Example
ectool installPlugin ./myPlugin.jar
Back to Top

modifyPlugin
Modifies an existing plugin.
Note: Some plugin attributes available on the Plugins web page are not available in any of the plugin-related
APIs.
Because some plugin meta data comes from the plugin.xml file, the web server can access this data, but the

449

ElectricCommander

Commander
server cannot. Thus, the Plugin Manager, run in the web server context, provides additional information and
functionality.
You must specify the pluginName.

Arguments

Descriptions
The name of the plugin to modify. If the name is specified without a

pluginName

version number, the currently promoted version is used if possible.


Argument type: String
The author of the plugin.

author
Argument type: String
A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the
description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type: String
The name of the plugin as displayed on the Plugins web page.

label
Argument type: String

Positional arguments
pluginName

Response
One plugin element.

ec-perl
syntax: $cmdr->modifyPlugin(<pluginName>, {...});

Example
$cmdr->modifyPlugin('TheWidget', {description => "new description"});

ectool
syntax: ectool modifyPlugin <pluginName> ...

Example
ectool modifyPlugin TheWidget --description "new description"

450

API Commands - Plugin Management

Back to Top

promotePlugin
Sets the promoted flag on a plugin. Only one version of a plugin can be promoted at a time, so setting the
promoted flag to "true" on one version sets the flag to false on all other plugins with the same key. The
promoted version is the one resolved by an indirect reference of the form $[/plugins/<key>] or a plugin
name argument without a specified version.
You must specify the pluginName.

Arguments

Descriptions
The name of the plugin to promote. If the name is specified without
a version number, the currently promoted version is used if

pluginName

possible.
Argument type: String
<Boolean flag - 0|1|true|false> The new value of the
promoted flag for the specified plugin.

promoted

The default is true, which means the plugin will be promoted.


If you want to demote the plugin, use the value of "0" or false.
Argument type: Boolean

Positional arguments
pluginName

Response
One plugin element, which includes the plugin ID, name, time created, label, owner, key, version,
project name, and so on.

ec-perl
syntax: $cmdr->promotePlugin(<pluginName>, {<optionals});

Example
$cmdr->promotePlugin("TheWidget-1.0");

ectool
syntax: ectool promotePlugin <pluginName> ...

Example
ectool promotePlugin TheWidget-1.0

451

ElectricCommander

Back to Top

uninstallPlugin
Uninstalls a plugin, deleting the associated project and any installed files.
You must specify the pluginName.

Arguments

Descriptions
The name of the plugin to uninstall. If the name is specified without
a version number, the currently promoted version is used if

pluginName

possible.
Argument type: String
The maximum amount of time to spend waiting for this operation to

timeout

complete.
Argument type: Long

Positional arguments
pluginName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->uninstallPlugin(<pluginName>, {<optionals>});

Example
$cmdr->uninstallPlugin("TheWidget-1.0");

ectool
syntax: ectool uninstallPlugin <pluginName> ...

Example
ectool uninstallPlugin TheWidget-1.0
Back to Top

452

API Commands - Procedure Management

API Commands - Procedure Management


createProcedure
createStep
deleteProcedure
deleteStep
getProcedure
getProcedures
getStep
getSteps
modifyProcedure
modifyStep
moveStep

createProcedure
Creates a new procedure for an existing project.
You must specify projectName and procedureName.

Arguments

Descriptions
The name of the project that contains this procedure. The name

projectName

must be unique among all projects.


Argument type: String
The name of the procedure that must be unique within the project.

procedureName
Argument type: String
The name of the credential specified in one of these formats:

credentialName

relative(for example, "cred1")The credential is assumed


to be in the project that contains the requested target
object.

absolute(for example,
"/projects/BuildProject/credentials/cred1")The credential
can be from any specified project, regardless of the project
for the target object.

Argument type: String

453

ElectricCommander

Arguments

Descriptions
A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the

description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type: String
Template used to determine the default name of jobs launched

jobNameTemplate

from a procedure.
Argument type: String
The name of the default resource or pool used in steps run by this

resourceName

procedure.
Argument type: String
If no time limit was specified on the calling step, time limits are
copied to the calling step from the procedure. If the procedure is
called from runProcedure (or a schedule), the time limit acts as a

timeLimit

global job timeout.


The timer for the procedure starts as soon as the calling step or job
becomes runnable (all preconditions are satisfied).
Argument type: String
Time limit units are hours|minutes|seconds.

timeLimitUnits
Argument type: TimeLimitUnits
The name of the default workspace used in steps run by this
workspaceName

procedure.
Argument type: String

Positional arguments
projectName, procedureName

Response
None or status OK message.

ec-perl
syntax: $cmdr->createProcedure(<projectName>, <procedureName>, {<optionals>});

454

API Commands - Procedure Management

Example
$cmdr->createProcedure("Test Proj", "Run Build", {resourceName => "Test Resourc
e"});

ectool
syntax: ectool createProcedure <projectName> <procedureName> ...

Example
ectool createProcedure "Test Proj" "Run Build" --resourceName "Test Resource"
Back to Top

createStep
Use this command to create a new procedure step.
Fundamentally, ElectricCommander supports three types of steps:
l

Command Stepthe step executes a command or script under the control of a shell program.

Subprocedure Stepthe step invokes another Commander procedure. In this case, the step will not
complete
until all subprocedure steps have completed.

Custom Step

You must specify a projectName, procedureName, and stepName.

Arguments

Descriptions
The name of a project that must be unique among all projects.

projectName
Argument type: String
The name for a procedure that must be unique within the project.
procedureName
Argument type: String
Name of the step that must be unique within the procedure.
stepName
Argument type: String

455

ElectricCommander

Arguments

Descriptions
Specifies the values to pass as parameters to the called
procedure. Each parameter value is specified with an
actualParameterName and a value. The

actualParameter

actualParameterName must match the name of a formal


parameter on the called procedure.
For more information about parameters, click here.
Argument type: Map
The value for alwaysRun is a <Boolean flag -0|1|true|false>.
Defaults to false.

alwaysRun

If this value is set to 1, this step will run even if the job is aborted
before the step completes. This is a useful argument for running a
"cleanup" step that should run whether the job is successful or not.
Argument type: Boolean
The broadcast value is <Boolean flag -0|1|true|false>.
Use this flag to run the same step on several resources at the
same time. The step is "broadcast" to all resources listed in the

broadcast

resourceName argument.
This argument is applicable only to command steps.The default is
false.
Argument type: Boolean
The command to run. This argument is applicable only to

command

command steps.
Argument type: String
This option is supported only in Perl and ectool bindings - it is
not a part of the XML protocol.
Contents of the command file is read and stored in the "command"

commandFile

field. This is an alternative argument for command and is useful if


the "command" field spans multiple lines. The commandFile value
is the actual command file text. This argument is applicable to
command steps only.

456

API Commands - Procedure Management

Arguments

Descriptions
If empty or non-zero, the step will run. If set to "0", the step is
skipped. A useful setting during procedure development or when
re-running a job that has already completed some of the steps.

condition

Also, this argument is useful for conditional execution of steps


based on properties set by earlier steps.
Argument type: String
The credential to use for impersonation on the agent.
Name of the credential in one of these forms:

credentialName

relative (for example, "cred1")The credential is assumed


to be in the project that contains the request target object.

absolute (for example,


"/projects/BuildProject/credentials/cred1")Tthe credential
can be from any specified project, regardless of the target
objects project.

Argument type: String


A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the
description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type: String

457

ElectricCommander

Arguments

Descriptions
Determines what happens to the procedure if the step fails:

errorHandling

failProcedure- The current procedure continues, but the


overall
status is error (default).

abortProcedure- Aborts the current procedure, but


allows
already-running steps in the current procedure to complete.

abortProcedureNow- Aborts the current procedure and


terminates running steps in the current procedure.

abortJob- Aborts the entire job, terminates running steps,


but allows
alwaysRunsteps to run.

abortJobNow- Aborts the entire job and terminates all


running steps, including alwaysRun steps.

ignore - Continues as if the step succeeded.

Argument type: ErrorHandling


The value for exclusive is a <Boolean flag -0|1|true|false>.
If set to 1, this step should acquire and retain this resource
exclusively. The defaults to false.
exclusive
Note: When you set exclusive, exclusiveMode is set to
"job".
Argument type: Boolean
Use one of the following options:
l

None - the "default", which does not retain a resource.

Job - keeps the resource for the duration of the job. No


other job can use this resource, regardless of its step limit,
until this job completes or "Release Exclusive" is used in a
step. Future steps for this job will use this resource in
preference to other resources--if this resource meets the
needs of the steps and its step limit is not exceeded.

Step - keeps the resource for the duration of the step.

Call - keeps the resource for the duration of the procedure


that called this step, which is equivalent to 'job' for top level
steps.

exclusiveMode

Argument type: ExclusiveMode

458

API Commands - Procedure Management

Arguments

Descriptions
A custom log file name produced by running the step. By default,

logFileName

ElectricCommander assigns a unique name for this file.


Argument type: String
The value for parallel is a <Boolean flag -0|1|true|false>.

parallel

If set, indicates this step should run at the same time as adjacent
steps marked to run as parallel also. The default is to false.
Argument type: Boolean
The name of a program to run after a step completes. This program
looks at the step output to find errors and warnings. Commander
includes a customizable program called "postp" for this purpose.

postProcessor

The value for postProcessor is a command string for invoking a


post-processor program in the platform shell for the resource (cmd
for Windows, sh for UNIX).
Argument type: String

459

ElectricCommander

Arguments

Descriptions
By default, if the step has no precondition, it will run when
scheduled. Set this property to make a step wait until one or more
dependent conditions are met. When a job step is eligible to
transition from pending to runnable, a precondition is evaluated.
A precondition is a fixed text or text embedding property reference
that is evaluated to TRUE or FALSE. An empty string, a \"0\" or
\"false\" is interpreted as FALSE. Any other result string is
interpreted as TRUE. The step will block until the precondition is
TRUE.
Precondition example:
Assume we defined these 4 steps:
1. Build object files and executables
2. Build installer
3. Run unit tests

precondition

4. Install bits on test system


Step 1 is an ordinary serial step.
Steps 2 and 3 can run in parallel because they depend only on
step 1's completion.
Step 4 depends on step 2, but not step 3.
You can achieve optimal step execution order with
preconditions:
l

Make steps 2-4 run in parallel.

Step 2 needs a job property set at the end of its step to


indicate step 2 is completing
(/myJob/buildInstallerCompleted=1).

Set a precondition in step 4:


$[/myJob/buildInstallerCompleted]

Argument type: String


<Boolean flag - 0|1|true|false>
Declares whether or not this step will release its resource, which is
currently held exclusively.
releaseExclusive
Note: Setting this flag to "true" is the same as setting
releaseMode to release.
Argument type: Boolean

460

API Commands - Procedure Management

Arguments

Descriptions
Use one of the following options:
l

none - the "default" - no action if the resource was not


previously marked as "retain."

release - releases the resource at the end of this step. If


the resource for the step was previously acquired with
"Retain exclusive" (either by this step or some preceding
step), the resource exclusivity is canceled at the end of this
step. The resource is released in the normal way so it may
be acquired by other jobs.

releaseToJob - allows a step to promote a "step


exclusive" resource to a Job exclusive resource.

releaseMode

Argument type: ReleaseMode


Name for the resource that must be unique among all resources.
resourceName
Argument type: String
Where shell is the name of a program used to execute commands
contained in the "command" field. The name of a temporary file
containing commands will be appended to the end of this
invocation line. Normally, this file is a command shell, but it can be
shell

any other command line program. The default is to use the


standard shell for the platform it runs on (cmd for Windows, sh for
UNIX). This is applicable to command steps only.
Argument type: String
The name of the nested procedure to call when this step runs. If a
subprocedure is specified, do not include the command or

subprocedure

commandFile options.
Argument type: String
If a subprocedureargument is used, this is the name of the
project where that subprocedure is found. By default, the current

subproject

project is used.
Argument type: String

461

ElectricCommander

Arguments

Descriptions
The maximum length of time the step is allowed to run. After the
time specified, the step will be aborted.

timeLimit

The time limit is specified in units that can be hours, minutes, or


seconds.
Argument type: String
Specify hours|minutes|seconds for time limit units.

timeLimitUnits
Argument type: TimeLimitUnits
The Commander agent sets this directory as the current working
directory, when running the command contained in the step. If no
working directory is specified in the step, Commander uses the
directory it created for the job in the Commander workspace as the
workingDirectory

working directory.
Note: If running a step on a proxy resource, this directory must
exist on the proxy target.
Argument type: String
The name of the workspace where the log files for this step will be

workspaceName

stored.
Argument type: String

Positional arguments
projectName, procedureName, stepName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->createStep(<projectName>, <procedureName>, <stepName>,
{<optionals>});
Specifying most arguments to the Perl createStep API is fairly intuitive. Similar to any other API, key-value
pairs are specified in a hash argument for all optional parameters. However, specifying actual parameters is
a little
different because they are not arbitrary key-values characterizing the step. Actual parameters are keyvalues
characterizing actual parameters to the step. See the following createStep request in XML:
<createStep>
<projectName>MyProject</projectName>
<procedureName>MyProcedure</procedureName>

462

API Commands - Procedure Management

<stepName>Step1</stepName>
<actualParameter>
<actualParameterName>parm1</actualParameterName>
<value>myval</value>
</actualParameter>
<actualParameter>
<actualParameterName>parm2</actualParameterName>
<value>val2</value>
</actualParameter>
</createStep>
Each actual parameter key-value is under an <actualParameter> element, which is codified in the
optional
arguments hash in the Perl API like this:
{... => ..., actualParameter => [{actualParameterName => 'parm1', value =>
'myval'},
{actualParameterName => 'parm2', value => 'val2'}], ... => ...}
In other words, the value of the actualParameter key in the optional arguments hash is a list of hashes,
each
representing one actual parameter. If the subprocedure call only takes one actual parameter, the value of
the
actualParameter key can be specified as just the hash representing the one parameter:
actualParameter => {actualParameterName => 'parm1', value => 'myval'}

Example
$cmdr->createStep("Test Proj", "Run Build", "Common Cleanup", {subprocedure => "Del
ay",
actualParameter => {actualParameterName => 'Delay Time', value => '5'}});

ectool
syntax: ectool createStep <projectName> <procedureName> <stepName> ...
Specifying actual parameters in an ectool call is also different than specifying other arguments.
Specify each key-value as an equal-sign delimited value:
ectool createStep ... --actualParameter "Delay Time=5" "parm2=val2"
Note: If the parameter name or value contains spaces, quotes are needed.

Examples
ectool createStep "Test Proj" "Run Build" "Compile" --command "make all"
ectool createStep "Test Proj" "Run Build" "Common Cleanup" --subprocedure "Delay"
--actualParameter "Delay Time=5"
Back to Top

463

ElectricCommander

deleteProcedure
Deletes a procedure, including all steps.
You must specify a projectName and procedureName.

Arguments

Descriptions
The name of the project that contains this procedure. The name

projectName

must be unique within the project.


Argument type: String
The name of the procedure that must be unique within the project.

procedureName
Argument type: String

Positional arguments
projectName, procedureName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deleteProcedure(<projectName>, <procedureName>);

Example
$cmdr->deleteProcedure("Test Proj", "Run Build");

ectool
syntax: ectool deleteProcedure <projectName> <procedureName>

Example
ectool deleteProcedure "Test Proj" "Run Build"
Back to Top

deleteStep
Deletes a step from a procedure.
You must specify projectName, procedureName, and stepName.

464

API Commands - Procedure Management

Arguments

Descriptions
The name of the project that contains this procedure. The name

projectName

must be unique within the project.


Argument type: String
The name of the procedure that must be unique within the project.

procedureName
Argument type: String
The name of the step that must be unique within the procedure.
stepName
Argument type: String

Positional arguments
projectName, procedureName, stepName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deleteStep(<projectName>, <procedureName>, <stepName>);

Example
$cmdr->deleteStep("Test Proj", "Run Build", "Compile");

ectool
syntax: ectool deleteStep <projectName> <procedureName> <stepName>

Example
ectool deleteStep "Test Proj" "Run Build" "Compile"
Back to Top

getProcedure
Finds a procedure by its name.
You must specify a projectName and a procedureName.

Arguments

Descriptions
The name of the project that contains this procedure. The name

projectName

must be unique within the project.


Argument type: String

465

ElectricCommander

Arguments

Descriptions
The name of the procedure that must be unique within the project.

procedureName
Argument type: String

Positional arguments
projectName, procedureName

Response
One procedure element, which includes the procedure ID, name, time created, job name
template, owner, resource name, workspace name, project name, and so on.

ec-perl
syntax: $cmdr->getProcedure(<projectName>, <procedureName>);

Example
$cmdr->getProcedure("Test Proj", "Run Build");

ectool
syntax: ectool getProcedure <projectName> <procedureName>

Example
ectool getProcedure "Test Proj" "Run Build"
Back to Top

getProcedures
Retrieves all procedures in one project.
You must specify the projectName.

Arguments

Descriptions
The name of the project that contains this procedure. The name

projectName

must be unique within the project.


Argument type: String

Positional arguments
projectName

Response
One or more procedure elements.

466

API Commands - Procedure Management

ec-perl
syntax: $cmdr->getProcedures(<projectName>);

Example
$cmdr->getProcedures("Test Proj");

ectool
syntax: ectool getProcedures <projectName>

Example
ectool getProcedures "Test Proj"
Back to Top

getStep
Retrieves a step from a procedure.
You must specify projectName, procedureName, and stepName.

Arguments

Descriptions
The name of the project that contains this procedure. The name

projectName

must be unique within the project.


Argument type: String
The name of the procedure that must be unique within the project.

procedureName
Argument type: String
The name of the step that must be unique within the procedure.
stepName
Argument type: String

Positional arguments
projectName, procedureName, stepName

Response
One step element.

ec-perl
syntax: $cmdr->getStep(<projectName>, <procedureName>, <stepName>);

Example
$cmdr->getStep("Test Proj", "Run Build", "Compile");

467

ElectricCommander

ectool
syntax: ectool getStep <projectName> <procedureName> <stepName>

Example
ectool getStep "Test Proj" "Run Build" "Compile"
Back to Top

getSteps
Retrieves all steps in a procedure.
You must specify the projectName and procedureName.

Arguments

Descriptions
The name of the project that contains this procedure. The name

projectName

must be unique within the project.


Argument type: String
The name of the procedure that must be unique within the project.

procedureName
Argument type: String

Positional arguments
projectName, procedureName

Response
Zero or more step elements.

ec-perl
syntax: $cmdr->getSteps(<projectName>, <procedureName>);

Example
$cmdr->getSteps("Test Proj", "Run Build");

ectool
syntax: ectool getSteps <projectName> <procedureName>

Example
ectool getSteps "Test Proj" "Run Build"
Back to Top

468

API Commands - Procedure Management

modifyProcedure
Modifies an existing procedure.
You must specify projectName and procedureName.

Arguments

Descriptions
The name of the project that contains this procedure. The name
must be unique within the project. You must also enter

projectName

procedureName.
Argument type: String
The name of the procedure that must be unique within the project.

procedureName

You must also enter projectName.


Argument type: String
Name of the credential in one of these forms:

credentialName

relative (for example, "cred1")The credential is assumed


to be in the project that contains the request target object.

absolute (for example,


"/projects/BuildProject/credentials/cred1")Tthe credential
can be from any specified project, regardless of the target
objects project.

Argument type: String

A plain text or HTML description for this object.


If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the
description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type: String
Job name format for jobs created by running this procedure.

jobNameTemplate
Argument type: String
New name of the procedure.
newName
Argument type: String

469

ElectricCommander

Arguments

Descriptions
The name of the default resource where steps belonging to this

resourceName

procedure will run. This name can be a resource pool name.


Argument type: String
If no time limit was specified on the calling step, time limits are
copied to the calling step from the procedure. If the procedure is
called from runProcedure (or a schedule), the time limit acts as a

timeLimit

global job timeout.


The "timer" for the procedure starts as soon as the calling step/job
becomes runnable (all preconditions are satisfied).
Argument type: String
Time limit units are hours|minutes|seconds.

timeLimitUnits
Argument type: TimeLimitUnits
The name of the default workspace where job output is stored.
workspaceName
Argument type: String

Positional arguments
projectName, procedureName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->modifyProcedure(<projectName>, <procedureName>, {...});

Example
$cmdr->modifyProcedure("Test Proj", "Run Build", {resourceName =>
"Windows - Bldg. 11"});

ectool
syntax: ectool modifyProcedure <projectName> <procedureName> ...

Example
ectool modifyProcedure "Test Proj" "Run Build"
--resourceName "Windows - Bldg. 11"
Back to Top

470

API Commands - Procedure Management

modifyStep
Modifies an existing step.
You must specify projectName, procedureName, and stepName.

Arguments

Descriptions
The name of the project that contains this procedure. The name
must be unique within the project. You must also enter

projectName

procedureName.
Argument type: String
The name of the procedure that must be unique within the project.

procedureName

You must also enter projectName.


Argument type: String
The name of the step that must be unique within the procedure.

stepName

You must also enter projectName and procedureName.


Argument type: String
Specifies the values to pass as parameters to the called
procedure. Each parameter value is specified with an
actualParameterName and a value. The

actualParameter

actualParameterName must match the name of a formal


parameter on the called procedure.
Argument type: Map
<Boolean flag - 0|1|true|false> If set to 1, this step will run
even if the job is aborted before the step completes. This a useful

alwaysRun

argument for running a "cleanup" step that should run whether the
job is successful or not.
Argument type: Boolean
<Boolean flag - 0|1|true|false> Use this flag to run the same
step on several resources at the same time. The step is

broadcast

"broadcast" to all resources listed in the resourceName.


Argument type: Boolean

471

ElectricCommander

Arguments

Descriptions
<Boolean flag - 0|1|true|false> If set to true, all actual

clearActualParameters

parameters will be removed from the step.


Argument type: Boolean
The step command.

command
Argument type: String
This option is supported only in Perl and ectool bindings - it is
not part of the XML protocol. The contents of the command file is
commandFile

read and stored in the "command" field. This is an alternative


argument for commandand is useful if the "command" field spans
multiple lines.
If empty or non-zero, the step will run. If set to "0", the step is
skipped. A useful setting during procedure development or when
re-running a job that has already completed some of the steps.

condition

Also, this argument is useful for conditional execution of steps


based on properties set by earlier steps.
Argument type: String
Name of the credential in one of these forms:

credentialName

relative (for example, "cred1")The credential is assumed


to be in the project that contains the request target object.

absolute (for example,


"/projects/BuildProject/credentials/cred1")Tthe credential
can be from any specified project, regardless of the target
objects project.

Argument type: String

A plain text or HTML description for this object.


If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the
description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type: String

472

API Commands - Procedure Management

Arguments

Descriptions
Determines what happens to the procedure if the step fails:
failProcedure- The current procedure continues, but the overall
status is error (default).
l

abortProcedure- Aborts the current procedure, but


allows already-running steps in the current procedure to
complete.

abortProcedureNow- Aborts the current procedure and


terminates running steps in the current procedure.

abortJob- Aborts the entire job, terminates running steps,


but allows alwaysRunsteps to run.

abortJobNow- Aborts the entire job and terminates all


running steps, including alwaysRun steps.

ignore - Continues as if the step succeeded.

errorHandling

Argument type: ErrorHandling


The value for exclusive is a <Boolean flag -0|1|true|false>.
If set to 1, this indicates this step should acquire and retain this
exclusive

resource exclusively. The default is false.


When you set exclusive, exclusiveMode is set to job.
Argument type: Boolean
Use one of the following options:
l

None - the "default", which does not retain a resource.

Job - keeps the resource for the duration of the job. No


other job can use this resource, regardless of its step limit,
until this job completes or "Release Exclusive" is used in a
step. Future steps for this job will use this resource in
preference to other resources--if this resource meets the
needs of the steps and its step limit is not exceeded.

Step - keeps the resource for the duration of the step.

Call - keeps the resource for the duration of the procedure


that called this step, which is equivalent to 'job' for top level
steps.

exclusiveMode

Argument type: ExclusiveMode


A custom log file name produced by running the step. By default,
logFileName

ElectricCommander assigns a unique name to this file.


Argument type: String

473

ElectricCommander

Arguments

Descriptions
New name of the step.

newName
Argument type: String
<Boolean flag - 0|1|true|false> This indicates if this step
should run at the same time as adjacent steps also marked to run
parallel

as parallel.
Argument type: String
By default, if the step has no precondition, it will run when
scheduled. Set this property to make a step wait until one or more
dependent conditions are met. When a job step is eligible to
transition from pending to runnable, a precondition is evaluated.
A precondition is a fixed text or text embedding property reference
that is evaluated to TRUE or FALSE. An empty string, a \"0\" or
\"false\" is interpreted as FALSE. Any other result string is
interpreted as TRUE. The step will block until the precondition is
TRUE.
Precondition example:
Assume we defined these 4 steps:
1. Build object files and executables
2. Build installer
3. Run unit tests
4. Install bits on test system

precondition

Step 1 is an ordinary serial step.


Steps 2 and 3 can run in parallel because they depend only on
step 1's completion.
Step 4 depends on step 2, but not step 3.
You can achieve optimal step execution order with
preconditions:
l

Make steps 2-4 run in parallel.

Step 2 needs a job property set at the end of its step to


indicate step 2 is completing
(/myJob/buildInstallerCompleted=1).

Set a precondition in step 4:


$[/myJob/buildInstallerCompleted]

Argument type: String

474

API Commands - Procedure Management

Arguments

Descriptions
The name of a program to run (script) after a step completes. This
program looks at the step output to find errors and warnings.

postProcessor

ElectricCommander includes a customizable program called


"postp" for this purpose.
Argument type: String
<Boolean flag - 0|1|true|false>
This declares whether or not this step will release its resource,
which is currently held exclusively.

releaseExclusive
Note: Setting this flag to "true" is the same as setting
releaseMode to "release".
Argument type: Boolean
Use one of the following options:
l

none - the "default" - no action if the resource was not


previously marked as "retain."

release - releases the resource at the end of this step. If


the resource for the step was previously acquired with
"Retain exclusive" (either by this step or some preceding
step), the resource exclusivity is canceled at the end of this
step. The resource is released in the normal way so it may
be acquired by other jobs.

releaseToJob - allows a step to promote a Step exclusive


resource to a Job exclusive resource.

releaseMode

Argument type: ReleaseMode


The name of the resource used by this step. The name must be
resourceName

unique among all resources.


Argument type: String
Whereshell is the name of a program used to execute commands
contained in the "command" field. The name of a temporary file
containing commands will be appended to the end of this
invocation line.

shell

Normally, this file is a command shell, but it could be any other


command line program. The default is to use the standard shell for
the platform it runs on.
Argument type: String

475

ElectricCommander

Arguments

Descriptions
The name of the nested procedure to call when this step runs. If a
subprocedure is specified, do not include the commandor

subprocedure

commandField.
Argument type: String
If a subprocedureargument is used, this is the name of the
project where that subprocedure is found.

subproject

By default, the current project is used.


Argument type: String
The maximum length of time the step is allowed to run. After the

timeLimit

time specified, the step will be aborted.


Argument type: String
Units for step time limit: <hours|minutes|seconds>

timeLimitUnits
Argument type: TimeLimitUnits
The Commander agent sets this directory as the "current working
directory," running the command contained in the step. If no
workingDirectory

working directory is specified in the step, Commander uses the


directory it created for the job in the Commander workspace.
Argument type: String
The name of the workspace used by this step.

workspaceName
Argument type: String

Positional arguments
projectName, procedureName, stepName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->modifyStep(<projectName>, <procedureName>, <stepName>,
{<optionals>});

Example
$cmdr->modifyStep("Test Proj", "Run Build", "Compile", {commandFile => "tempfile.tx
t"});

476

API Commands - Procedure Management

ectool
syntax: ectool modifyStep <projectName> <procedureName> <stepName> ...

Example
ectool modifyStep "Test Proj" "Run Build" "Compile" --commandFile tempfile.txt
Back to Top

moveStep
Moves a step within a procedure.
You must specify projectName, procedureName, and stepName.

Arguments

Descriptions
The name of the project that contains this procedure. The name
must be unique within the project. You must also enter

projectName

procedureName.
Argument type: String
The name of the procedure that must be unique within the project.

procedureName

You must also enter projectName.


Argument type: String
The name of the step that must be unique within the procedure.

stepName

You must also enter projectName and procedureName.


Argument type: String
Moves the step (stepName) to position before the step "named" by
this option. If omitted, stepName is moved to the end of the list of

beforeStep

steps.
Argument type: String

Positional arguments
projectName, procedureName, stepName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->moveStep(<projectName>, <procedureName>, <stepName>, {<optionals>});

477

ElectricCommander

Example
$cmdr->moveStep("Test Proj", "Run Build", "Get Sources", {beforeStep => "Compil
e"});

ectool
syntax: ectool moveStep <projectName> <procedureName> <stepName> ...

Example
ectool moveStep "Test Proj" "Run Build" "Get Sources"
--beforeStep "Compile"
Back to Top

478

API Commands - Process

API Commands - Process


createProcess on page 479
deleteProcess on page 480
getProcess on page 482
getProcesses on page 483
modifyProcess on page 484
runProcess on page 486

createProcess
Creates a new process for an application or component.
Required Arguments
projectName
Description: Name of the project; must be unique among all projects.
Argument Type: String
processName
Description: Name of the process.
Argument Type: String
Optional Arguments
applicationName
Description: Name of the application, if the process is owned by an application; must be unique among all
projects.
Argument Type: String
componentApplicationName
Description: If specified, the component is scoped to this application, not the project.
Argument Type: String
componentName
Description: Name of the component, if the process is owned by a component.
Argument Type: String
credentialName
Description: Name of a credential to attach to this process.

479

ElectricCommander

Argument Type: String


description
Description: Comment text describing this object; not interpreted at all by ElectricCommander.
Argument Type: String
processType
Description: Defines the type of action performed by the process.
Argument Type: ProcessType
timeLimit
Description: Maximum amount of time that the step can execute; abort if it exceeds this time.
Argument Type: String
timeLimitUnits
Description: Units for the step- time limit: seconds, minutes, or hours.
Argument Type: TimeLimitUnits
workspaceName
Description: Name of the default workspace for this process.
Argument Type: String
Response
Returns a process component element.
ec-perl
Syntax:
$<object>->createProcess(<projectName>, <processName>, {<optionals>});
Example:
$ec->createProcess("default", "process1", {componentName => "VCScomponent"});
ectool
Syntax:
ectool createProcess <projectName> <processName> [optionals...]
Example:
ectool createProcess default newProcess --componentName VCScomponent

deleteProcess
Deletes an application or component process.

480

API Commands - Process

Required Arguments
projectName
Description: Name of the project; must be unique among all projects.
Argument Type: String
processName
Description: Name of the process.
Argument Type: String
Optional Arguments
applicationName
Description: Name of the application, if the process is owned by an application; must be unique among all
projects.
Argument Type: String
componentApplicationName
Description: If specified, the component is scoped to this application, not the project.
Argument Type: String
componentName
Description: Name of the component, if the process is owned by a component.
Argument Type: String
Response
None or a status OK message.
ec-perl
Syntax:
$<object>->deleteProcess(<projectName>, <processName>, {<optionals>});
Example:
$ec->deleteProcess("default", "newProcess", {componentName => "Component1"});
ectool
Syntax:
ectool deleteProcess <projectName> <processName> [optionals...]
Example:
ectool deleteProcess default newProcess --componentName Component1

481

ElectricCommander

getProcess
Retrieves an application or component process.
Required Arguments
projectName
Description: Name of the project; must be unique among all projects.
Argument Type: String
processName
Description: Name of the process.
Argument Type: String
Optional Arguments
applicationEntityRevisionId
Description: The revision ID of the versioned project.
Argument Type: UUID
applicationName
Description: Name of the application, if the process is owned by an application, that must be unique among
all projects.
Argument Type: String
componentApplicationName
Description: If specified, the component is scoped to this application, not the project.
Argument Type: String
componentName
Description: Name of the component, if the process is owned by a component.
Argument Type: String
Response
Retrieves the specified process element.
ec-perl
Syntax:
$<object>->getProcess(<projectName>, <processName>, {<optionals>});
Example:
$ec->getProcess("default", "newProcess", {componentName => "VCS"});
ectool
Syntax:

482

API Commands - Process

ectool getProcess <projectName> <processName> [optionals...]


Example:
ectool getProcess default newProcess

--componentName VCScomponent

getProcesses
Retrieves all processes in an application or component.
Required Arguments
projectName
Description: Name of the project; must be unique among all projects.
Argument Type: String
Optional Arguments
applicationEntityRevisionId
Description: The revision ID of the versioned project.
Argument Type: UUID
applicationName
Description: Name of the application, if the process is owned by an application, that must be unique among
all projects.
Argument Type: String
componentApplicationName
Description: If specified, the component is scoped to this application, not the project.
Argument Type: String
componentName
Name of the component, if the process is owned by a component.
Argument Type: String
Response
Retrieves the specified process element.
ec-perl
Syntax:
$<object>->getProcess(<projectName>, <processName>, {<optionals>});
Example:
$ec->getProcess("default", "newProcess", {componentName => "VCS"});

483

ElectricCommander

ectool
Syntax:
ectool getProcess <projectName> <processName> [optionals...]
Example:
ectool getProcess default newProcess

--componentName VCScomponent

applicationName
Description: Name of the application, if the process is owned by an application; must be unique among all
projects.
Argument Type: String
componentApplicationName
Description: Application name of the component, if the component is scoped to application.
Argument Type: String
componentName
Description: Name of the component, if the process is owned by a component.
Argument Type: String
Response
Retrieves zero or more process elements.
ec-perl
Syntax:
$<object>->getProcesses(<projectName>, {<optionals>});
Example:
$ec->getProcesses("default",

{componentName => "VCS"});

ectool
Syntax:
ectool getProcesses <projectName> [optionals...]
Example:
ectool getProcesses default --componentName VCScomponent

modifyProcess
Modifies an existing process.
Required Arguments
projectName
Description: Name of the project; must be unique among all projects.

484

API Commands - Process

Argument Type: String


processName
Description: Name of the process.
Argument Type: String
Optional Arguments
applicationName
Description: Name of the application, if the process is owned by an application; must be unique among all
projects.
Argument Type: String
componentApplicationName
Description: If specified, the component is scoped to this application, not the project.
Argument Type: String
componentName
Description: Name of the component, if the process is owned by a component.
Argument Type: String
credentialName
Description: Name of a credential to attach to this process.
Argument Type: String
description
Description: Comment text describing this object; not interpreted at all by ElectricCommander.
Argument Type: String
newName
Description: New name for an existing object that is being renamed.
Argument Type: String
processType
Description: Defines the type of action performed by the process.
Argument Type: ProcessType
timeLimit
Description: Maximum amount of time that the step can execute; abort if it exceeds this time.
Argument Type: String
timeLimitUnits

485

ElectricCommander

Description: Units for step time limit: seconds, minutes, or hours.


Argument Type: TimeLimitUnits
workspaceName
Description: Name of the default workspace for this process.
Argument Type: String
Response
Retrieves an updated process element.
ec-perl
Syntax:
$<object>->modifyProcess (<projectName>, <processName>, {<optionals>});
Example:
$ec->modifyProcess("default", "newProcess", {componentName => "VCS", newName =>
"VCScomponent", description => "An updated description"});
ectool
Syntax:
ectool modifyProcess <projectName> <processName> [optionals...]
Example:
ectool modifyProcess default newProcess
VCS --description "A description"

--componentName VCScomponent --newName

runProcess
Runs the specified process.
Required Arguments
projectName
Description: Name for the project; must be unique among all projects.
Argument Type: String
applicationName
Description: Name of the application that owns the process; must be unique among all applications in the
project.
Argument Type: String
processName
Description: Name of the application process.
Argument Type: String

486

API Commands - Process

Optional Arguments
actualParameter
Description: Parameters passed as arguments to the process.
Argument Type: Map
destinationProject
Description: Project that will own the job.
Argument Type: String
environmentName
Description: Name of the environment.
Argument Type: String
Argument Type:
environmentTemplateName
Description: Name of the environment template.
Argument Type: String
keepOnError
Description: Set this flag to "true" to keep the environment when an error occurs .
The keepOnError value = <Boolean flag -0|1|true|false>.
Defaults to "false". Name of the environment template tier.
Argument Type: Boolean
environmentTemplateTierMapName
Description: Name of the environment template tier.
Argument Type: String
priority
Description: Priority of the job.
Argument Type: JobPriority
scheduleName
Description: Name for the schedule that must be unique among all schedules for the project.
Argument Type: String
snapshotName
Description: Name for the snapshot that must be unique among all snapshots for the project.
Argument Type: String

487

ElectricCommander

tierMapName
Description: Name of the tier map used to determine where to run the process.
Argument Type: String
tierResourceCounts
Description: Resource count for each resource template tier.
Argument Type: Map
validate
Description: Validates that the application process, tier map, and environment are well-defined and valid
before the running the application process. This argument defaults to true.
Argument Type: Boolean
Response
Returns new job ID.
ec-perl
Syntax:
$<object>->runProcess(<projectName>, <applicationName>, <processName>, <tierMapN
ame>, {<optionals>});
Example:
$ec->runProcess("default", "NewApp", "newProcess", "TierMap2", {destinationProje
ct => "deploy1"});
ectool
Syntax:
ectool runProcess <projectName> <applicationName> <processName> <tierMapName> [o
ptionals...]
Example:
ectool runProcess default NewApp newProcess TierMap2 --destinationProject deploy
1

488

API Commands - Process Dependency

API Commands - Process Dependency


createProcessDependency on page 489
deleteProcessDependency on page 490
getProcessDependencies on page 492
modifyProcessDependency on page 493

createProcessDependency
Creates a dependency between two process steps.
Required Arguments
projectName
Description: Name of the project; must be unique among all projects.
Argument Type: String
processName
Description: Name of the process.
Argument Type: String
processStepName
Description: Name of the process step.
Argument Type: String
targetProcessStepName
Description: Name of the target process step.
Argument Type: String
Optional Arguments
applicationName
Description: Name of the application, if the process is owned by an application; must be unique among all
projects.
Argument Type: String
branchCondition
Description: Condition of the branch.
Argument Type: String
branchConditionName

489

ElectricCommander

Description: Name of the branch condition.


Argument Type: String
branchConditionType
Description: Type of the branch condition.
Argument Type: BranchConditionType
branchType
Description: Type of the branch.
Argument Type: BranchType
componentApplicationName
Description: If specified, the component is scoped to this application not the project.
Argument Type: String
componentName
Description: Name of the component, if the process is owned by a component.
Argument Type: String
Response
Returns a process dependency element.
ec-perl
Syntax:
$<object>->createProcessDependency(<projectName>, <processName>,
<processStepName>, <targetProcessStepName>, {<optionals>});
Example:
$ec->createProcessDependency("default", "newProcess", "Step C", "Step D", {compo
nentName => "VCScomponent"});
ectool
Syntax:
ectool createProcessDependency <projectName> <processName> <processStepName>
<targetProcessStepName> [optionals...]
Example:
ectool createProcessDependency default newProcess "Step A" "Step "B" --component
Name VCScomponent

deleteProcessDependency
Deletes a dependency between two process steps.

490

API Commands - Process Dependency

Required Arguments
projectName
Description: Name of the project; must be unique among all projects.
Argument Type: String
processName
Description: Name of the process.
Argument Type: String
processStepName
Description: Name of the process step.
Argument Type: String
targetProcessStepName
Description: Name of the target process step.
Argument Type: String
Optional Arguments
applicationName
Description: Name of the application, if the process is owned by an application; must be unique among all
projects.
Argument Type: String
componentApplicationName
Description: If specified, the component is scoped to this application, not the project.
Argument Type: String
componentName
Description: Name of the component, if the process is owned by a component.
Argument Type: String
Response
None or a status OK message.
ec-perl
Syntax:
$<object>->deleteProcessDependency(<projectName>, <processName>, <processStepNam
e>, <targetProcessStepName>, {<optionals>});
Example:

491

ElectricCommander

$ec->deleteProcessDependency("default", "newProcess", "Step B", "Step C", {compo


nentName => "VCScomponent"});
ectool
Syntax:
ectool deleteProcessDependency <projectName> <processName> <processStepName> <ta
rgetProcessStepName> [optionals...]
Example:
ectool deleteProcessDependency default newProcess "Step B" "Step C" --componentN
ame VCScomponent

getProcessDependencies
Retrieves all dependencies for a process.
Required Arguments
projectName
Description: Name of the project; must be unique among all projects.
Argument Type: String
processName
Description: Name of the process.
Argument Type: String
Optional Arguments
applicationEntityRevisionId
Description: The revision ID of the versioned project.
Argument Type: UUID
applicationName
Description: Name of the application, if the process is owned by an application; must be unique among all
projects.
Argument Type: String
componentApplicationName
Description: If specified, the component is scoped to this application, not the project.
Argument Type: String
componentName
Description: Name of the component, if the process is owned by a component.
Argument Type: String

492

API Commands - Process Dependency

Response
Retrieves zero or more process dependency elements.
ec-perl
Syntax:
$<object>->getProcessDependencies(<projectName>, <processName>, {<optionals>});
Example:
$ec->getProcessDependencies("default", "newProcess", {componentName => "VCScompo
nent"});
ectool
Syntax:
ectool getProcessDependencies <projectName> <processName> [optionals...]
Example:
ectool getProcessDependencies default newProcess --componentName VCScomponent

modifyProcessDependency
Modifies a dependency between two process steps.
Required Arguments
projectName
Description: Name of the project; must be unique among all projects.
Argument Type: String
processName
Description: Name of the process.
Argument Type: String
processStepName
Description: Name of the process step.
Argument Type: String
targetProcessStepName
Description: Name of the target process step.
Argument Type: String
Optional Arguments
applicationName
Description: Name of the application, if the process is owned by an application.

493

ElectricCommander

Argument Type: String


branchCondition
Description: Condition of the branch.
Argument Type: String
branchConditionName
Description: Name of the branch condition.
Argument Type: String
branchConditionType
Description: Type of the branch condition.
Argument Type: BranchConditionType
branchType
Description: Type of the branch.
Argument Type: BranchType
componentApplicationName
Description: If specified, the component is scoped to this application, not the project.
Argument Type: String
componentName
Description: Name of the component, if the process is owned by a component.
Argument Type: String
ec-perl
Syntax:
$<object>->modifyProcessDependency(<projectName>, <processName>, <processStepNam
e>, <targetProcessStepName>, {<optionals>});
Example:
$ec->modifyProcessDependency("default", "newProcess", "Step1", "StepA", {compone
ntName => "VCScomponent"});
ectool
Syntax:
ectool modifyProcessDependency <projectName> <processName> <processStepName> <ta
rgetProcessStepName> [optionals...]
Example:
ectool modifyProcessDependency default newProcess Step1 StepA --componentName VC
Scomponent

494

API Commands - Process Step

API Commands - Process Step


createProcessStep on page 495
deleteProcessStep on page 498
getProcessStep on page 499
getProcessSteps on page 500
modifyProcessStep on page 501

Note: Several of the following API commands have context type optional arguments. For example, a step
command may reference either a procedure or component.

createProcessStep
Creates a new process step.
Required Arguments
projectName
Description: Name for the project; must be unique among all projects.
Argument Type: String
processName
Description: Name of the process.
Argument Type: String
processStepName
Description: Name of the process step.
Argument Type: String
Optional Arguments
actualParameter
Description: Actual parameters (<var1>=<val1> [<var2>=<val2> ...) passed to an invoked subprocedure or
process.
Argument Type: Map
afterProcessStep
Description: If specified, the process step will be placed after the named process step.
Argument Type: String
applicationName

495

ElectricCommander

Description: Name of the application, if the process is owned by an application; must be unique among all
projects.
Argument Type: String
applicationTierName
Description: Application tier on which to run the step.
Argument Type: String
beforeProcessStep
Description: If specified, the process step will be placed before the named process step.
Argument Type: String
componentName
Description: Name of the component, if the process is owned by a component.
Argument Type: String
credentialName
Description: Name of the credential object.
Argument Type: String
description
Description: Comment text describing this object; not interpreted at all by the ElectricCommander platform.
Argument Type: String
errorHandling
Description: Specifies error handling for this step.
Argument Type: ErrorHandling
includeCompParameterRef
Description: True if the actual parameters should be generated from component properties. Works for
artifact components only.
Argument Type: Boolean
processStepType
Description: Defines type of the process step.
Argument Type: ProcessStepType
subcomponent
Description: If referencing a component process, the name of the component.
Argument Type: String

496

API Commands - Process Step

subcomponentProcess
Description: If referencing a component process, the name of the component process.
Argument Type: String
subprocedure
Description: If referencing a procedure, the name of the procedure.
Argument Type: String
subproject
Description: If referencing a procedure, the name of the procedure's project.
Argument Type: String
timeLimit
Description: Maximum amount of time that the step can execute; abort if it exceeds this time.
Argument Type: String
timeLimitUnits
Description: Units for the step time limit: seconds, minutes, or hours.
Argument Type: TimeLimitUnits
workspaceName
Description: Name of the workspace.
Argument Type: String
Response
Returns a process step element.
ec-perl
Syntax:
$<object>->createProcessStep(<projectName>, <processName>, <processStepName>, {<
optionals>});
Example:
$ec->createProcessStep("default", "newProcess", "Step 1", {componentName => "VCS
component"});
ectool
Syntax:
ectool createProcessStep <projectName> <processName> <processStepName>
[optionals...]
Example:
ectool createProcessStep default newProcess "Step A" --componentName VCScomponen
t

497

ElectricCommander

deleteProcessStep
Deletes an application or component process step.
Required Arguments
projectName
Description: Name for the project; must be unique among all projects.
Argument Type: String
processName
Description: Name of the process.
Argument Type: String
processStepName
Description: Name of the process step.
Argument Type: String
Optional Arguments
applicationName
Description: Name of the application, if the process is owned by an application; must be unique among all
projects.
Argument Type: String
componentApplicationName
Description: If specified, the component is scoped to this application, not the project.
Argument Type: String
componentName
Description: Name of the component, if the process is owned by a component.
Argument Type: String
Response
None or a status OK message.
ec-perl
Syntax:
$<object>->deleteProcessStep
{<optionals>});

(<projectName>, <processName>, <processStepName>,

Example:
$ec->deleteProcessStep ("default", "newProcess", "stepToDelete", {componentName
=> "VCScomponent"});

498

API Commands - Process Step

ectool
Syntax:
ectool deleteProcessStep <projectName> <processName> <processStepName> [optional
s...]
Example:
ectool deleteProcessStep
component

default newProcess "stepToDelete" --componentName VCS

getProcessStep
Gets an application or component process step.
Required Arguments
projectName
Description: Name for the project; must be unique among all projects.
Argument Type: String
processName
Description: The name of the process.
Argument Type: String
processStepName
Description: The name of the process step.
Argument Type: String
Optional Arguments
applicationEntityRevisionId
Description: The revision ID of the versioned project.
Argument Type: UUID
applicationName
Description: Name of the application, if the process is owned by an application; must be unique among all
projects.
Argument Type: String
componentApplicationName
Description: If specified, the component is scoped to this application, not the project.
Argument Type: String
componentName

499

ElectricCommander

Description: Name of the component, if the process is owned by a component.


Argument Type: String
Response
Retrieves the specified process step element.
ec-perl
Syntax:
$<object>->getProcessStep(<projectName>, <processName>, <processStepName>, {<opt
ionals>});
Example:
$ec->getProcessStep("default", "newProcess", "Step 1", {componentName => "VCScom
ponent"});
ectool
Syntax:
ectool getProcessStep <projectName> <processName> <processStepName> [optional
s...]
Example:
ectool getProcessStep

default newProcess "Step A" --componentName VCScomponent

getProcessSteps
Retrieves all the process steps in an application or component process.
Required Arguments
projectName
Description: Name for the project; must be unique among all projects.
Argument Type: String
processName
Description: Name of the process.
Argument Type: String
Optional Arguments
applicationEntityRevisionId
Description: The revision ID of the versioned project.
Argument Type: UUID
applicationName

500

API Commands - Process Step

Description: Name of the application, if the process is owned by an application; must be unique among all
projects.
Argument Type: String
componentApplicationName
Description: If specified, the component is scoped to this application, not the project.
Argument Type: String
componentName
Description: Name of the component, if the process is owned by a component.
Argument Type: String
Response
Retrieves zero or more process step elements.
ec-perl
Syntax:
$<object>->getProcessSteps(<projectName>, <processName>, {<optionals>});
Example:
$ec->getProcessSteps("default", "newProcess", {componentName=> "VCScomponent"});
ectool
Syntax:
ectool getProcessSteps

<projectName> <processName> [optionals...]

Example:
ectool getProcessSteps

default newProcess

--componentName VCScomponent

modifyProcessStep
Modifies an existing process step.
Required Arguments
projectName
Description: Name of the project; must be unique among all projects.
Argument Type: String
processName
Description: Name of the process.
Argument Type: String
processStepName

501

ElectricCommander

Description: Name of the process step.


Argument Type: String
Optional Arguments
actualParameter
Description: Actual parameters passed to an invoked subprocedure or process.
Argument Type: Map
afterProcessStep
Description: If specified, the process step will be placed after the named process step.
Argument Type: String
applicationName
Description: Name of the application, if the process is owned by an application; must be unique among all
projects.
Argument Type: String
applicationTierName
Description: Name of the application tier on which to run the step.
Argument Type: String
beforeProcessStep
Description: If specified, the process step will be placed before the named process step.
Argument Type: String
clearActualParameters
Description: True if the step should remove all actual parameters.
Argument Type: Boolean
componentApplicationName
Description: If specified, the component is scoped to this application not the project.
Argument Type: String
componentName
Description: Name of the component, if the process is owned by a component.
Argument Type: String
credentialName
Description: Name of the credential object.
Argument Type: String

502

API Commands - Process Step

description
Description: Comment text describing this object; not interpreted at all by the ElectricCommander platform.
Argument Type: String
errorHandling
Description: Specifies error handling for this step.
Argument Type: ErrorHandling
includeCompParameterRef
Description: True if the actual parameters should be generated from component properties. Works for
artifact components only.
Argument Type: Boolean
newName
Description: New name for an existing object that is being renamed.
Argument Type: String
processStepType
Description: Defines type of the process step.
Argument Type: ProcessStepType
subcomponent
Description: If referencing a component process, the name of the component.
Argument Type: String
subcomponentApplicationName
Description: If referencing a component process, the name of the component application (if it has not been
scoped to a project).
Argument Type: String
subcomponentProcess
Description: If referencing a component process, the name of the component process.
Argument Type: String
subprocedure
Description: If referencing a procedure, the name of the procedure.
Argument Type: String
subproject
Description: If referencing a procedure, the name of the procedure's project.

503

ElectricCommander

Argument Type: String


timeLimit
Description: Maximum amount of time that the step can execute; abort if it exceeds this time.
Argument Type: String
timeLimitUnits
Description: Units for the step time limit: seconds, minutes, or hours.
Argument Type: TimeLimitUnits
workspaceName
Description: Name of the workspace.
Argument Type: String
Response
Retrieves an updated process step element.
ec-perl
Syntax:
$<object>->modifyProcessStep(<projectName>, <processName>, <processStepName>, {<
optionals>});
Example:
$ec->modifyProcessStep ("default", "newProcess", "Step 1", {componentName => "VC
Scomponent", newName => "Step 2", description => "A description"};
ectool
Syntax:
ectool modifyProcessStep <projectName> <processName> <processStepName> [optional
s...]
Example:
ectool modify ProcessStep newProcess "Step A" --componentName VCScomponent --new
Name "Step B" --description "A description"

504

API Commands - Project Management

API Commands - Project Management


createProject
deleteProject
getProject
getProjects
modifyProject
reloadSetupScripts on page 510

createProject
Creates a new project.
You must specify a projectName.

Arguments

Descriptions
The name of the project that must be unique within the project.

projectName
Argument type: String
Name of the credential in one of these forms:

credentialName

relative (for example, "cred1")The credential is assumed


to be in the project that contains the request target object.

absolute (for example,


"/projects/BuildProject/credentials/cred1")Tthe credential
can be from any specified project, regardless of the target
objects project.

Argument type: String


A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the
description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type: String
The name of the resource to use as the default for steps run by

resourceName

procedures in this project.


Argument type: String

505

ElectricCommander

Arguments

Descriptions
<Boolean flag - 0|1|true|false> If set to 1 or true, Change

tracked

Tracking is enabled for the project.


Argument type: Boolean
The name of a workspace to use as the default for steps run by

workspaceName

procedures in this project.


Argument type: String

Positional arguments
projectName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->createProject(<projectName>, {<optionals>});

Example
$cmdr->createProject("Test Proj", {workspaceName => "Test_WS"});

ectool
syntax: ectool createProject <projectName> ...

Example
ectool createProject "Test Proj" --workspaceName "Test WS"
Back to Top

deleteProject
Deletes a project, including all procedures, procedure steps, and jobs within that project.
You must specify a projectName.

Arguments

Descriptions
The name of the project that must be unique within the project.

projectName
Argument type: String

506

API Commands - Project Management

Arguments

Descriptions
(Optional) <Boolean flag - 0|1|true|false> If set to 1 or true,
the object in the foreground is deleted. The default is to delete the

foreground

object in the background.


Argument type: Boolean

Positional arguments
projectName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deleteProject(<projectName>, {<optionals>});

Example
$cmdr->deleteProject("Test Proj");

ectool
syntax: ectool deleteProject <projectName> ...

Example
ectool deleteProject "Test Proj"
Back to Top

getProject
Finds a project by its name.
You must specify a projectName.

Arguments

Descriptions
The name of the project that must be unique within the project.

projectName
Argument type: String

Positional arguments
projectName

Response
One project element.

507

ElectricCommander

ec-perl
syntax: $cmdr->getProject(<projectName>);

Example
$cmdr->getProject("Test Proj");

ectool
syntax: ectool getProject <projectName>

Example
ectool getProject "Test Proj"
Back to Top

getProjects
Retrieves all projects.

Arguments

Descriptions

None

Positional arguments
None

Response
Zero or more project elements.
Note: This response includes all projects in the system, including plugin projects, which are not
displayed on the Projects page in the web UI.

ec-perl
syntax: $cmdr->getProjects();

Example
$cmdr->getProjects();

ectool
syntax: ectool getProjects

Example
ectool getProjects
Back to Top

508

API Commands - Project Management

modifyProject
Modifies an existing project.
You must specify a projectName.

Arguments

Descriptions
The name of the project that must be unique within the project.

projectName
Argument type: String
Name of the credential in one of these forms:

credentialName

relative (for example, "cred1")The credential is assumed


to be in the project that contains the request target object.

absolute (for example,


"/projects/BuildProject/credentials/cred1")Tthe credential
can be from any specified project, regardless of the target
objects project.

Argument type: String

A plain text or HTML description for this object.


If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the
description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type: String
New name of the project.

newName
Argument type: String
The name of the resource used as the default for steps run by
resourceName

procedures in this project.


Argument type: String
<Boolean flag - 0|1|true|false> If set to 1 or true, Change

tracked

Tracking is enabled for the project.


Argument type: Boolean
The name of the default workspace where job output is stored.

workspaceName
Argument type: String

509

ElectricCommander

Positional arguments
projectName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->modifyProject(<projectName>, {...});

Example
$cmdr->modifyProject("Test Proj", {description => "A very simple project"});

ectool
syntax: ectool modifyProject <projectName> ...

Example
ectool modifyProject "Test Proj" --description "A very simple project"
Back to Top

reloadSetupScripts
Runs new, modified, or previously unsuccessful setup scripts.

Arguments

Descriptions

None

Positional arguments
None

Response
None or a status OK message.

ec-perl
syntax:$cmdr->reloadSetupScripts ();

Example
$cmdr->reloadSetupScripts ();

ectool
syntax: ectool reloadSetupScripts

Example
ectool reloadSetupScripts

510

API Commands - Project Management

Back to Top

511

ElectricCommander

API Commands - Property Management


createProperty
deleteProperty
evalScript
expandString
getProperties
getProperty
incrementProperty
modifyProperty
setProperty

createProperty
Creates a regular string or nested property sheet using a combination of property path and context.
You must specify a propertyName and locator arguments to define where (or on which object) you are creating
this property.
Note: The name "properties" is NOT a valid property name.

Arguments

Descriptions
The name of the property that must be unique within the property
sheet.

propertyName

It can be a relative or absolute property path, including "my" paths


such as "/myProject/prop1".
Argument type: String
(Optional) The name of the application container of the property
sheet which owns the property. The name must be unique among

applicationName

all projects.
Argument type: String
(Optional) The name of the application tier container of the

applicationTierName

property sheet which owns the property.


Argument type: String
(Optional) The name of the artifact container of the property sheet

artifactName

which owns the property.


Argument type: String

512

API Commands - Property Management

Arguments

Descriptions
(Optional) The name of the artifact version.
Note: An artifact version name is interpreted by the server as
the artifactVersionName attribute for the

artifactVersionName

artifactVersion in question. This name is parsed and


interpreted as "groupId:artifactKey:version"and the
object is searched either way you specify its name. The
Commander server interprets either name form correctly.
Argument type: String
(Optional) The name of the component container of the property

componentName

sheet which owns the property.


Argument type: String
(Optional) The name of the email configuration container that owns

configName

the property.
Argument type: String
(Optional) <Boolean flag - 0|1|true|false> If 1 or true, the

counter

property is used as a counter.


Argument type: Boolean
(Optional) The name of the credential container of the property
sheet which owns the property.
Name of the credential in one of these forms:
l

relative (for example, "cred1")The credential is assumed


to be in the project that contains the request target object.

absolute (for example,


"/projects/BuildProject/credentials/cred1")Tthe credential
can be from any specified project, regardless of the target
objects project.

credentialName

Argument type: String

513

ElectricCommander

Arguments

Descriptions
(Optional) A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the

description

text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol>
<p> <pre> <span> <style> <table> <tc> <td> <th>
<tr> <ul>
Argument type: String
(Optional) The name of the environment container of the property
sheet that owns the property. The name must be unique among all

environmentName

projects.
Argument type: String
(Optional) The name of the environment template container of the

environmentTemplateName

property sheet that owns the property.


Argument type: String

environmentTemplateTierName

(Optional) The name of the environment template tier container of


the property sheet that owns the property.
(Optional) The name of the environment tier container of the

environmentTierName

property sheet that owns the property.


Argument type: String
(Optional) Whether or not the property is recursively expandable.
<Boolean flag - 0|1|true|false>

expandable

This determines whether the property value will undergo property


expansion when it is fetched. The default is true.
Argument type: Boolean
(Optional) For simple property names, whether or not to search

extendedContextSearch

objects in the hierarchy to find the desired property.


Argument type: Boolean
(Optional) The name of the gateway container of the property

gatewayName

sheet.
Argument type: String

514

API Commands - Property Management

Arguments

Descriptions
(Optional) The name of the group group container of the property

groupName

sheet which owns the property.


Argument type: String
(Optional) The unique Commander-generated identifier (a UUID)
for a job that is assigned automatically when the job is created.

jobId

The system also accepts a job name assigned to the job by its
name template.
Argument type: UUID

jobStepId

(Optional) The unique identifier for a job step that is assigned


automatically when the job step is created.
(Optional) The name of the email notifier.

notifierName
Argument type: UUID
(Optional) The object identifier returned by findObjects and
objectId

getObjects.
Argument type: String
(Optional) Property path string.

path
Argument type: String
The name of the plugin container of the property sheet which owns
pluginName

the property.
Argument type: String
The name of the procedure container of the property sheet which
owns the property. When using this argument, you must also enter

procedureName

projectName.
Argument type: String
(Optional) The name of the process when the container is a

processName

process or process step.


Argument type: String

515

ElectricCommander

Arguments

Descriptions
(Optional) The name of the process step when the container is a

processStepName

process step.
Argument type: String
(Optional) The name of the project container of the property sheet
which owns the property. The name must be unique among all

projectName

projects.
Argument type: String
(Optional) The unique identifier for a property sheet that is

propertySheetId

assigned automatically when the property sheet is created.


Argument type: UUID
(Optional) Type of property: <string|sheet>

propertyType

This indicates whether to create a string property or a sub-sheet.


The default is string.
Argument type: PropertyType
(Optional) The name of the repository container of the property
sheet which owns the property. Use the repository for artifact

repositoryName

management.
Argument type: String
(Optional) The name of the resource container of the property
sheet which owns the property. You define the new property in this

resourceName

resource.
Argument type: String
(Optional) The name of the resource pool (with one or more

resourcePoolName

resources)container of the property sheet that owns the property.


Argument type: String
(Optional) The name of the resource template container of the

resourceTemplateName

property sheet that owns the property.


Argument type: String

516

API Commands - Property Management

Arguments

Descriptions
(Optional) The name of the schedule container of the property
sheet.

scheduleName

If you use a schedule name to define the location for the new
property, you must also enter projectName.
Argument type: String
(Optional) The name of the snapshot container of the property

snapshotName

sheet which owns the property.


Argument type: String

stateDefinitionName

(Optional) The name of the state definition container of the


property sheet which owns the property.
(Optional) The name of the state container of the property sheet

stateName

which owns the property


Argument type: String
(Optional) The name of the step container of the property sheet
which owns the property.

stepName

If you use a step name to define the location for the new property,
you must also enter projectName and procedureName.
Argument type: String
(Optional) The name of the special system object. In this context,

systemObjectName

only server is legal.


Argument type: SystemObjectName
(Optional) The name of the transition definition container of the

transitionDefinitionName

property sheet which owns the property.


Argument type: String
(Optional) The name of the transition container of the property

transitionName

sheet which owns the property.


Argument type: String

517

ElectricCommander

Arguments

Descriptions
(Optional) The name of the user container of the property sheet

userName

which owns the property.


Argument type: String
(Optional) For a string property (see propertyType ), this is the
value of the property. For a sheet property, this argument is invalid.

value
Argument type: String
(Optional) This option is supported only in Perl and ectool
bindings - it is not a part of the XML protocol.
valueFile

The contents of the valuefile is read and stored in the "value" field
for a string property. This is an alternative argument for value and
is useful if the value field spans multiple lines.
(Optional) The name of the workflow definition container of the

workflowDefinitionName

property sheet which owns the property.


Argument type: String
(Optional) The name of the workflow container of the property

workflowName

sheet which owns the property.


Argument type: String
(Optional) The name of the workspace container of the property

workspaceName

sheet
Argument type: String
(Optional) The name of the zone container of the property sheet.

zoneName
Argument type: String

Positional arguments
propertyName

Response
An XML stream that echoes the new property, including its ID, which is assigned by the ElectricCommander
server.

ec-perl
syntax: $cmdr->createProperty(<propertyName>, {<optionals>});

518

API Commands - Property Management

Examples
$cmdr->createProperty('/myJob/Runtime Env/PATH', {value => 'c:\bin'});
$cmdr->createProperty('Runtime Env/PATH', {value => 'c:\bin', });

ectool
syntax: ectool createProperty <propertyName> ...

Examples
ectool createProperty "/myJob/Runtime Env/PATH" --value "c:\bin"
ectool createProperty "Runtime Env/PATH" --value "c:\bin" --jobId 4fa765dd-73f1-11e
3-b67e-b0a420524153
ectool createProperty "Saved Variables" --propertyType sheet --jobId 4fa765dd-73f111e3-b67e-b0a420524153
Back to Top

deleteProperty
Deletes a property from a property sheet.
You must specify a propertyName and you must specify locator arguments to find the property you want to
delete.

Arguments

Descriptions
The name of the property that must be unique within the property

propertyName

sheet.
Argument type: String
The name of the application that must be unique among all

applicationName

projects.
Argument type: String
The name of the application tier.

applicationTierName
Argument type: String
The name of the artifact.
artifactName
Argument type: String

519

ElectricCommander

Arguments

Descriptions
The name of the artifact version.
Note: An artifact version name is interpreted by the server as
the artifactVersionName attribute for the

artifactVersionName

artifactVersion in question. This name is parsed and


interpreted as "groupId:artifactKey:version" and the
object is searched either way you specify its name. The
Commander server interprets either name form correctly.
Argument type: String
The name of the component.

componentName
Argument type: String
The name of the email configuration.
configName
Argument type: String
Whether or not the property is recursively expandable.
Name of the credential in one of these forms:

credentialName

relative (for example, "cred1")The credential is assumed


to be in the project that contains the request target object.

absolute (for example,


"/projects/BuildProject/credentials/cred1")Tthe credential
can be from any specified project, regardless of the target
objects project.

Argument type: String


The name of the environment that must be unique among all
environmentName

projects.
Argument type: String
The name of the environment template.

environmentTemplateName
Argument type: String
The name of the environment template tier.
environmentTemplateTierName
Argument type: String
The name of the environment tier.
environmentTierName
Argument type: String

520

API Commands - Property Management

Arguments

Descriptions
For simple property names, whether or not to search objects in the
hierarchy to find the desired property.
<Boolean flag -0|1|true|false> If set, and there is an object
specifier in the command, ElectricCommander first looks for the
property in that object specifier, but also searches in other
locations if not found, according to the following rules:

extendedContextSearch

1. If the object specifier is a procedure, ElectricCommander looks


for the property in the project where the procedure resides.
2. If the object specifier is a job step, Commander looks in the
actual parameters of the procedure to which it belongs, and then
looks at the job properties.
The d efault setting is true.
Argument type: Boolean
The name of the gateway.

gatewayName
Argument type: String
The name of a group that contains this property.
groupName
Argument type: String
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system
jobId

also accepts a job name assigned to the job by its name template.
Argument type: UUID
The unique identifier for a job step that is assigned automatically

jobStepId

when the job step is created.


Argument type: UUID
The name of the email notifier.

notifierName
Argument type: String
This is an object identifier returned by findObjects and
objectId

getObjects.
Argument type: String
Property path.

path
Argument type: String

521

ElectricCommander

Arguments

Descriptions
The name of a plugin that may contain a property you want to

pluginName

delete.
Argument type: String
The name of the procedure containing the property you want to

procedureName

delete.
Also requiresprojectName
Argument type: String
The name of the process when he container is a process or

processName

process step.
Argument type: String
The name of the process step when the container is a process

processStepName

step.
Argument type: String
The name of the project that contains the property you want to

projectName

delete.
Argument type: String
The unique identifier for a property sheet, assigned automatically

propertySheetId

when the property sheet is created.


Argument type: UUID
The name of the repository for artifact management.

repositoryName
Argument type: String
The name of the resource that contains the property you want to
resourceName

delete.
Argument type: String
The name of a pool containing one or more resources.

resourcePoolName
Argument type: String
The name of the resource template.
resourceTemplateName
Argument type: String

522

API Commands - Property Management

Arguments

Descriptions
The name of the schedule containing the property you want to
delete.

scheduleName

Also requiresprojectName.
Argument type: String
The name of the snapshot.

snapshotName
Argument type: String
The name of the state definition.
stateDefinitionName
Argument type: String
The name of the state.
stateName
Argument type: String
The name of the step containing the property you want to delete.
stepName

Also requiresprojectName and procedureName.


Argument type: String
The name of a special system object. Only "sever" is valid in this

systemObjectName

context.
Argument type: SystemObjectName
The name of the transition definition.

transitionDefinitionName
Argument type: String
The name of the transition.
transitionName
Argument type: String
The user name that contains this property.
userName
Argument type: String
The name of the workflow definition.
workflowDefinitionName
Argument type: String
The name of the workflow.
workflowName
Argument type: String

523

ElectricCommander

Arguments

Descriptions
The name of the zone.

zoneName
Argument type: String

Positional arguments
propertyName

Response
None or a status OK message.

ec-perl
syntax: $cmdr->deleteProperty(<propertyName>, { ... });

Example
$cmdr->deleteProperty("/projects/Sample project/Changeset ID");

ectool
syntax: ectool deleteProperty <propertyName> ...

Example
ectool deleteProperty "/projects/Sample project/Changeset ID"
Back to Top

evalScript
Evaluates a script in a given context.This API is similar to expandString except that it evaluates the value
argument as a Javascript block, without performing any property substitution on either the script or the result.
The string value of the final expression in the script is returned as the value element of the response.
You must specify a value to evaluate.

Arguments

Descriptions
Script to evaluate.

value
Argument type:String
(Optional)Name of the application that must be unique among all
applicationName

projects.
Argument type:String

524

API Commands - Property Management

Arguments

Descriptions
(Optional) Name of the application tier.

applicationTierName
Argument type:String
(Optional) Name of the artifact.
artifactName
Argument type:String
(Optional) Name of the artifact version.
Note: An artifact version name is interpreted by the server as the
artifactVersionName attribute for the artifactVersion in
question. This name is parsed and interpreted as
artifactVersionName

"groupId:artifactKey:version" and the object is searched


either way you specify its name. The Commander server interprets
either name form correctly.
Argument type:String
(Optional) Name of the component.

componentName
Argument type:String
(Optional) Name of the email configuration.
configName
Argument type:String
(Optional) Name of the credential in one of these forms:

credentialName

relative (for example, "cred1")The credential is assumed


to be in the project that contains the request target object.

absolute (for example,


"/projects/BuildProject/credentials/cred1")Tthe credential
can be from any specified project, regardless of the target
objects project.

Argument type:String
(Optional) Name of the environment that must be unique among all
environmentName

projects.
Argument type:String
(Optional) Name of the environment template.

environmentTemplateName
Argument type:String

525

ElectricCommander

Arguments

Descriptions
(Optional) Name of the environment template tier.

environmentTemplateTierName
Argument type:String
(Optional) Name of the environment tier.
environmentTierName
Argument type:String
(Optional) Name of the gateway.
gatewayName
Argument type:String
(Optional) Name of a group where you might evaluate a script.
groupName
Argument type:String
(Optional) The unique Commander-generated identifier (a UUID)
for a job that is assigned automatically when the job is created.
jobId

The system also accepts a job name assigned to the job by its
name template.
Argument type:UUID
(Optional) The unique identifier for a job step that is assigned

jobStepId

automatically when the job step is created.


Argument type:UUID
(Optional) Name of the email notifier.

notifierName
Argument type:String
(Optional) This is an object identifier returned by findObjects
objectId

and getObjects.
Argument type:String
(Optional) Property path string.

path
Argument type:String
(Optional) Name of a plugin where you might evaluate a script.
pluginName
Argument type:String

526

API Commands - Property Management

Arguments

Descriptions
(Optional) Name of a procedure where you might need to evaluate
a script.

procedureName

Also requiresprojectName.
Argument type:String
(Optional) Name of the process when the container is a process or

processName

process step.
Argument type:String
(Optional) Name of the process step when the container is a

processStepName

process step.
Argument type:String
(Optional) Name of the project that contains the script to evaluate.

projectName
Argument type:String
(Optional) The unique identifier for a property sheet that is
propertySheetId

assigned automatically when the property sheet is created.


Argument type:UUID
(Optional) Name of the repository for artifact management.

repositoryName
Argument type:String
(Optional) Name of a resource where you might evaluate a script.
resourceName
Argument type:String
(Optional) Name of a pool containing one or more resources.
resourcePoolName
Argument type:String
(Optional) Name of the resource template.
resourceTemplateName
Argument type:String
(Optional) Name of a schedule within this project.
scheduleName

Also requiresprojectName.
Argument type:String

527

ElectricCommander

Arguments

Descriptions
(Optional) Name of the snapshot.

snapshotName
Argument type:String

scheduleName

(Optional) Name of the resource where you might evaluate a


script.
(Optional) Name of the state definition.

stateDefinitionName
Argument type:String
(Optional) Name of the state.
stateName
Argument type:String
(Optional) Name of the step whose script you might evaluate.
stepName

Also requiresprojectName and procedureName.


Argument type:String
(Optional) System object names include:
admin|directory|log|priority|projects|resources|

systemObjectName

server|session|workspaces.
Argument type:SystemObjectName
(Optional) Name of the transition definition.

transitionDefinitionName
Argument type:String
(Optional) Name of the transition.
transitionName
Argument type:String
(Optional) Name of the user where you may need to evaluate a
userName

script.
Argument type:String
(Optional) Name of the workflow definition.

workflowDefinitionName
Argument type:String
(Optional) Name of the workflow.
workflowName
Argument type:String

528

API Commands - Property Management

Arguments

Descriptions
(Optional) Name of a workspace where you may need to evaluate

workspaceName

a script.
Argument type:String
(Optional) Name of the zone.

zoneName
Argument type:String

Positional arguments
value

Response
The string value of the final expression in the Javascript block inside a value element.

ec-perl
syntax: $cmdr->evalScript (<value>);

Examples
my $result = $ec->evalScript (q{"ip=" + server.hostIP+", name=" + server.hostName})
->findvalue("//value");
my $result = $ec->evalScript (q{myProject.projectName}, {jobId => '4fa765dd-73f1-11
e3-b67e-b0a420524153'});

ectool
syntax: ectool evalScript <value>

Examples
ectool evalScript '"ip=" + server.hostIP+", name=" + server.hostName'
ectool evalScript 'myProject.projectName' --jobId 4fa765dd-73f1-11e3-b67e-b0a420524
153
--jobStepId 5da765dd-73f1-11e3-b67e-b0a420524153
Back to Top

expandString
Expands property references in a string, in the current context.
You must specify a value and a context in which to perform the expansion or a valueFile option.

529

ElectricCommander

Arguments

Descriptions
The string value to expand in the given context.

value
Argument type:String
(Optional) The name of the application that must be unique among
applicationName

all projects.
Argument type:String
(Optional) The name of the application tier.

applicationTierName
Argument type:String
(Optional) The name of the artifact.
artifactName
Argument type:String
(Optional) The name of the artifact version.
Note: An artifact version name is interpreted by the server as the
artifactVersionName attribute for the artifactVersion in
question. This name is parsed and interpreted as
artifactVersionName

"groupId:artifactKey:version" and the object is searched


either way you specify its name. The Commander server interprets
either name form correctly.
Argument type:String
(Optional) The name of the component.

componentName
Argument type:String
(Optional) The name of the email configuration.
configName
Argument type:String
(Optional) The name of the credential container of the property
sheet which owns the property.
Name of the credential in one of these forms:
l

relative (for example, "cred1")The credential is assumed


to be in the project that contains the request target object.

absolute (for example,


"/projects/BuildProject/credentials/cred1")Tthe credential
can be from any specified project, regardless of the target
objects project.

credentialName

Argument type:String

530

API Commands - Property Management

Arguments

Descriptions
(Optional) The name of the environment that must be unique

environmentName

among all projects.


Argument type:String
(Optional) Name of the environment template.

environmentTemplateName
Argument type:String
(Optional) Name of the environment template tier.
environmentTemplateTierName
Argument type:String
(Optional) The name of the environment tier.
environmentTierName
Argument type:String
(Optional) The name of the gateway.
gatewayName
Argument type:String
(Optional) The name of a group where you might expand a string.
groupName
Argument type:String
(Optional) The unique Commander-generated identifier (a UUID)
for a job that is assigned automatically when the job is created.
jobId

The system also accepts a job name assigned to the job by its
name template.
Argument type:UUID
(Optional) The unique identifier for a job step that is assigned

jobStepId

automatically when the job step is created.


Argument type:UUID
(Optional) The name of the email notifier.

notifierName
Argument type:String
(Optional) This is an object identifier returned by findObjects
objectId

and getObjects.
Argument type:String

531

ElectricCommander

Arguments

Descriptions
(Optional) Property path string.

path
Argument type:String
(Optional) The name of a plugin where you might expand a string.
pluginName
Argument type:String
(Optional) The name of a procedure where you might need to
expand a string.
procedureName

Also requiresprojectName.
Argument type:String
(Optional) The name of the process when the container is a

processName

process or process step.


Argument type:String
(Optional) The name of the process step when the container is a

processStepName

process step.
Argument type:String
(Optional) The name of the project that contains the string to

projectName

expand.
Argument type:String
(Optional) The unique identifier for a property sheet that assigned

propertySheetId

automatically when the property sheet is created.


Argument type:UUID
(Optional) The name of the repository for artifact management.

repositoryName
Argument type:String
(Optional) The name of a resource where you might expand a
resourceName

string.
Argument type:String
(Optional) The name of a pool containing one or more resource

resourcePoolName
Argument type:String

532

API Commands - Property Management

Arguments

Descriptions
(Optional) Name of the resource template.

resourceTemplateName
Argument type:String
(Optional) The name of a schedule within this project.
scheduleName

Also requiresprojectName.
Argument type:String
(Optional) The name of the snapshot.

snapshotName
Argument type:String
(Optional) The name of the state definition.
stateDefinitionName
Argument type:String
(Optional) The name of the state.
stateName
Argument type:String
(Optional) The name of the step whose string you might be
expanding.
stepName

Also requiresprojectName and procedureName.


Argument type:String
(Optional) System object names include:
admin|directory|log|priority|projects|resources|

systemObjectName

server|session|workspaces.
Argument type:SystemObjectName
(Optional) The name of the transition definition.

transitionDefinitionName
Argument type:String
(Optional) The name of the transition.
transitionName
Argument type:String
(Optional) The name of the user where you may need to expand
userName

the string.
Argument type:String

533

ElectricCommander

Arguments

Descriptions
(Optional) This option is supported only in Perl and ectool
bindings - it is not part of the XML protocol.

valueFile

Contents of the valuefile is read and stored in the "value" field. This
is an alternative argument for value and is useful if the value field
spans multiple lines.
(Optional) The name of the workflow definition.

workflowDefinitionName
Argument type:String
(Optional) The name of the workflow.
workflowName
Argument type:String
(Optional) The name of a workspace where you may need to
workspaceName

expand the string.


Argument type:String
(Optional) The name of the zone.

zoneName
Argument type:String

Positional arguments
value

Response
The expanded string value.

ec-perl
syntax: $cmdr->expandString(<value>, {<optionals>});

Examples
$cmdr->expandString('$[fullUserName]', {userName => "admin"})->findvalue('//value')
->value();
$cmdr->expandString('$[/myWorkspace/agentUncPath]/$[logFileName]',
{jobStepId => 5da765dd-73f1-11e3-b67e-b0a420524153})->findvalue('//value')->valu
e();

ectool
syntax: ectool expandString <value> ...

Examples
ectool expandString '$[fullUserName]' --userName admin

534

API Commands - Property Management

ectool expandString '$[/myWorkspace/agentUncPath]/$[logFileName]'


--jobStepId 5da765dd-73f1-11e3-b67e-b0a420524153
Back to Top

getProperties
Retrieves all properties associated with an object, along with the property sheet identifier for the object's
property sheet.
You must specify object locators for the properties you want to retrieve.

Arguments

Descriptions
The name of the application that must be unique among all

applicationName

projects.
Argument type:String
The name of the application tier.

applicationTierName
Argument type:String
The name of the artifact.
artifactName
Argument type:String
The name of the artifact version.
Note: An artifact version name is interpreted by the server as the
artifactVersionName attribute for the artifactVersion in
question. This name is parsed and interpreted as
artifactVersionName

"groupId:artifactKey:version" and the object is searched


either way you specify its name. The Commander server interprets
either name form correctly.
Argument type:String
The name of the component.

componentName
Argument type:String
The name of the email configuration.
configName
Argument type:String

535

ElectricCommander

Arguments

Descriptions
The name of the credential containing the properties to retrieve.
Name of the credential in one of these forms:

credentialName

relative (for example, "cred1")The credential is assumed


to be in the project that contains the request target object.

absolute (for example,


"/projects/BuildProject/credentials/cred1")The credential
can be from any specified project, regardless of the target
objects project.

Argument type:String
The name of the environment that must be unique among all
environmentName

projects.
Argument type:String
Name of the environment template.

environmentTemplateName
Argument type:String
Name of the environment template tier.
environmentTemplateTierName
Argument type:String
The name of the environment tier.
environmentTierName
Argument type:String
<Boolean flag - 0|1|true|false>
Thedefault value is 1 (true), and the value of each property will
be expanded.
expand
A value of 0 (false) will cause the unexpanded value of each
property to be returned.
Argument type:Boolean
The name of the gateway.
gatewayName
Argument type:String
The name of the group containing the properties to retrieve.
groupName
Argument type:String

536

API Commands - Property Management

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system

jobId

also accepts a job name assigned to the job by its name template.
Argument type:UUID
The unique identifier for a job step that is assigned automatically

jobStepId

when the job step is created.


Argument type:UUID
The name of the email notifier.

notifierName
Argument type:String
This is an object identifier returned by findObjects and
objectId

getObjects.
Argument type:String
The path to the property sheet containing the properties to retrieve.
If the full path to the property sheet is specified, no additional

path

object locators are needed.


Argument type:String
The name of the plugin containing the properties to retrieve.

pluginName
Argument type:String
The name of the procedure containing the properties to retrieve.
procedureName

Also requiresprojectName.
Argument type:String
The name of the process when the container is a process or

processName

process step.
Argument type:String
The name of the process step when the container is a process

processStepName

step.
Argument type:String

537

ElectricCommander

Arguments

Descriptions
The name of the project containing the properties to retrieve.

projectName
Argument type:String
The unique identifier for a property sheet that is assigned
propertySheetId

automatically when the property sheet is created.


Argument type:UUID
<Boolean flag - 0|1|true|false>
Thedefault value is 0 (false), and properties of nested sheets will
not be included in the response.

recurse
If you want the properties from all nested sheets to be retrieved,
use the value of 1 for true.
Argument type:Boolean
The name of the repository for artifact management.
repositoryName
Argument type:String
The name of the resource containing the properties to retrieve.
resourceName
Argument type:String
The name of a pool containing one or more resources.
resourcePoolName
Argument type:String
Name of the resource template.
resourceTemplateName
Argument type:String
The name of the schedule containing the properties to retrieve.
scheduleName

Also requires projectName.


Argument type:String
The name of the snapshot.

snapshotName
Argument type:String
The name of the state definition.
stateDefinitionName
Argument type:String

538

API Commands - Property Management

Arguments

Descriptions
The name of the state.

stateName
Argument type:String
The name of the step containing the properties to retrieve.
stepName

Also requiresprojectName and procedureName.


Argument type:String
The name of the system object containing the properties to

systemObjectName

retrieve. Only "server" is supported.


Argument type:SystemObjectName
The name of the transition definition.

transitionDefinitionName
Argument type:String
The name of the transition.
transitionName
Argument type:String
The name of the user containing the properties to retrieve.
userName
Argument type:String
workflowDefinitionName

The name of the workflow definition.


The name of the workflow.

workflowName

Also requires projectName.


Argument type:String
The name of the workspace containing the properties to retrieve.

workspaceName
Argument type:String
The name of the zone.
zoneName
Argument type:String

Positional arguments
Arguments to locate the property, beginning with the top-level object.

Response
A propertySheet element, which contains zero or more property elements and nested propertySheet
elements.

539

ElectricCommander

ec-perl
syntax: $cmdr->getProperties({<optionals>});

Examples
$cmdr->getProperties({resourceName => "r2"});

ectool
syntax: ectool getProperties ...

Examples
ectool getProperties --resourceName "r2"
Back to Top

getProperty
Retrieves the specified property value.
You must specify a propertyName.
Note: This specification can be the full path to the property or it can be relative to an object, which then requires
appropriate object locators.

Arguments

Descriptions
The name or path for the property to retrieve.

propertyName
Argument type:String
The name of the application that must be unique among all
applicationName

projects.
Argument type:String
The name of the application tier.

applicationTierName
Argument type:String
The name of the artifact.
artifactName
Argument type:String

540

API Commands - Property Management

Arguments

Descriptions
The name of the artifact version.
Note: An artifact version name is interpreted by the server as the
artifactVersionName attribute for the artifactVersion in
question. This name is parsed and interpreted as

artifactVersionName

"groupId:artifactKey:version" and the object is searched


either way you specify its name. The Commander server interprets
either name form correctly.
Argument type:String
The name of the component.

componentName
Argument type:String
The name of the email configuration.
configName
Argument type:String
The name of the credential containing the property to retrieve.
Name of the credential in one of these forms:

credentialName

relative (for example, "cred1")The credential is assumed


to be in the project that contains the request target object.

absolute (for example,


"/projects/BuildProject/credentials/cred1")The credential
can be from any specified project, regardless of the target
objects project.

Argument type:String
The name of the environment container that must be unique
environmentName

among all projects.


Argument type:String
Name of the environment template.

environmentTemplateName
Argument type:String
Name of the environment template tier.
environmentTemplateTierName
Argument type:String
The name of the environment tier.
environmentTierName
Argument type:String

541

ElectricCommander

Arguments

Descriptions
<Boolean flag - 0|1|true|false>
The default value is 1 (true), and the value of each property will
be expanded.

expand
A value of 0 (false) will cause the unexpanded value of each
property to be returned.
Argument type:Boolean
For simple property names, whether or not to search objects in the
hierarchy to find the desired property.
<Boolean flag - 0|1|true|false> If set, and there is an object
locator in the command, Commander first looks for the property in
that object locator, but also searches in other locations if not found,
according to the following rules:
extendedContextSearch

If the object locator is a procedure, Commander looks for


the property in the project where the procedure resides.

If the object locator is a job step, Commander looks in the


actual parameters of the procedure to which it belongs, and
then looks at the job properties.

Default setting is true.


Argument type:Boolean
The name of the gateway.
gatewayName
Argument type:String
The name of the group containing the property to retrieve.
groupName
Argument type:String
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system
jobId

also accepts a job name assigned to the job by its name template.
Argument type:UUID
The unique identifier for a job step that is assigned automatically

jobStepId

when the job step is created.


Argument type:String

542

API Commands - Property Management

Arguments

Descriptions
The name of the email notifier.

notifierName
Argument type:String
This is an object identifier returned by findObjects and
objectId

getObjects.
Argument type:String
The path to the property sheet containing the properties to retrieve.
If the full path to the property sheet is specified, no additional

path

object locators are needed.


Argument type:String
The name of the plugin containing the property to retrieve.

pluginName
Argument type:String
The name of the procedure containing the property to retrieve.
procedureName

Also requiresprojectName.
Argument type:String
The name of the process when the container is a process or

processName

process step.
Argument type:String
The name of the process step when the container is a process

processStepName

step.
Argument type:String
The name of the project containing the property to retrieve.

projectName
Argument type:String
The unique identifier for a property sheet that is assigned
propertySheetId

automatically when the property sheet is created.


Argument type:UUID
The name of the repository for artifact management.

repositoryName
Argument type:String

543

ElectricCommander

Arguments

Descriptions
The name of the resource containing the property to retrieve.

resourceName
Argument type:String
The name of a pool containing one or more resources.
resourcePoolName
Argument type:String
Name of the resource template.
resourceTemplateName
Argument type:String
The name of the schedule containing the property to retrieve.
scheduleName

Also requiresprojectName.
Argument type:String
The name of the snapshot.

snapshotName
Argument type:String
stateDefinitionName

The name of the state definition.

stateName

The name of the state.

stepName

The name of the step containing the property to retrieve.


Also requiresprojectName and procedureName
The name of the system object containing the property to retrieve.

systemObjectName

Only "server" is supported.


Argument type:SystemObjectName
The name of the transition definition.

transitionDefinitionName
Argument type:String

transitionName

The name of the transition.


Argument type:String
The name of the user containing the property to retrieve.

userName
Argument type:String
The name of the workflow definition.
workflowDefinitionName
Argument type:String

544

API Commands - Property Management

Arguments

Descriptions
The name of the workflow.

workflowName
Argument type:String
The name of the workspace containing the property to retrieve.
workspaceName
Argument type:String
The name of the zone.
zoneName
Argument type:String

Positional arguments
propertyName

Response
A property sheet or a text string containing the value of the property.
Property value example: 35491

ec-perl
syntax: $cmdr->getProperty(<propertyName>, {<optionals>});

Examples
use XML::XPath;
$cmdr->getProperty("/myProject/changeset ID")->findvalue('//value')->value();
$cmdr->getProperty("Changeset ID", {projectName => "Sample Project"})->findvalue('/
/value')->value();

ectool
syntax: ectool getProperty <propertyName> ...

Examples
ectool getProperty "/myProject/changeset ID"
ectool getProperty "Changeset ID" --projectName "Sample Project"
# Retrieve the /users/<userName>/providerName property.
ectool getProperty --objectID <ID> --propertyName "/users/<userName>/providerName"
Back to Top

545

ElectricCommander

incrementProperty
Atomically increments the specified property value by the incrementBy amount. If the property does not exist, it
will be created with an initial value of the incrementBy amount.
You must specify a propertyName and incrementBy.

Arguments

Descriptions
Name for the property that must be unique within the property

propertyName

sheet.
Argument type:String
This is positive or negative integer.

incrementBy
Argument type:Integer
The name of the application that must be unique among all
applicationName

projects.
Argument type:String
The name of the application tier.

applicationTierName
Argument type:String
The name of the artifact.
artifactName
Argument type:String
The name of the artifact version.
Note: An artifact version name is interpreted by the server as
the artifactVersionName attribute for the
artifactVersionName

artifactVersion in question. This name is parsed and


interpreted as "groupId:artifactKey:version" and the
object is searched either way you specify its name. The
Commander server interprets either name form correctly.
Argument type:String
The name of the component.

componentName
Argument type:String
The name of the email configuration.
configName
Argument type:String

546

API Commands - Property Management

Arguments

Descriptions
Name of the credential in one of these forms:

credentialName

relative (for example, "cred1")The credential is assumed


to be in the project that contains the request target object.

absolute (for example,


"/projects/BuildProject/credentials/cred1")Tthe credential
can be from any specified project, regardless of the target
objects project.

Argument type: String


The name of the environment that must be unique among all
environmentName

projects.
Argument type:String
Name of the environment template.

environmentTemplateName
Argument type:String
Name of the environment template tier.
environmentTemplateTierName
Argument type:String
The name of the environment tier.
environmentTierName
Argument type:String
For simple property names, whether or not to search objects in the
hierarchy to find the desired property.
<Boolean flag - 0|1|true|false>
If set, and there is an object specified in the command,
ElectricCommander first looks for the property in that object
specifier, but also searches in other locations if not found,
according to the following rules:
extendedContextSearch

If the object specifier is a procedure, ElectricCommander


looks for the property in the project where the procedure
resides.

If the object specifier is a job step, ElectricCommander


looks in the actual parameters of the procedure to which it
belongs, and then looks at the job properties.

The default setting is true.


Argument type:Boolean

547

ElectricCommander

Arguments

Descriptions
The name of the gateway.

gatewayName
Argument type:String
The name of the group containing the property to increment.
groupName
Argument type:String
The unique Commander-generated identifier (a UUID) for a job
that is assigned automatically when the job is created. The system
jobId

also accepts a job name assigned to the job by its name template.
Argument type:UUID
The unique identifier for a job step that is assigned automatically

jobStepId

when the job step is created.


Argument type:UUID
The name of the email notifier.

notifierName
Argument type:String
This is an object identifier returned by findObjects and
objectId

getObjects.
Argument type:String
Path to the property.

path
Argument type:String
pluginName

The name of the plugin containing a property to increment.


The name of the procedure containing this property.

procedureName

Also requiresprojectName.
Argument type:String
The name of the process when the container is a process or

processName

process step.
Argument type:String

548

API Commands - Property Management

Arguments

Descriptions
The name of the process step when the container is a process

processStepName

step.
Argument type:String
The name of the project containing this property.

projectName

Also requires procedureName.


Argument type:String
The unique identifier for a property sheet that is assigned

propertySheetId

automatically when the property sheet is created.


Argument type:UUID
The name of the repository for artifact management.

repositoryName
Argument type:String
The name of the resource containing this property.
resourceName
Argument type:String
The name of a pool containing one or more resources.
resourcePoolName
Argument type:String
Name of the resource template.
resourceTemplateName
Argument type:String
The name of the schedule containing this property.
scheduleName

Also requiresprojectName.
Argument type:String
The name of the snapshot.

snapshotName
Argument type:String
The name of the state definition.
stateDefinitionName
Argument type:String
The name of the state.
stateName
Argument type:String

549

ElectricCommander

Arguments

Descriptions
The name of the step containing this property.

stepName

Also requiresprojectName and procedureName.


Argument type:String
Only server is a valid system object for this API.

systemObjectName
Argument type:SystemObjectName
The name of the transition definition.
transitionDefinitionName
Argument type:String
The name of the transition.
transitionName
Argument type:String
The name of the user containing this property.
userName
Argument type:String
The name of the workflow definition.
workflowDefinitionName
Argument type:String
The name of the workflow.
workflowName
Argument type:String
The name of the workspace containing this property.
workspaceName
Argument type:String
The name of the zone.
zoneName
Argument type:String

Positional arguments
propertyName, incrementBy

Response
A text string containing the updated numeric property value.

ec-perl
syntax: $cmdr->incrementProperty(<propertyName> <incrementBy> ...);

550

API Commands - Property Management

Examples
$cmdr->incrementProperty("Build Number", 1, {procedureName => "Delay", projectName
=> "Sample Project");
$cmdr->incrementProperty("/projects/Sample Project/procedures/Delay/Build Number",
1);
$cmdr->incrementProperty("procedures/Delay/Build Number", 1,{projectName => "Sample
Project"});

ectool
syntax: ectool incrementProperty <propertyName> <incrementBy> ...

Examples
ectool incrementProperty "Build Number" 1 --procedureName "Delay" --projectName "Sa
mple Project"
ectool incrementProperty "/projects/Sample Project/procedures/Delay/Build Number" 1
ectool incrementProperty "procedures/Delay/Build Number" 1 --projectName "Sample Pr
oject"
Back to Top

modifyProperty
Modifies a regular string or nested property sheet using a combination of property path and context.
You must specify a propertyName.
Note: The name "properties" is NOT a valid property name.

Arguments

Descriptions
The name of the property that must be unique within the property
sheet.

propertyName

This argument can be a path.


Argument type:String
The name of the application that must be unique among all projects.

applicationName
Argument type:String
The name of the application.
applicationTierName
Argument type:String

551

ElectricCommander

Arguments

Descriptions
The name of the artifact.

artifactName
Argument type:String
The name of the artifact version.
Note: An artifact version name is interpreted by the server as
the artifactVersionName attribute for the artifactVersion
artifactVersionName

in question. This name is parsed and interpreted as


"groupId:artifactKey:version" and the object is
searched either way you specify its name--the Commander
server interprets either name form correctly.
Argument type:String
The name of the component.

componentName
Argument type:String
The name of the email configuration.
configName
Argument type:String
credentialName can be one of two forms:
relative
(for example, "cred1") - the credential is assumed to be in the
project that contains the request target object.
credentialName

absolute
(for example, "/projects/BuildProject/credentials/cred1") - the
credential can be from any specified project, regardless of the target
object's project.
Argument type:String
A plain text or HTML description for this object.
If using HTML, you must surround your text with
<html> ... </html> tags. The only HTML tags allowed in the
text are:

description

<a> <b> <br> <div> <dl> <font> <i> <li> <ol> <p>
<pre> <span>
<style> <table> <tc> <td> <th> <tr> <ul>
Argument type:String

552

API Commands - Property Management

Arguments

Descriptions
The name of the environment that must be unique among all

environmentName

projects.
Argument type:String
(Optional) Name of the environment template.

environmentTemplateName
Argument type:String
(Optional) Name of the environment template tier.
environmentTemplateTierName
Argument type:String
The name of the environment tier.
environmentTierName
Argument type:String
<Boolean flag -0|1|true|false>Determines whether the
property will undergo property expansion when it is retrieved. The
expandable

default is true.
Argument type: Boolean
For simple property names, whether or not to search objects in the
hierarchy to find the desired property.
<Boolean flag - 0|1|true|false> If set, and there is an object
specified in the command, ElectricCommander first looks for the
property in that object specifier, but also searches in other locations
if not found, according to the following rules:

extendedContextSearch

1. If the object specifier is a procedure, ElectricCommander


looks for the property in the project where the procedure
resides.
2. If the object specifier is a job step, ElectricCommander looks
in the actual parameters of the procedure to which it
belongs, and then looks at the job properties.
The default setting is true.
Argument type: Boolean
The name of the gateway.

gatewayName
Argument type:String
The name of the group.
groupName
Argument type:String

553

ElectricCommander

Arguments

Descriptions
The unique Commander-generated identifier (a UUID) for a job that
is assigned automatically when the job is created. The system also

jobId

accepts a job name assigned to the job by its name template.


Argument type:UUID
The unique identifier for a job step, which is assigned automatically

jobStepId

when the job step is created.


Argument type:UUID
New name of the property.

newName
Argument type:String
Name of the email notifier.
notifierName
Argument type:String
An object identifier returned by findObjects and getObjects.
objectId
Argument type:String
Name of the plugin.
pluginName
Argument type:String
Name of the procedure.
procedureName

Also requiresprojectName.
Argument type:String
Name of the project. The property may be on the project itself or on

projectName

the object, which is indicated by other arguments.


Argument type:String
Name of the process when the container is a process or process

processName

step.
Argument type:String
Name of the process step when the container is a process step.

processStepName
Argument type:String

554

API Commands - Property Management

Arguments

Descriptions
The unique identifier for a property sheet, which is assigned

propertySheetId

automatically when the property sheet is created.


Argument type:UUID
<string|sheet> Indicates whether to create a string property or

propertyType

a sub-sheet. The default is string.


Argument type:PropertyType
Name of the repository for artifact management.

repositoryName
Argument type:String
Name of the resource.
resourceName
Argument type:String
Name of a pool containing one or more resources.
resourcePoolName
Argument type:String
Name of the resource template.
resourceTemplateName
Argument type:String
Name of the schedule.
scheduleName

Also requiresprojectName.
Argument type:String
Name of the state definition.

stateDefinitionName
Argument type:String
Name of the state.
stateName
Argument type:String
Name of the step containing the property to be modified.
stepName

Also requiresprojectName and procedureName.


Argument type:String

555

ElectricCommander

Arguments

Descriptions

systemObjectName

System objects include:


admin|artifactVersions|directory|emailConfigs|
log|plugins|server|session|workspaces.
Argument type: SystemObjectName
The name of the transition definition.

transitionDefinitionName
Argument type:String
The name of the transition.
transitionName
Argument type:String
The name of the user.
userName
Argument type:String
Value of the property.
value
Argument type:String
This option is supported only in Perl and ectool bindings - it is not
part of the XML protocol.
valueFile

The contents of the valuefile is read and stored in the "value" field.
This is an alternative argument for value and is useful if the "value"
field spans multiple lines.
The name of the workflow definition.

workflowDefinitionName
Argument type:String
The name of the workflow.
workflowName
Argument type:String
The name of the workspace.
workspaceName
Argument type:String
The name of the zone.
zoneName
Argument type:String

Positional arguments
propertyName

556

API Commands - Property Management

Response
An XML stream that echoes the modified property.

ec-perl
syntax: $cmdr->modifyProperty(<propertyName>, {...});

Example
$cmdr->modifyProperty("Saved Variables", {description =>
&qu