Save Searches Service
Save Searches Serviceπ
The save searches service allows to manage saved searches. It comes with methods to save, delete, and list them. All method are existing in two variants: one including user authentication, and another one requesting a valid access token.
All methods of this service can raise the following common errors. Method-specific errors are mentioned later. While the methods with user authentication can raise an INVALID_PASSWORD error, the versions requiring access tokens can instead return INVALID_ACCESS_TOKEN errors.
Common Error Handlingπ
Error Code | Description |
---|---|
EMPTY_ARGUMENT | One or more mandatory arguments are empty. |
METHOD_NOT_AVAILABLE | The service method is disabled in the environment configuration. |
INVALID_PASSWORD | The password is incorrect - applies only to password authentication. |
INVALID_ACCESS_TOKEN | The token is not valid (possibly timed-out) - applies only to token authentication. |
ENVIRONMENT_NOT_AVAILABLE | The environment is not available (see log-file for possible errors). |
DATABASE_ERROR | Database communication failed (possibly a misconfiguration issue). |
PROJECT_NOT_FOUND | A project with projectID is not existing. |
SAVE_SEARCH_NOT_FOUND | A saved search with provided saved search ID is not existing. |
PROJECT_ACCESS_DENIED | The project with projectID is not owned by the user. |
Method saveSearchπ
Method callπ
saveSearch(environment, password, user, accessRoles, savedSearchID, projectID, name, queryParts, synonyms, emailAlert, emailAddresses, emailUsers, emailRoles, emailProjectShares, emailEmptyResults, note, language, queryContext) : saveSearchResponse
Descriptionπ
The save searches service persists the provided search (queryParts and synonyms) with given name to the database configured for the current search environment and user. If the database contains a previously saved search with the same name, it will be overwritten. If the call includes a savedSearchID parameter, the request is interpreted as an update, and the saved search with the provided ID will be overwritten, returning a SavedSearchNotFound exception if it is not existing. It is not possible to persist a search with a customer-provided ID. This method can be called as:
Parametersπ
Parameter Name | Type | Description |
---|---|---|
environment | string | identifier of a search environment |
password | string | password for the search environment |
user | string | identifier for the current user |
accessRoles | List of Strings | access roles of the current user |
savedSearchID | string | identifier for saved search to be updated, null if persisting a new saved search. |
projectID | string | identifier for project the search belongs to, null for default project |
name | string | desired name for this search |
queryParts | list of QueryPart | all query parts of the query to be stored. Optional in case of updates. |
synonyms | map of string to list of SynonymSection | synonym map containing all offered synonyms as returned by the SearchResult. Optional in case of updates. |
emailAlert | string | Optional. Sets email alerting period. Should be one of [NEVER, DAILY, WEEKLY, MONTHLY]. |
emailAddresses | List of strings | Optional. Contains a comma-separated list of email addresses |
emailUsers | List of strings | Optional. Contains a comma-separated list of user identities |
emailRoles | List of strings | Optional. Contains a comma-separated list of role identities |
emailProjectShares | boolean | Optional. Indicates whether to send the email alert to all users and roles that the save search' project is shared with. |
emailEmptyResults | boolean | Optional. Indicates whether the emails may contain empty results |
note | string | Optional. Free-text field for notes about the saved search. |
language | string | Optional. Language code for the saved search. |
queryContext | QueryContext | Optional. Stores additional information about the query. |
Returnsπ
Result Name | Type | Description |
---|---|---|
saveSearchResponse | SavedSearch object | The stored or updated object. See description of SavedSearch in chapter Object Structures |
Pre-Conditionπ
- The saved search with savedSearchID exists if savedSearchID is given.
- The project with projectID exists if projectID is given.
- The project with projectID is either owned by or shared with the user if projectID is given.
- In order for the email alert to be sent to users, roles, and project shares, email alerting must be enabled for your environment and the Email Address Service must be implemented.
Post-Conditionπ
- The search is persisted or updated in the Search database
- If a search with the provided savedSearchID existed in the database it will be replaced.
- If a search with the same name and projectID existed in the database it will be replaced.
- If the saved search has email alerting enabled it will trigger email alerts: one email will be sent to each of the email addresses, users, and roles.
- If the given projectID is null then a βdefault projectβ is created if it does not exist.
Error Handlingπ
See the description of common errors as well as method-specific errors listed below:
Error Code | Description |
---|---|
INVALID_EMAIL_ADDRESSES | Email addresses field is not valid while emailAlert is enabled. |
SAVED_SEARCH_NAME_EXISTS | Another saved search with the same name already exists for that project. |
Method saveSearchWithTokenπ
Method callπ
saveSearchWithToken(accessToken, savedSearchID, projectID, name, queryParts, synonyms, emailAlert, emailAddresses, emailEmptyResults, note, language, queryContext) : saveSearchResponse
Descriptionπ
Same as saveSearch method but with accessToken instead of environment, password, and user.
Method deleteSearchπ
Method callπ
deleteSearch(environment, password, user, accessRoles, savedSearchID) : deleteSearchResponse
Descriptionπ
The save searches service deletes a previously saved search from the database specified by saved search ID.
Parametersπ
Parameter Name | Type | Description |
---|---|---|
environment | string | identifier of a search environment |
password | string | password for the search environment |
user | string | identifier for the current user |
accessRoles | List of Strings | access roles of the current user |
savedSearchID | string | identifier for saved search to be deleted. |
Returnsπ
Result Name | Type | Description |
---|---|---|
deleteSearchResponse | Integer | The new revision number of the affected project |
Pre-Conditionπ
- The saved search with savedSearchID exists.
- The associated project is either owned by or shared with the user.
Post-Conditionπ
Any previously saved search with the given identifier is deleted from the database.
Error Handlingπ
See the description of common errors as well as method-specific errors listed below:
Method deleteSearchWithTokenπ
Method callπ
deleteSearchWithToken(accessToken, savedSearchID) : deleteSearchResponse
Descriptionπ
Same as deleteSearch method but with accessToken instead of environment, password, and user.
Method listSearchesπ
Method callπ
listSearches(environment, password, user, accessRoles, projectID) : listSearchesResponse
Descriptionπ
The save searches service gets all previously saved searches from the database associated with the project defined by projectID. If the projectID is not specified the results of the user's default project are listed.
Parametersπ
Parameter Name | Type | Description |
---|---|---|
environment | string | identifier of a search environment |
password | string | password for the search environment |
user | string | identifier for the current user |
accessRoles | List of Strings | access roles of the current user |
projectID | string | identifier for project the search belongs to, null for default project |
Returnsπ
Result Name | Type | Description |
---|---|---|
listSearchesResponse | List of SavedSearch objects | See description of SavedSearch in chapter Object Structures |
Pre-Conditionπ
- The project with projectID exists if projectID is given.
- The project with projectID is either owned by or shared with the user if projectID is given.
- For the service to return saved searches they must have been saved to the database by the given user.
Post-Conditionπ
None.
Error Handlingπ
See the description of common errors.
Method listSearchesWithTokenπ
Method callπ
listSearchesWithToken(accessToken, projectID) : listSearchesResponse
Descriptionπ
Same as listSearches method but with accessToken instead of environment, password, and user.