findAccounts()

AccountSearchResultList findAccounts(SearchCondition searchCondition, int limit, int offset)

This method searches by custom field for accounts and returns an XML document with detailed information about any matches. This method searches only custom fields that you have defined in Smile; it does not search any default properties such as USN or username.

Note: Subscriptions belonging the returned accounts are not displayed.

Parameters

searchCondition: Format: SearchCondition XML; Purpose: Defines a SearchCondition XML document that specifies the custom field attribute and value to find.
limit: Format: integer; Purpose: Specifies the maximum number of results to return. Should be a positive integer not exceeding 200.
offset: Format: integer; Purpose: Specifies a zero-based index position from within the result set of the search from where to begin returning results.
Note: When calling findAccounts() for the first time with a new search, specify zero for this argument.

Example: Find accounts by custom field

This example searches for an account that has the value JoeSmith1 in the custom field client_id.

The value in the <Attribute> element is the code name of the custom field. To find the code name, log in to Smile and click Configuration and Tools > Custom Fields, then click View next to the appropriate custom field. The code name is in the Code field.

The value in the <Value> element is the value in the custom field. If the value is part of a custom collection, specify the code name for the value. To find the code name, log in to Smile and click Configuration and Tools > Custom Collections, then click View next to the appropriate custom collection. The code names are listed next to each value in the custom collection.

<SearchCondition xmlns="http://xml.inomial.com/smile/2.xsd">
  <Equals>
    <Attribute>contactName</Attribute>
    <Value>JoeSmith1</Value>
  </Equals>
</SearchCondition>

Results

This method returns an XML document that contains a list of zero or more elements that matched the search criteria. Each element contains detailed information about that account's properties and status.

This method returns an empty element if no accounts match the search criteria. If there are more matching accounts than are set by the "limit" argument, then the list will be truncated to the specified limit, and the MoreResults attribute of the element will be set to "true". In this case, the additional matching accounts can be retrieved by making a subsequent follow-up call to findAccounts() with the "offset" argument advanced by "limit". For example:

findAccounts(searchCondition, 200, 0);
findAccounts(searchCondition, 200, 200);
findAccounts(searchCondition, 200, 400);
// ...

Until the MoreResults flag becomes "false".

If the offset parameter points beyond the total number of matching accounts for a given search criterion, then an empty element will be returned.

The list of returned accounts will be ordered in a stable manner to allow accurate pagination of results among successive calls to this method, however Inomial reserves the right to alter the ordering algorithm between future Smile version releases without notice.

There are no messages defined by this method.

Example: A returned AccountSearchResultList XML document

This example shows a AccountSearchResultList XML document. The document contains elements which feature account properties, including the attribute and value searched for.

<AccountSearchResultList moreResults="false" limit="100" offset="0">
  <Accounts xsi:type="AccountType" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <USN>1000000008</USN>
    <AccountType key="1">Standard Account</AccountType>
    <InvoicingCycle>
      <CycleType>Anniversary</CycleType>
      <CycleDay>31</CycleDay>
    </InvoicingCycle>
    <RatingCycle>
      <CycleType>Anniversary</CycleType>
      <CycleDay>31</CycleDay>
    </RatingCycle>
    <Timezone key="13">Australia/Melbourne</Timezone>
    <AccountTerms key="1">Default terms</AccountTerms>
    <Properties>
      <Object objectId="848" formId="5" displayName="Account service extended data">
        <String name="abn">123456</String>
        <String name="billAddress">123 Fake Street</String>
        <String name="billBuildingName"/>
        <String name="billCountry"/>
        <String name="billFloorNumber"/>
        <String name="billLotNumber"/>
        <String name="billName"/>
        <String name="billNumber">54321</String>
        <String name="billPostCode"/>
        <String name="billPostalDeliveryType"/>
        <String name="billState"/>
        <String name="billSubUnit"/>
        <String name="billSuburb"/>
        <String name="billType"/>
        <String name="billTypeSuffix"/>
        <String name="comments"/>
        <String name="companyPosition"/>
        <String name="contactFamily">Administrator</String>
        <String name="contactGiven">Administrator</String>
        <String name="contactTitle"/>
        <String name="emailAddress"/>
        <String name="fax"/>
        <String name="homePhone">54321</String>
        <String name="jabberAddress"/>
        <String name="mobilePhone">54321</String>
        <String name="name">Administrator, Administrator</String>
        <String name="secretAnswer"/>
        <String name="secretQuestion"/>
        <String name="sex"/>
        <String name="streetAddress"/>
        <String name="streetBuildingName"/>
        <String name="streetCountry"/>
        <String name="streetFloorNumber"/>
        <String name="streetLotNumber"/>
        <String name="streetName"/>
        <String name="streetNumber"/>
        <String name="streetPostalDeliveryType"/>
        <String name="streetPostcode"/>
        <String name="streetState"/>
        <String name="streetSubUnit"/>
        <String name="streetSuburb"/>
        <String name="streetType"/>
        <String name="streetTypeSuffix"/>
        <String name="tradingName"/>
        <String name="workPhone">54321</String>
        <String name="username">1000000008</String>
        <String name="alternateAccountNumber"/>
        <String name="contactName">JoeSmith1</String>
        <Integer name="preferredHomeContactTime"/>
        <Integer name="preferredMobileContactTime"/>
        <Integer name="preferredWorkContactTime"/>
        <Boolean name="billPrintName">true</Boolean>
        <Boolean name="streetPrintName">true</Boolean>
        <Timestamp name="dob"/>
      </Object>
    </Properties>
  </Accounts>
</AccountSearchResultList>

Faults

InvalidRequestException

This fault is returned when either:

the limit is non-positive or greater than 200
the offset is negative

NoSuchItemException

This fault is returned when the custom field that you are searching for does not exist.

Java client syntax

java -cp build/smilewsv2-client.jar [options]
 com.inomial.smile.client.v2.examples.indAccounts filename [limit [offset]]

filename: Purpose: Defines the filename of the SearchCondition XML document.
limit: Purpose: Specifies the maximum number of results to return; can be between 1 and 200. If omitted, then a default of 100 will be assumed.
offset: Purpose: Specifies a zero-based position index into the search result set from where to start returning results. If omitted, then a default of zero will be assumed.

Note: For more information about the Java client and the options it accepts, see Java client syntax.