Search filters and SA CLI methods

Many methods in the SA API accept object references as parameters. To retrieve object references based on search criteria, you invoke methods such as findServerRefs and findJobRefs. For example, you can invoke findServerRefs to search for all servers that have example.com in the hostname attribute.

Search syntax

Methods such as findServerRefs have the following syntax:

findobjectRefs filter=’[object-type:]expression’

The filter parameter includes an expression, which specifies the search criteria. You enclose an expression in either parentheses or curly brackets. A simple expression has the following syntax:

value-object.attribute operator value

This syntax is simplified. For the full definition, see Filter grammar.

Search examples

Most of the SA object types have associated finder methods. This section shows how to use just a few of them. To see how searches are used with other SA CLI methods, see Sample scripts.

Finding servers

Find servers with host names containing example.com:

cd /opsw/api/com/opsware/server/ServerService/method
./.findServerRefs:i \
filter=’device:{ ServerVO.hostname CONTAINS example.com }’

Find servers with a use attribute value of either UNKNOWN or PRODUCTION:

cd /opsw/api/com/opsware/server/ServerService/method
./.findServerRefs:i \
filter=’{ ServerVO.use IN “UNKNOWN” “PRODUCTION” }’

The following bash script shows how to search for servers, save their IDs in a temporary file, and then specify each ID as the parameter of another method invocation. This script displays the public groups that each Linux server belongs to.

#!/bin/bash

TMPFILE=/tmp/server-list.txt

rm -f $TMPFILE

cd /opsw/api/com/opsware/server/ServerService/method

./.findServerRefs:i \

filter='{ ServerVO.osVersion CONTAINS Linux }' > $TMPFILE

for ID in `cat "$TMPFILE"`

do  

  echo Server ID: $ID

  ./getDeviceGroups self:i=$ID

  echo

done

Finding jobs

The examples in this section return the IDs of jobs such as server audits or policy remediations.

Find the jobs that have completed successfully:

cd /opsw/api/com/opsware/job/JobService/method

./.findJobRefs:i filter='job:{ job_status = "SUCCESS" }'

(For a list of allowed values of job_status, see “Job Approval Integration” in the SA Integrate section.)

Find the jobs that have completed successfully or with warning:

cd /opsw/api/com/opsware/job/JobService/method

./.findJobRefs:i \

filter='job:{ job_status IN "SUCCESS" "WARNING" }'

Find the jobs that have been started today:

cd /opsw/api/com/opsware/job/JobService/method

./.findJobRefs:i \

filter='job:{ JobInfoVO.startDate IS_TODAY "" }'

Find all server audit jobs:

cd /opsw/api/com/opsware/job/JobService/method

./findJobRefs \

filter='job:{ JobInfoVO.description = "Server Audit" }'

Find the jobs that have run on the server with the ID 280039:

cd /opsw/api/com/opsware/job/JobService/method

./.findJobRefs:i filter='job:{ job_device_id = "280039" }'

Find today’s jobs that have failed:

cd /opsw/api/com/opsware/job/JobService/method

./.findJobRefs:i \

filter='job:{ (( JobInfoVO.startDate IS_TODAY "" ) \

& ( job_status = "FAILURE" )) }'

Finding other objects

This section has examples that search for software policies and packages.

Find the software policies created by the SA user jdoe:

cd /opsw/api/com/opsware/swmgmt/SoftwarePolicyService/method

./.findSoftwarePolicyRefs:i \

filter=’{ SoftwarePolicyVO.createdBy CONTAINS jdoe }’

Find the MSIs with ismtool for the Windows 2003 platforms:

cd /opsw/api/com/opsware/pkg/UnitService/method

./.findUnitRefs:i \

filter='software_unit:{ ((UnitVO.unitType = "MSI") \

& ( UnitVO.name contains "ismtool" ) \

& ( software_platform_name = "Windows 2003" )) }'

Find the Solaris patches named 117170-01:

cd /opsw/api/com/opsware/pkg/solaris/SolPatchService/method

./.findSolPatchRefs:i filter='{name = 117170-01}' 

Find the folder with the name that includes the string Test and with a parent folder named My Stuff.

cd /opsw/api/com/opsware/folder/FolderService/method

./.findFolders:s \

filter='( ( FolderVO.name CONTAINS "Test" ) \

& (folder_parent_name = "My Stuff" ) )'

Searchable attributes and valid operators

Not every attribute of a value object can be specified in a search filter. For example, you can search on ServerVO.use but not on ServerVO.OsFlavor.

To find out which attributes are searchable for a given object type, invoke the getSearchableAttributes method. The following example lists the attributes of ServerVO that can be specified in a search expression:

cd /opsw/api/com/opsware/search/SearchService/method

./getSearchableAttributes searchableType=device

The searchableType parameter indicates the object type. To determine the allowed values for searchableType, enter the following commands:

cd /opsw/api/com/opsware/search/SearchService/method

./getSearchableTypes

To find out which operators are valid for an attribute, invoke the getSearchableAttributeOperators method. The following example lists valid operators (such as CONTAINS and IN) for the attribute ServerVO.hostname:

cd /opsw/api/com/opsware/search/SearchService/method

./getSearchableAttributeOperators searchableType=device \

searchableAttribute=ServerVO.hostname