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.

Refer to the following table for the list of object types in CloudBees CD/RO:

application

applicationDependency

applicationServiceMapping

applicationTier

artifact

artifactVersion

catalog

catalogItem

cluster

component

container

credential

dashboard

deployerApplication

deployerConfiguration

deployerService

devOpsInsightServerConfiguration

directoryProvider

emailConfig

emailNotifier

entityChange

environment

environmentInventoryItem

environmentMap

environmentTemplate

environmentTemplateTier

environmentTemplateTierMap

environmentTier

environmentVariable

eventSubscription

gate

gateway

hook

formalParameter

flow

flowState

flowRuntime

job

jobStep

logEntry

note

pipeline

plugin

port

procedure

procedureStep

process

processDependency

processStep

project

property

release

report

reportObjectAssociation

reportObjectAttribute

reportObjectType

reportingFilter

repository

reservation

resource

resourcePool

resourceTemplate

retrievedArtifact

rollingDeployPhase

schedule

service

serviceClusterMapping

serviceDependency

serviceMapDetail

snapshot

stage

state

stateDefinition

step

task

tierMap

transition

transitionDefinition

utilityResource

waitDependency

widget

workflow

workflowDefinition

workspace

objectType

Stringrequired

The object type to search for.

filters

Collectionoptional

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.

selects

Collectionoptional

Custom properties to project into the query results.

sorts

Collectionoptional

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'}"▼