Skip to content
Search! & Match! API
Save Searches Service
latest

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.