Service: zimbraAccount

Command: SearchGal
Namespace: urn:zimbraAccount
Description: Search Global Address List (GAL)
Properties:
Authorization token required true
Admin Authorization token required false

SearchGalRequest

    <SearchGalRequest [ref="{gal-search-ref-DN}"] [name="{query-string}"] [type="(all | account | resource | group)"]
                         [needExp="{need-can-expand} (0|1)"] [needIsOwner="{need-isOwner-flag-in-response} (0|1)"]
                         [needIsMember="{need-isMember-all|directOnly|none} (all | directOnly | none)"]
                         [needSMIMECerts="{internal-use-only} (0|1)"] [galAcctId="{gal-account-id}"] [quick="(0|1)"]
                         [sortBy="{sort-by}"] [limit="{query-limit} (Integer)"] [offset="{query-offset} (Integer)"]> ## SearchGalRequest
        <locale>{locale} (String)</locale>
        <cursor [id="{cursor-prev-id}"] [sortVal="{cursor-sort-value}"] [endSortVal="{cursor-end-sort-value}"]
                    [includeOffset="{cursor-include-offset} (0|1)"] /> ## CursorInfo
        <query>{query} (String)</query>
        <searchFilter> ## EntrySearchFilterInfo
            Choose one of: {
                <conds [not="{not} (0|1)"] [or="{or} (0|1)"]> ## EntrySearchFilterMultiCond
                    List of any of: {
                        <conds> ... </conds> ## See /searchFilter/conds [ ## EntrySearchFilterMultiCond] # [inside itself]
                        <cond [not="{not} (0|1)"] attr="{single-cond-attr}" op="{single-cond-op}" value="..." /> ## EntrySearchFilterSingleCond
                    }
                 </conds>
                <cond ... /> ## See /searchFilter/conds/cond [ ## EntrySearchFilterSingleCond]
            }
         </searchFilter>
    </SearchGalRequest>

elements and attributes you can define within a <SearchGalRequest> element:

XPath Required / Optional Description
@ref Optional (0 or 1) Type: String
If set then search GAL by this ref, which is a dn. If specified then "name" attribute is ignored.
@name Optional (0 or 1) Type: String
Query string. Note: ignored if {gal-search-ref-DN} is specified
@type Optional (0 or 1) Type: all | account | resource | group
type of addresses to auto-complete on
  • "account" for regular user accounts, aliases and distribution lists
  • "resource" for calendar resources
  • "group" for groups
  • "all" for combination of all types
if omitted, defaults to "all"
@needExp Optional (0 or 1) Type: 0|1
flag whether the {exp} flag is needed in the response for group entries. Default is unset.
@needIsOwner Optional (0 or 1) Type: 0|1
Set this if the "isOwner" flag is needed in the response for group entries. Default is unset.
@needIsMember Optional (0 or 1) Type: all | directOnly | none
Specify if the "isMember" flag is needed in the response for group entries.
all the isMember flag returned is set if the user is a direct or indirect member of the group, otherwise it is unset
directOnly the isMember flag returned is set if the user is a direct member of the group, otherwise it is unset
none (default) The isMember flag is not returned
@needSMIMECerts Optional (0 or 1) Type: 0|1
Internal attr, for proxied GSA search from GetSMIMEPublicCerts only
@galAcctId Optional (0 or 1) Type: String
GAL Account ID
@quick Optional (0 or 1) Type: 0|1
"Quick" flag.
For performance reasons, the index system accumulates messages with not-indexed-yet state until a certain threshold and indexes them as a batch. To return up-to-date search results, the index system also indexes those pending messages right before a search. To lower latencies, this option gives a hint to the index system not to trigger this catch-up index prior to the search by giving up the freshness of the search results, i.e. recent messages may not be included in the search results.
@sortBy Optional (0 or 1) Type: String
SortBy setting.
Default value is "dateDesc"
Possible values: none|dateAsc|dateDesc|subjAsc|subjDesc|nameAsc|nameDesc|rcptAsc|rcptDesc|attachAsc|attachDesc|flagAsc|flagDesc| priorityAsc|priorityDesc If {sort-by} is "none" then cursors MUST NOT be used, and some searches are impossible (searches that require intersection of complex sub-ops). Server will throw an IllegalArgumentException if the search is invalid.
@limit Optional (0 or 1) Type: Integer
The maximum number of results to return. It defaults to 10 if not specified, and is
@offset Optional (0 or 1) Type: Integer
Specifies the 0-based offset into the results list to return as the first result for this search operation.
For example, limit=10 offset=30 will return the 31st through 40th results inclusive.
/locale Optional (0 or 1) Type: {locale} (String)
Client locale identification.
Value is of the form LL-CC[-V+] where:
LL is two character language code
CC is two character country code
V+ is optional variant identifier string

