Reporting API reference

This section describes reporting-related requests.

All database examples provided in this guide are specific to MySQL. If you use a different database, use syntax that is appropriate for your respective database.

createFilter

Creates a named filter for a specific table.

Non-global filters are stored by user ID; therefore, the same name can be used by more than one user.

Required arguments

Field	Description
tableName	A short string that uniquely identifies the table being filtered. Possible table names are: ec_agent, ec_build, ec_build_class, ec_filter, ec_message, ec_resource, ec_resource_stat.
filterName	A short string that uniquely identifies the filter.
filterQuery	A SQL order by clause for the associated table.

Field

Description

tableName

A short string that uniquely identifies the table being filtered. Possible table names are: ec_agent, ec_build, ec_build_class, ec_filter, ec_message, ec_resource, ec_resource_stat.

filterName

A short string that uniquely identifies the filter.

filterQuery

A SQL order by clause for the associated table.

Optional arguments

Field	Description
global	Can be true or false. If true, this is a globally visible filter. This parameter is required for global filters.
order	A SQL order by clause. Used to specify ordering for the query result set.

Field

Description

global

Can be true or false. If true, this is a globally visible filter. This parameter is required for global filters.

order

A SQL order by clause. Used to specify ordering for the query result set.

Syntax

cmtool createFilter <tableName> <filterName> <filterQuery> [optionals...]

Example

cmtool createFilter ec_agents linuxAgents ""platform = ’linux’" --global true

Creates a global filter that selects Linux agents only.

deleteFilter

Deletes a named filter for a specific table.

Required arguments

Field	Description
tableName	A short string that uniquely identifies the table being filtered. Possible table names are: ec_agent, ec_build, ec_build_class, ec_filter, ec_message, ec_resource, ec_resource_stat.
filterName	A short string that uniquely identifies the filter.

Field

Description

tableName

A short string that uniquely identifies the table being filtered. Possible table names are: ec_agent, ec_build, ec_build_class, ec_filter, ec_message, ec_resource, ec_resource_stat.

filterName

A short string that uniquely identifies the filter.

Optional argument

Field	Description
global	Can be true or false. If true, this is a globally visible filter. This parameter is required for global filters.

Field

Description

global

Can be true or false. If true, this is a globally visible filter. This parameter is required for global filters.

Syntax

cmtool deleteFilter <tableName> <filterName> [optionals...]

Example

cmtool deleteFilter ec_agents linuxAgents --global true

getCurrentServerLoad

Retrieves information about the current resource load.

Required arguments

None

Optional arguments

None

Result tags

Field Description

Field	Description
agentsAvailable	The total number of active agents in the cluster.
agentClusterShortage	The difference between the maximum number of agents requested by all builds and the number of agents that were assigned.
agentDemand	The total maximum number of requests for agents by all running builds.
agentLicenseShortage	The difference between the maximum request for agents by all builds and the number of agents the license allows.
agentsInUse	The total number of agents assigned to builds.
buildsDuration	The average amount of time the current builds have been running.
buildsRunning	Average number of simultaneous builds running during a specific time period.
createTime	The time when the item was created.
duration	The number of milli-seconds the build has been running.
resourceName	This name is used on the eMake parameter: `--emake-resource`, and can be specified in a build class. It is used in the `ea_resource` table and also matches the resource requirement string for eMake.
resourceStatId	The resource ID number that uniquely identifies every resource.

agentsAvailable

The total number of active agents in the cluster.

agentClusterShortage

The difference between the maximum number of agents requested by all builds and the number of agents that were assigned.

agentDemand

The total maximum number of requests for agents by all running builds.

agentLicenseShortage

The difference between the maximum request for agents by all builds and the number of agents the license allows.

agentsInUse

The total number of agents assigned to builds.

buildsDuration

The average amount of time the current builds have been running.

buildsRunning

Average number of simultaneous builds running during a specific time period.

createTime

The time when the item was created.

duration

The number of milli-seconds the build has been running.

resourceName

This name is used on the eMake parameter: --emake-resource, and can be specified in a build class. It is used in the ea_resource table and also matches the resource requirement string for eMake.

resourceStatId

The resource ID number that uniquely identifies every resource.

Example

cmtool getCurrentServerLoad

getFilter

Retrieves a named filter for a specific table.

Required arguments

Field	Description
tableName	A short string that uniquely identifies the table being filtered. Possible table names are: ec_agent, ec_build, ec_build_class, ec_filter, ec_message, ec_resource, ec_resource_stat.
filterName	A short string that uniquely identifies the filter.

Field

Description

tableName

A short string that uniquely identifies the table being filtered. Possible table names are: ec_agent, ec_build, ec_build_class, ec_filter, ec_message, ec_resource, ec_resource_stat.

filterName

A short string that uniquely identifies the filter.

Optional arguments

Field	Description
global	Can be true or false. If true, this is a globally visible filter. This parameter is required for global filters.

Field

Description

global

Can be true or false. If true, this is a globally visible filter. This parameter is required for global filters.

Syntax

cmtool getFilter <tableName> <filterName> [optionals...]

Example

cmtool getFilter ec_agent agentFilter

getFilters

Retrieves a list of saved filters for the current user.

Required arguments

None

Optional arguments

Field	Description
filter	The query to use to limit the result set. For a list of possible SQL values, see the getAgents command.
maxResults	The maximum number of elements to return from a query.
firstResult	The starting index for the query result set. The argument takes values beginning with 0. A negative value indicates a record starting from the end of the set, counting backwards, so -1 is the last record, -2 is the next to last, and so on.
order	A SQL order by clause. Used to specify ordering for the query result set.

Field

Description

filter

The query to use to limit the result set. For a list of possible SQL values, see the getAgents command.

maxResults

The maximum number of elements to return from a query.

firstResult

The starting index for the query result set. The argument takes values beginning with 0. A negative value indicates a record starting from the end of the set, counting backwards, so -1 is the last record, -2 is the next to last, and so on.

order

A SQL order by clause. Used to specify ordering for the query result set.

Syntax

cmtool getFilters [optionals...]

Example

cmtool getFilters --filter "table_name = ’ec_agent’ && user_name is null"

Retrieves a list of all global filters for the agent table.

modifyFilter

Updates a named filter for a specific table.

Required arguments

Field	Description
tableName	A short string that uniquely identifies the table being filtered. Possible table names are: ec_agent, ec_build, ec_build_class, ec_filter, ec_message, ec_resource, ec_resource_stat.
filterName	A short string that uniquely identifies the filter.
filterQuery	A SQL order by clause for the associated table.

Field

Description

tableName

A short string that uniquely identifies the table being filtered. Possible table names are: ec_agent, ec_build, ec_build_class, ec_filter, ec_message, ec_resource, ec_resource_stat.

filterName

A short string that uniquely identifies the filter.

filterQuery

A SQL order by clause for the associated table.

Optional arguments

Field	Description
global	Can be true or false. If true, this is a globally visible filter. This parameter is required for global filters.
order	A SQL order by clause. Used to specify ordering for the query result set.

Field

Description

global

Can be true or false. If true, this is a globally visible filter. This parameter is required for global filters.

order

A SQL order by clause. Used to specify ordering for the query result set.

Syntax

cmtool modifyFilter <tableName> <filterName> <filterQuery> [optionals...]

Example

cmtool modifyFilter ec_agent agentFilter "id 750" --order agent_name