findObjects

Back to index

Summary

This command returns a sorted list of CloudBees CD/RO objects based on an object type and a set of filter criteria. This API can be used to find many, but not all, types of CloudBees CD/RO objects and is used by the CloudBees CD/RO web interface to implement the CloudBees CD/RO Search feature.
For a list of object types in CloudBees CD/RO, refer to Object types in CloudBees CD/RO.
objectType
Stringrequired
The object type to search for.
caseSensitiveSearch
Booleanoptional
Applicable only for case-sensitive databases. When set to True (default), searches are case-sensitive. When set to False, searches are case-insensitive.
filter
Arrayoptional
A list of zero or more filter criteria definitions used to define objects to find.
firstResult
Integeroptional
The first result to be retrieved, numbered from 0.
includeAccess
Booleanoptional
True to fetch the objects' access maps as well.
includeEntityRevisions
Booleanoptional
Include versions/entity revision if it is a revisionable object in the search result.
includeLatestRevision
Booleanoptional
Include the latest revision data for versioned objects.
maxIds
Integeroptional
The maximum number of object IDs to return.
numObjects
Integeroptional
The number of objects to return as the first page of results.
quickSearchFilter
Stringoptional
Quick search filter.
select
Arrayoptional
Custom properties to project into the query results.
sort
Arrayoptional
Sort specifications.
viewName
Stringoptional
The name of the view.

Usage

Perl

