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.