See:
ISO Language Codes: http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt
ISO Country Codes: http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html
/cursor Optional (0 or 1) Cursor specification
/cursor@id Optional (0 or 1) Type: String
Previous ID. cursor-prev-id and cursor-sort-value and correspond to the last hit on the current page (assuming you're going forward, if you're backing up then they should be the first hit on the current page) or the selected item before changing the sort order. cursor-sort-value should be set to the value of the 'sf' (SortField) attribute. If you are changing the sort field, don't specify sortVal because 'sf' is sort field dependent. (In this case, the server supplements sortVal using the specified item ID. If the item no longer exist, the cursor gets cleared.) The server uses those attributes to find the spot in the new results that corresponds to your old position: even if some entries have been removed or added to the search results (e.g. if you are searching is:unread and you read some).
/cursor@sortVal Optional (0 or 1) Type: String
Should be set to the value of the 'sf' (SortField) attribute. See description for cursor-prev-id for more information.
/cursor@endSortVal Optional (0 or 1) Type: String
Used for ranges to tell the cursor where to stop (non-inclusive) returning values
/cursor@includeOffset Optional (0 or 1) Type: 0|1
If true, the response will include the cursor position (starting from 0) in the entire hits. This can't be used with text queries. Don't abuse this option because this operation is relatively expensive
/query Optional (0 or 1) Type: {query} (String)
query string
/searchFilter Optional (0 or 1) Search filter specification
/searchFilter/conds Optional (0 or 1)
/searchFilter/conds@not Optional (0 or 1) Type: 0|1
Negation flag
If set to 1 (true) then negate the compound condition
/searchFilter/conds@or Optional (0 or 1) Type: 0|1
OR flag
1 (true) child conditions are OR'ed together
0 (false) [default] child conditions are AND'ed together
/searchFilter/conds/conds Optional (0 or 1) See /searchFilter/conds for more details.
/searchFilter/conds/cond Optional (0 or 1)
/searchFilter/conds/cond@not Optional (0 or 1) Type: 0|1
Negation flag
If set to 1 (true) then negate the compound condition
/searchFilter/conds/cond@attr Required (only 1) Type: String
Attribute name
/searchFilter/conds/cond@op Required (only 1) Type: String
Operator. Valid operators are:
eq attr equals value (integer or string)
has attr has value (substring search)
ge attr greater than or equal to integer value
le attr less than or equal to integer value
gt attr greater than (but not equal to) equal to integer value
lt attr less than (but not equal to) to integer value
startswith attr starts with value (string)
endswith attr ends with value (string)
/searchFilter/conds/cond@value Required (only 1) Type: String
value
/searchFilter/cond Optional (0 or 1) See /searchFilter/conds/cond for more details.

