Skip to content

Search Operations

Common Use Cases

Many plugins allow you to search for records on the end systems.

For example:

  • Finding Active Directory objects

  • Looking for incidents in an ITSM system

  • Getting servers from a PAM platform

Using Search Results

When writing a Playbook you may need to do any of the following:

  • Get the number of results

  • Supply the results to another action

  • Get the first result

  • Get the last result

To make this easier in a Playbook, all search actions are starting to adopt a new result format.

Legacy Format

Older search actions output a list of results, regardless of how many results are found.

Getting the number of results, & grabbing the first or last result required extra Playbook steps.

Examples

Deprecated Examples

The examples in this section use legacy search actions.

They are here for comparison with the new format.

Checking Number of Results

This example uses the built-in count action to get & save the number of results.

Access Number of Results

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
- active_directory.groups.search:
    search_params:
      sAMAccountName: Test*
  load:
    domain_controller: domain_controller
  save: search_results

- count:
  load:
    item: search_results
  save: result_count

- ppa.ui.output_error:
    text: No test groups were found!
  when: result_count == 0

See the new version here

Searching for Unique Records

This example uses a search with multiple parameters to find a unique user.

You may need to do this if you do not have the value of a unique attribute to search with.

An extra get_first_item action is required to 'unpack' the result before it can be used.

Get First Result

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
- active_directory.users.search:
    search_params:
      mail: john.smith@email.domain
      cn: John Smith
  load:
    domain_controller: domain_controller
  save: search_results

- ppa_tools.lists.get_first_item:
  load:
    items: search_results
  save: result

- active_directory.users.delete:
  load:
    distinguishedName:result.distinguishedName
    domain_controller: domain_controller

See the new version here

Which Actions?

Any search action whose Output documentation doesn't link to this page uses the legacy format.

New Format

The new result format provides easy access the information you need.

Each of the following keys can be used in your Playbook with no extra steps.

Search Result Dictionary

Contents

all: a list of search results

first: the first record in all (or null if nothing was found)

last: the last record in all (or null if nothing was found)

total: the total number of search results

Examples

Checking Number of Results

This example uses the total key to display an error if no results were found.

Access Number of Results

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
- active_directory.groups.search:
    search_params:
      sAMAccountName: Test*
  load:
    domain_controller: domain_controller
  save: search_results

- ppa.ui.output_error:
    text: No test groups were found!
  when: search_results.total == 0

See the legacy version here

Operating on Each Result

This example uses the all key to supply each result into another action.

Use All Results

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
- active_directory.groups.search:
    search_params:
      sAMAccountName: Test*
  load:
    domain_controller: domain_controller
  save: search_results

- active_directory.groups.delete:
  load:
    distinguishedName: loop.action.item.value.distinguishedName
    domain_controller: domain_controller
  sequence: search_results.all

Searching for Unique Records

This example uses a search with multiple parameters to find a unique user.

You may need to do this if you do not have the value of a unique attribute to search with.

The first key allows you to easily supply that single result to another action.

Get First Result

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
- active_directory.users.search:
    search_params:
      mail: john.smith@email.domain
      cn: John Smith
  load:
    domain_controller: domain_controller
  save: search_results

- active_directory.users.delete:
  load:
    distinguishedName: search_results.first.distinguishedName
    domain_controller: domain_controller

See the legacy version here

Which Actions?

Any search action whose Output documentation links to this page uses the new format.