findObjects

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.

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

This example shows how to find all enabled schedules.

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