SearchGalResponse

    <SearchGalResponse [sortBy="{sort-by}"] [offset="(Integer)"] [more="(0|1)"]
                          [paginationSupported="{pagination-supported} (0|1)"] [tokenizeKey="{tokenize-key-op} (0|1)"]> ## SearchGalResponse
        (<cn [sf="{contact-sort-field-value}"] [exp="(0|1)"] id="{contact-id}" [l="{contact-folder}"]
                 [f="{contact-flags}"] [t="..."] [tn="{contact-tag-names}"] [md="{contact-change-date} (Long)"]
                 [ms="{modified-seq-id} (Integer)"] [d="{contact-date} (Long)"] [rev="{contact-revision-id} (Integer)"]
                 [fileAsStr="{contact-fileAs}"] [email="{contact-email-1}"] [email2="{contact-email-2}"]
                 [email3="{contact-email-3}"] [type="{contact-type}"] [dlist="..."] [ref="{contact-ref}"]
                 [tooManyMembers="{contact-group-too-many-members} (0|1)"] [isOwner="{isOwner} (0|1)"]
                 [isMember="{isMember} (0|1)"]> ## ContactInfo
            (<meta [section="{metadata-section-key}"]> ## AccountCustomMetadata
                (<a n="{key}">{value}</a> ## KeyValuePair)*
              </meta>)*
            (<a [part="{contact-part-id}"] [ct="{contact-content-type}"] [s="{contact-size} (Integer)"]
                    [filename="{contact-content-filename}"] n="{key}" /> ## ContactAttr)*
            (<m type="{contact-group-member-type}" value="{contact-group-member-value}"> ## ContactGroupMember
                <cn> ... </cn> ## See /cn [ ## ContactInfo] # [inside itself]
              </m>)*
          </cn>)*
    </SearchGalResponse>

elements and attributes you can define within a <SearchGalResponse> element:

XPath Required / Optional Description
@sortBy Optional (0 or 1) Type: String
Name of attribute sorted on.
@offset Optional (0 or 1) Type: Integer
The 0-based offset into the results list returned as the first result for this search operation.
@more Optional (0 or 1) Type: 0|1
Flags whether there are more results
@paginationSupported Optional (0 or 1) Type: 0|1
Flag whether the underlying search supported pagination.
  • 1 (true) - limit and offset in the request was honored
  • 0 (false) - the underlying search does not support pagination. limit and offset in the request was not honored
@tokenizeKey Optional (0 or 1) Type: 0|1
Valid values: and|or
  • Not present if the search key was not tokenized.
  • Some clients backtrack on GAL results assuming the results of a more specific key is the subset of a more generic key, and it checks cached results instead of issuing another SOAP request to the server. If search key was tokenized and expanded with AND or OR, this cannot be assumed.
/cn Optional (0 or more) Matching contacts
/cn@sf Optional (0 or 1) Type: String
Sort field value
/cn@exp Optional (0 or 1) Type: 0|1
/cn@id Required (only 1) Type: String
Contact ID
/cn@l Optional (0 or 1) Type: String
Folder
/cn@f Optional (0 or 1) Type: String
Flags
/cn@t Optional (0 or 1) Type: String
Tags (deprecated)
/cn@tn Optional (0 or 1) Type: String
Tag names
/cn@md Optional (0 or 1) Type: Long
Change date
/cn@ms Optional (0 or 1) Type: Integer
Modified sequence ID
/cn@d Optional (0 or 1) Type: Long
Contact date
/cn@rev Optional (0 or 1) Type: Integer
Revision ID
/cn@fileAsStr Optional (0 or 1) Type: String
FileAs string for contact
/cn@email Optional (0 or 1) Type: String
Email address 1
/cn@email2 Optional (0 or 1) Type: String
Email address 2
/cn@email3 Optional (0 or 1) Type: String
Email address 3
/cn@type Optional (0 or 1) Type: String
Contact type
Default value is "contact". If is present and set to "group", then the contact is a personal distribution list.
/cn@dlist Optional (0 or 1) Type: String
dlist - retained for backwards compatibility
/cn@ref Optional (0 or 1) Type: String
Reference
/cn@tooManyMembers Optional (0 or 1) Type: 0|1
Flag whether there were too many members.
If the number of members on a GAL group is greater than the specified max, no members are returned and this flag is set to 1 (true) instead.
/cn@isOwner Optional (0 or 1) Type: 0|1
For group entries, flags whether user is the owner of a group (type=group in attrs on a <cn>).
/cn@isMember Optional (0 or 1) Type: 0|1
For group entries, flags whether user is a member of a group (type=group in attrs on a <cn>).
/cn/meta Optional (0 or more) Custom metadata
/cn/meta@section Optional (0 or 1) Type: String
Metadata section key.
Must be no more than 36 characters long and must be in the format of {namespace}:{section-name}. Currently the only valid namespace is "zwc".

Normally present but sometimes an empty element is created to show that custom metadata info is present but there are no sections to report on.
/cn/meta/a Optional (0 or more) Type: {value}
Attributes specified as key value pairs
Description for element text content:Value
/cn/meta/a@n Required (only 1) Type: String
Key
/cn/a Optional (0 or more) Contact attributes
/cn/a@part Optional (0 or 1) Type: String
Part ID.
Can only specify a {contact-part-id} when modifying an existent contact
/cn/a@ct Optional (0 or 1) Type: String
Content type
/cn/a@s Optional (0 or 1) Type: Integer
Size
/cn/a@filename Optional (0 or 1) Type: String
Content filename
/cn/a@n Required (only 1) Type: String
Key
/cn/m Optional (0 or more) Contact group members
/cn/m@type Required (only 1) Type: String
Contact group member type
/cn/m@value Required (only 1) Type: String
Contact group member value
/cn/m/cn Optional (0 or 1) Contact
See /cn for more details.