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/ROSearch
feature.For a list of object types in CloudBees CD/RO, refer to Object types in CloudBees CD/RO. |
objectTypeStringrequiredThe object type to search for. caseSensitiveSearchBooleanoptionalApplicable only for case-sensitive databases. When set to True (default), searches are case-sensitive. When set to False , searches are case-insensitive.filterArrayoptionalA list of zero or more filter criteria definitions used to define objects to find. firstResultIntegeroptionalThe first result to be retrieved, numbered from 0. includeAccessBooleanoptionalTrue to fetch the objects' access maps as well. includeEntityRevisionsBooleanoptionalInclude versions/entity revision if it is a revisionable object in the search result. includeLatestRevisionBooleanoptionalInclude the latest revision data for versioned objects. maxIdsIntegeroptionalThe maximum number of object IDs to return. numObjectsIntegeroptionalThe number of objects to return as the first page of results. quickSearchFilterStringoptionalQuick search filter. selectArrayoptionalCustom properties to project into the query results. sortArrayoptionalSort specifications. viewNameStringoptionalThe 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
# 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
# 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.
# 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:
# 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' }"