$cmdr->findObjects( "test-objectType" # objectType # optionals );

ectool

ectool findObjects \ "test-objectType" `# objectType` \ # optionals

Examples

Perl

This example shows how to use a Boolean filter for the findObjects command to find jobs matching either of two patterns for the job name.

my @filterList; push (@filterList, {"propertyName" => "jobName", "operator" => "like", "operand1" => "%-branch-%"}); push (@filterList, {"propertyName" => "jobName", "operator" => "like", "operand1" => "branch-%"}); my $result = $cmdr->findObjects('job', {filter => [ { operator => 'or', filter => \@filterList, } ]} ); print "result = " . $result->findnodes_as_string("/"). "\n";

This example uses findObjects and getObjects to manage large result sets, and also uses select to return the values of two properties in the returned objects.

# Search for the first 10 matching objects and retrieve the first 2 my $xPath = $cmdr->findObjects("schedule", {maxIds => "10", numObjects => "2", filter => [{propertyName => "createTime", operator => "greaterOrEqual", operand1 => "2007-01-20T00:00:00.000Z"}, {propertyName => "lastModifiedBy", operator => "like", operand1 => "adm%"}], sort => [{propertyName => "projectName", order => "ascending"}, {propertyName => "createTime", order => "descending"}], select => [{propertyName => 'prop1'}, {propertyName => 'prop2'}] }); print "Return data from CloudBees CD/RO:\n" . $xPath-> findnodes_as_string("/"). "\n"; # Build a list of all the object id's my @allObjectsList; my $nodeset = $xPath->find('//response/objectId'); foreach my $node ($nodeset->get_nodelist) { my $objectId = $node-> string_value(); push (@allObjectsList, $objectId); } # Retrieve the second 2 objects my @objectList = @allObjectsList[2..3]; $xPath = $cmdr->getObjects( {objectId => \@objectList}); print "Return data from CloudBees CD/RO :\n" . $xPath->findnodes_as_string("/"). "\n";

This example shows how to make filters with or and and for finding artifacts matching either of two patterns for the artifact name and modifyTime before a specified date.

# Create the filter list for filtering on artifact name. my @artifactNameFilters; push (@artifactNameFilters, {"propertyName" => "artifactName", "operator" => "equals", "operand1" => "groupId:installer-windows"}, {propertyName => "artifactName", operator => "equals", operand1 => "groupId:installer-linux" }); # Perform the findObjects query my $result = $cmdr->findObjects('artifactVersion', {filter => {operator => "and", # 'and' the different filters below filter => [ \#filter 1 { propertyName => "modifyTime", operator => "lessOrEqual", # Give me all dates before operand1 => "2011-11-10T00:00:00.000Z" # Arbitrary date }, \#filter 2 { operator => 'or', # apply 'or' for the filters in the list filter => \@artifactNameFilters } ] } } ); print "result = " . $result-> findnodes_as_string("/") . "\n"; # Top-level filters are implicitly 'and'ed, so the above findObjects query # could also be written like this: $result = $cmdr->findObjects('artifactVersion', {filter => [ \#filter 1 { propertyName => "modifyTime", operator => "lessOrEqual", # Give me all dates before operand1 => "2011-11-10T00:00:00.000Z" # Arbitrary date }, \#filter 2 { operator => 'or', # apply 'or' for the filters in the list filter => \@artifactNameFilters } ] } );

This example shows how to find a project with a name containing foo and with the description bar.

$cmdr->findObjects('project', { filter => {operator => 'and', filter => [{propertyName => 'projectName', operator => 'contains', operand1 => 'foo'}, {propertyName => 'description', operator => 'equals', operand1 => 'bar'}]}});

This example shows how to find a procedure with the project name foo and with the procedure name bar or not bat. (The top level filters are implicitly combined with and.)

$cmdr->findObjects('procedure', { filter => [{propertyName => 'projectName', operator => 'equals', operand1 => 'foo'}, {operator => 'or', filter => [{propertyName => 'procedureName', operator => 'equals', operand1 => 'bar'}, {operator => 'not', filter => {propertyName => 'procedureName', operator => 'equals', operand1 => 'bat'}}]}]});

This example shows how to find a project with certain property values.

$cmdr->findObjects("project", { filter => {operator => 'or', filter => [{propertyName => 'prop1', operator => 'equals', operand1 => 'value1'}, {propertyName => 'prop2', operator => 'equals', operand1 => 'value2'}, {propertyName => 'prop3', operator => 'isNull'}]}

ectool

The following examples shows how to use findObjects with ectool commands.

You can find the property names, and the associated datatypes for any entity, using describeObject API.

Find schedules

This example shows how to find all enabled schedules.

ectool findObjects schedule --filters "{ propertyName=>'scheduleDisabled', operator=>'equals', operand1=>'false'}"

This example shows how to find all disabled schedules.

ectool findObjects schedule --filters "{ propertyName=>'scheduleDisabled', operator=>'equals', operand1=>'true'}"

Find projects based on name

This example retrieves projects whose name contains test.

ectool findObjects project --filters "{ propertyName=>'projectName', operator=>'contains', operand1=>'test'}"

Find projects based on tags

This example retrieves projects with the tag qa.

ectool findObjects project --filters "{ propertyName=>'tags',operator=>'equals',operand1=>'qa'}"

Find projects based on multiple criteria

This example retrieves projects with the test in the name and with the tag qa.

ectool findObjects project --filters "[{ propertyName=>'projectName', operator=>'contains', operand1=>'test'}, {propertyName=>'tags',operator=>'equals',operand1=>'qa'}]"

Find releases based on time-specific details

The following examples retrieve releases based on time-specific details.

Find releases based on created, modified, or archived times
createTime
modifyTime
archiveTime
# Find releases based on their creation time within a time period: ectool findObjects release --filters "{ propertyName=>'createTime', operator=>'between', operand1=>'2024-10-14T12:30:00', operand2=>'2024-11-21T13:30:00' }"
# Find releases based on their modification time within a time period: ectool findObjects release --filters "{ propertyName=>'modifyTime', operator=>'between', operand1=>'2024-09-01T12:30:00', operand2=>'2024-11-21T13:30:00' }"
# Find releases based on their archive time within a time period: ectool findObjects release --filters "{ propertyName=>'archiveTime', operator=>'between', operand1=>'2024-10-01T12:30:00', operand2=>'2024-11-21T13:30:00' }"
Find releases based on start and end times
plannedStartTime
actualStartTime
plannedEndTime
actualEndTime
# Find releases based on their planned start time within a time period: ectool findObjects release --filters "{ propertyName=>'plannedStartTime', operator=>'between', operand1=>'2024-10-15T12:30:00', operand2=>'2024-10-17T13:30:00' }"
# Find all releases based on their actual start time within a time period: ectool findObjects release --filters "{ propertyName=>'actualStartTime', operator=>'between', operand1=>'2024-10-15T12:30:00', operand2=>'2024-11-21T13:30:00' }"
# Find releases based on their planned end time within a time period: ectool findObjects release --filters "{ propertyName=>'plannedEndTime', operator=>'between', operand1=>'2024-10-01T12:30:00', operand2=>'2024-10-29T13:30:00' }"
# Find releases based on their actual end time within a time period: ectool findObjects release --filters "{ propertyName=>'actualEndTime', operator=>'between', operand1=>'2024-11-20T12:30:00', operand2=>'2024-11-21T13:30:00' }"

Find pipelines based on time-specific details

The following examples retrieve pipelines based on time-specific details.

createTime
modifyTime
# Find pipelines based on when they were created within a time period: ectool findObjects pipeline --filters "{ propertyName=>'createTime', operator=>'between', operand1=>'2024-11-13T12:30:00', operand2=>'2024-11-21T13:30:00' }"
# Find pipelines based on when they were last modified within a time period: ectool findObjects pipeline --filters "{ propertyName=>'modifyTime', operator=>'between', operand1=>'2024-11-10T12:30:00', operand2=>'2024-11-21T13:30:00' }"

Time-specific operator examples

The following examples demonstrate how to use different operators for time-specific queries within commands:

greaterThan
lessThan
notEqual
isNull
isNotNull
# Find releases that occurred after a date/time: ectool findObjects release --filters "{ propertyName=>'plannedStartTime', operator=>'greaterThan', operand1=>'2024-12-03T12:30:00' }"
# Find releases that occurred before a date/time: ectool findObjects release --filters "{ propertyName=>'plannedEndTime', operator=>'lessThan', operand1=>'2024-12-05T12:30:00' }"
# Find all releases that did not occur on a specific date/time: ectool findObjects release --filters "{ propertyName=>'actualStartTime', operator=>'notEqual', operand1=>'2024-12-05T12:30:00' }"
# Find all releases without an actualStartTime property assigned: ectool findObjects release --filters "{ propertyName=>'actualStartTime', operator=>'isNull' }"
# Find all releases with an actualStartTime property assigned: ectool findObjects release --filters "{ propertyName=>'actualStartTime', operator=>'isNotNull' }"