Executes a preconfigured named Saved Search against the specified table and/or an ad-hoc query and returns and array of record data for the records that match the criteria.
EWWSBaseUserObject[] os = ew.EWSearchTableWithQuery(String sessionId, String tableName, String[] fieldNames, String searchName, String query); |
Use EWSearchTableWithQuery call to search for records in the specified table based on a Saved Search pre-configured in the GUI and/or to filter the records with an ad-hoc query.
When querying records, consider the following rules and guidelines:
This method never returns null. In the case when no records are found an empty array is returned.
Special note on memory management: As WS integration implies pass-by-value semantics, the memory allocated for the resulting array will be released once the data is sent to the client and the server-side JVM's garbage collector considers it eligible for discarding.
In MyKB knowledgebase, as user A, find all cases assigned to the user used to login with low priority. Return summaries as a String array.
Completion of the task is performed by the following steps:
You can generate sample Web Services code for any table by selecting Setup > Table > [Select Table to Edit] > API > Download Sample.
public String[] search() throws Exception { EWServiceAPI binding = new EWServiceAPIServiceLocator().getDemo(); try { String sessionId = binding.EWLogin("MyKB", "A", "password", "en"); EWWSBaseUserObject[] records = binding.EWSearchTableWithQuery(sessionId, "case", new String[] {"summary"}, "My Assigned", "Priority=Low"); String[] result = new String[records.length]; for (int i=0; i<records.length; i++) { result[i] = records[i].getSummary(); } return result; } finally { binding.EWLogout(sessionId); } } |
Name | Type | Description |
---|---|---|
sessionId | String | Session token |
tableName | String | The name of the table where the query has to be performed. |
fieldNames | String array | The list of fields to read |
searchName | String | The optional name of the Saved Search to run |
query | String | The ad-hoc query |
An array of the records as descendants of EWWSBaseUserObject - a complex structure described in WSDL.
EWSessionException - client not logged in or session has expired; client should re-login.
EWPermissionException - user used to create the session lacks sufficient privileges to run the query.
EWWrongDataException - client has supplied wrong data.
EWOperationException - the operation has been blocked by an function, for example a table-level lock.
EWIntegrityException - specified table cannot be found or its primary key cannot be identified.
EWUnexpectedException - an unexpected exception has happened; the admin user should report this for investigation.
Field names are usually column labels as seen in the UI. However, DB and User column names are accepted too. Both field names and values may be surrounded by single quotes ('). If they contain spaces or some weird characters then quoting is mandatory. For example:
Example | Result |
---|---|
Priority=Low | OK |
'Priority'='Low' | OK |
Bug Priority=Low | Invalid |
'Bug Priority'=Low | OK |
'Bug Priority'=Very Low | Invalid |
'Bug Priority'='Very Low' | OK |
Simple criteria has the form of
<field name><operator><value> |
where operator is one of:
Operator | Definition |
---|---|
= | equals |
!= | not equals |
~= | contains |
!~= | doesn't contain |
>= | greater or equals |
<= | lesser or equals |
> | greater |
< | lesser |
<< | included by |
!<< | not included by |
The included/not included by operators (<<, !<<) expect a comma-separated list of values, without spaces, at the right-hand side of the equation and checks if field value is included (or not-included) in this list. In other words, Priority << High,Low is a short-hand for Priority=High || Priority=Low, where || is the OR operator, as described below.
Allows to combine other criterias using AND and OR operators. '&&' is AND, '||' is OR.
Expression is evaluated from left to right, braces may be used for grouping. For example 'A && B || C' means '(A && B) || C'.
Allows to set relative date constraints. The form is <field name><operator><mode><value>, where operator is one of =,!=,<,>,<=,>=, mode is either '-', which means 'old', '+', which means 'in the future' or '#', which means 'absolute'. 'value' is an integer followed by a single character:
m | minute |
h | hour |
w | week |
M | month |
y | year |
Examples:
Date<-1y | 'Date' is less than one year old |
Date>=+10m | 'Date' is greater or equal than 10 minutes in the future |
Duration=#2h | 'Duration' is exactly two hours |
Currently, more complex expressions like 'two years, one month and three hours' are not supported.
Advanced criteria has the form of <field name>:<from>-><to> and means 'field <field name> has changed from from to to' Either from or to – but not both at the same time – may hold '?' meaning 'any value'.
This criteria searches through record history, and thus the history column must exist and must track changes to the specified field. All simple and time-based criteria have implicit 'now' flag set, which means that they will match the current record state, not the state when advanced criteria has been satisfied. In the other words, if we have a record with the following modification history, with the bottom state being the most recent:
State=Open, Priority=Low State=Closed, Priority=Low State=Closed, Priority=High
Then 'State:Open->Closed && Priority=Low' will not find it, but 'State:Open->Closed && Priority=High' will.
Related articles |