findSubscriptions()

SubscriptionSearchResultList findSubscriptions(SearchCondition searchCondition, int limit, int offset)

This method searches by custom field for a non-closed subscription and returns an XML document with detailed information about the matching subscriptions. This method searches only custom fields that you have defined in Smile; it does not search any default properties such as USN or username.

You can call this method at any point in the subscription lifecycle after the subscription order is entered.

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 findSubscriptions() for the first time with a new search, specify zero for this argument.

Example: Find subscriptions by custom field

This example searches for a subscription 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> field 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>client_id</Attribute>
    <Value>JoeSmith1</Value>
  </Equals>
</SearchCondition>

Results

This method returns a SubscriptionSearchResultList XML document that contains a list of zero or more <Subscription> elements that matched the search criteria.

Each <Subscription> element contains detailed information about that subscription's properties and status.

This method returns an empty <SubscriptionSearchResultList> element if no subscriptions match the search criteria.

If there are more matching subscriptions than that set by the "limit" argument, then the list will be truncated to the specified limit, and the MoreResults attribute of the <SubscriptionSearchResultList> element will be set to "true".

In this case, the additional matching subscriptions can be retrieved by making a subsequent follow-up call to findSubscriptions() with the "offset" argument advanced by "limit". For example:

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

Until the MoreResults flag becomes "false".

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

It is guaranteed that the list of returned subscriptions will always 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 SubscriptionSearchResultList XML document

This example shows a SubscriptionSearchResultList XML document. The document contains two examples of the Subscription element which features subscription properties (username, given name, family name, number of phone lines and the custom field client_id) and the subscription's status (provisioned, not suspended, activated and enabled).

Note: Smile uses the key attribute on the <Timezone> and <Costcentre> elements as an internal identifier.

<SubscriptionSearchResultList xmlns="http://xml.inomial.com/smile/2.xsd" moreResults="false" limit="200" offset="0">
  <Subscription>
    <USN>120398123</USN>
    <SID>15</SID>
    <ServiceName>VOIP</ServiceName>
    <Parent>1204921324</Parent>
    <Properties>
      <Object>
        <String name="username">+61355501256</String>
        <String name="contactGiven">Joe</String>
        <String name="contactFamily">Smith</String>
        <Integer name="phoneLines">13</Integer>
        <String name="client_id">JoeSmith1</String>
        <String name="voipRouterType">Acme 2000</String>
      </Object>
    </Properties>
    <ProvisionStatus>Provisioned</ProvisionStatus>
    <SuspendStatus>Active</SuspendStatus>
    <ActivateStatus>Activated</ActivateStatus>
    <EnableStatus>Enabled</EnableStatus>
    <InvoicingCycle>
      <CycleType>Anniversary</CycleType>
      <CycleDay>24</CycleDay>
    </InvoicingCycle>
    <RatingCycle>
      <CycleType>Anniversary</CycleType>
      <CycleDay>24</CycleDay>
    </RatingCycle>
    <Timezone key="19">Australia/Sydney</Timezone>
    <CostCentre key="1">Example cost centre</CostCentre>
  </Subscription>
  <Subscription>
    <USN>120398134</USN>
    <SID>15</SID>
    <ServiceName>VOIP</ServiceName>
    <Parent>1204921324</Parent>
    <Properties>
      <Object>
        <String name="username">+61355501357</String>
        <String name="contactGiven">John</String>
        <String name="contactFamily">Doe</String>
        <Integer name="phoneLines">14</Integer>
        <String name="client_id">JohnDoe1</String>
        <String name="voipRouterType">Acme 2000</String>
      </Object>
    </Properties>
    <ProvisionStatus>Provisioned</ProvisionStatus>
    <SuspendStatus>Active</SuspendStatus>
    <ActivateStatus>Activated</ActivateStatus>
    <EnableStatus>Enabled</EnableStatus>
    <InvoicingCycle>
      <CycleType>Anniversary</CycleType>
      <CycleDay>24</CycleDay>
    </InvoicingCycle>
    <RatingCycle>
      <CycleType>Anniversary</CycleType>
      <CycleDay>24</CycleDay>
    </RatingCycle>
    <Timezone key="19">Australia/Sydney</Timezone>
    <CostCentre key="1">Example cost centre</CostCentre>
  </Subscription>
</SubscriptionSearchResultList>

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.FindSubscriptions propName value [limit [offset]]

propName: Purpose: Specifies the custom field code name.
value: Purpose: Specifies the custom field value to find.
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.