The Advanced CIS REST Web API supports the ability to perform advanced searches against customer/account and related data in order to retrieve matching records in a single function. The functionality and results exactly mimic the search features in the CIS AccountView form. Indeed, the same API is used for both, ensuring the search behavior and results are consistent across all interfaces.
There are two APIs related to searching. The legacy end point at /data/customeraccount/search which supports searching for customer/accounts only, and the new search API at /data/customeraccount/$search which is more generic and powerful. The newer $search API is also available at additional end points at /data/customer and /data/account to search for those items, and may be expanded to other end points in the future.
Refer to the specific section below describing the specific search API you are interested in.
This is the newer and preferred search mechanism if you are implemented new functionality. It will be supported and enhanced on an ongoing basis.
This functionality is implemented as two related end points: a $searchconfig end point to retrieve configuration details that itemize every alias, target, table, and field supported by that search; and a $search end point that submits the actual search and returns details about the search results. These end points are general, and will be added to more contexts as needed, but they are currently available on the /data/customer, /data/customeraccount, and /data/account end points.
Retrieve a list of tables, fields, aliases supported by the context (customeraccount in this case). Used to validate input and offer help, code completion, and intellisense to search providers using this end point. It is not required to use this search; it is an aid for reflection/discovery purposes related to this search context. See the REST Swagger details for this end point to review the details of the returned data.
Invoke a search on the context (customeraccount in this case) using the given query string. Refer to the details below for an explanation of the query string contents and possibilities. The return data can include the found context business object, and/or a formatted result line with selected content taken from the result object and its children and match conditions, and/or also any child or related items of the result object by using the optional standard fields= directive. See the Swagger documentation for this end point for details on the result data format. The order of the results is done in match weight order. Items with a higher match weight are sorted higher in the result list. Match weights are set in the CIS application dictionary and are highest for fields in the target table and lower for related tables.
|
Query String |
Description |
|
query= |
The general format for a search query string is: [target:] terms [ AND|OR [target:] terms …]
The target: is optional and can be used to specifically target a field, table, or special alias; the terms are any combination of the following and can be combined using AND, OR, and NOT operators:
Wildcards can be used in any search query: * or % for any number of characters, ? or _ for a single character, and ^ or / to determine the starting or ending character. Search queries require minimum of 3 characters, unless it is an exact term search or name or address search as explained later. Specific NULL keyword can be used to search for null values in a field, while EMPTY keyword or "" can be used to search for empty strings or null values in a field. NULL or EMPTY keywords are case-insensitive and can be used in combination with other keywords or operators. Examples: firstname: john AND (birthday: [1980-01-01:2000-01-01] OR age: [20:40]) firstname: john lastname: NOT (smith OR nazeri) firstname: "john" lastname: "smith" firstname: jo?? firstname: jo% firstname: ^jo firstname: hn^ firstname: NULL firstname: EMPTY customer.firstname: NOT EMPTY AND customer.nametype: C
Date, Date/Time, Boolean format:
ContextsA search is performed in a Context. A Search-Context is combination of a main table and its related tables. If a match if found, the record from the main table is returned. For each search-context, the search is performed in all Searchable fields of corresponding tables. Searchable fields are defined in AppDict. For example, the “CustomerAccount” search-context, performs search in BIF003 and all its related tables including Customer (BIF001), Account (BIF002), Address (BIF006), … but the result of this search always returns a context item, e.g. CustomerAccount. So far only the following search-contexts are implemented:
The result of a search query is the list of primary keys of a main table of a search-context together with table/field names of its related tables where data matches were found. The detail of a search result is the underlying business object associated to the main table of the search-context and a Description Text object explaining the content of the search result.
General features of the CisSearch:
Special Aliases feature of the CisSearch:Along with the standard table and business name targets, there are several special alias targets implemented. These targets implement special meaning and handling of the search terms applied to them. Special target aliases begin with a “.” To indicate they are special targets and to avoid name overlaps with table names or business names. The currently implemented special alias targets are .name, .address, and .serviceaddress. Customer name search using .name: The combined fields representing a name in the Customer (BIF001) table can be targeted for intelligent searches using the alias .name:
Examples: .name: john smith .name: smith, john .name: auto repair
Customer address search using .address: Customer/Account address search is performed by an alias .address:
Service address search using .serviceaddress:
Examples: .serviceaddress: 123 main .address: main st, smallville 90210 .address: apt 12 main st
Payment search using .payment:
Examples: .payment: $201.55 .payment: 201.55 456 .payment: 201.55 1/1/2021 .payment: 201.55 1/1/2021-12/31/2021 .payment: 201.55 -06/15/2022 ref444
Meter search using .meter:
Active Meter search using .ameter:
Examples: .meter: 5612345 .ameter: E554367 electric .meter: KL665431 wa
Service Order search using .so:
Examples: .so: 101145 .so: 10555-10590 turn off .so: 560000- LALO
|
|
fields= |
Optional data shaping directive; include or exclude fields by using a comma separated list of fields or elements; prefix field with '-' to exclude item. The optional embedded child items 'Account', 'Customer', 'CustomerAccount', 'Address', and 'ContactInformation' are also available via this query string. These items will be returned as standard embedded objects in the _embedded container of each result item. Children of these children are also supported using the standard fields= syntax for selecting them.
The default is '*' |
|
maximum= |
Optional maximum number of search results to limit the response to. The default value is 100. |
|
loadcount= |
Optional parameter to indicate whether you want the total match count returned. This is an optimization parameter meant to suppress the match count from being returned in order to return the results more quickly. This is typically used in combination with the maximum= directive to e.g. quickly return the top e.g. 10 matches for a given search. Suppressing the match count improves performance because the search does not have to do extra work to quantify the result set when the total match is not needed and only a limited number of items are requested. The default is true. |
This search is a legacy implementation. There are no plans to remove it, but it will not be expanded or enhanced. Refer to the $search form of the search API for the best search experience available via the CIS API.
The search function is invoked via a HTTP GET against /data/customeraccount/search
The full URL signature is:
GET: /data/customeraccount/search?where=&fields=&maximum=&order=
|
Query String |
Description |
|
where= |
Search condition(s) to be used. Multiple conditions must be AND connected. Field names to search are formatted as ‘class.property’ or ‘table.field’. Only 'eq' and 'like' expressions are currently supported. Note that an OR connector will be accepted but is treated like an AND - all expressions are additive irrespective of connector type. Table / class prefixes to be used in the expressions can come from the subset of tables/classes:
Additionally, there are a few special prefixes with interesting functionality:
Examples: where=name.lastname like 'SMI*' and name.firstname like 'JO*' where=account.streetname like 'MAIN*' and account.town eq 'TORONTO where=bif001.c_nametype eq 'C' and bif001.c_lastname like '*CORP*' and address.c_town eq 'MYVILLE' where=serviceorder.serviceordertype eq 'FIX1' AND accountmeter.meter like '1234*' AND accountservice.service eq '10' where=name.lastname like 'ACME *' and address.streetname eq 'MAIN' |
|
fields= |
Optional data shaping directive; include or exclude fields by using a comma separated list of fields or elements; prefix field with '-' to exclude item. The optional embedded child items 'Account', 'Customer', 'CustomerAccount', 'Address', and 'ContactInformation' are also available via this query string. These items will be returned as standard embedded objects in the _embedded container of each result item. Children of these children are also supported using the standard fields= syntax for selecting them.
|
|
maximum= |
Optional maximum number of search results to limit the response to. The default and maximum value allowed is 500. Any value outside the range 1-500 will cause 500 to be used. The total number of matches will always be returned in the result TotalItems property no matter the limit applied; this allows you to know how many matches really occurred even though you did not retrieve details for all of them. |
|
order= |
Optional comma separated list of result fields to use to sort the result list. Prefix fields with “-“ to sort descending. The sort field names should be taken from the available fields in the CustomerAccountSearchResulItemtModel return results. Only basic search result fields can be used to sort on - not _embedded data. |
The basic result data includes formatted names and formatted addresses for all matching records.
The result set is meant to select a BIF003/customeraccount record, so searching on e.g. name will return multiple records for the same person if that person has multiple customer/account items, or is in the process of moving (in which case the outgoing and the incoming items are returned). The results include BIF001PK, BIF002PK, and BIF003PK, so it is easy to dedupe the results cased on service address or customer if that’s all you need, but typically the resulting selection would be used to select the applicable BIF003/customeraccount, so deduping might not be advisable.
Refer to the fields= query string for details on including additional child object data for each result item. Doing this may save you additional calls if the data you require is available in one of the available children.
Refer to the detailed definitions of the CustomerAccountSearchResultModel and CustomerAccountSearchResultItemModel for names and descriptions of the returned result properties.