Save Results Service
Save Results Service🔗
The save results service allows to manage saved results. 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 disable 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 does not exist. |
| PROJECT_ACCESS_DENIED | The project with projectID is not owned by the user. |
| SEARCHER_NOT_FOUND | The searchEngine does not exist. |
| SEARCH_EXECUTION_ERROR | An error occurred while querying the search index (while retrieving metadata). |
| SEARCHER_ACCESS_DENIED | Save results enabled only for the searchers of type elasticsearch. |
Method saveResults🔗
Method call🔗
saveResults(environment, password, user, accessRoles, projectID, searchEngine, results) : saveResultsResponse
Description🔗
The save results service persists all results provided by the savedResults object. If the saveResults object contains no projectID, a default project is created for the user. 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 |
| projectID | string | identifier for the project, may be null for default project |
| searchEngine | string | the searchEngine where the results are saved to. SearchEngine must be of type elasticsearch |
| results | list of SavedResult | See description of SavedResult in chapter Object Structures |
Returns🔗
| Result Name | Type | Description |
|---|---|---|
| saveResultsResponse | Integer | The new revision number of the affected project |
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.
- SearchEngine must be of type elasticsearch.
Post-Condition🔗
- Each result is saved for the user’s project and searcher.
- The results are saved in the same order as they are in the list.
- If saved results existed with the same user’s project’s searcher’s docID their metadata is overwritten.
- 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.
Method saveResultsWithToken🔗
Method call🔗
saveResultsWithToken(accessToken, saveResults) : saveResultsResponse
Description🔗
Same as saveResults method but with accessToken instead of environment, password, and user.
Method deleteResults🔗
Method call🔗
deleteResults(environment, password, user, accessRoles, projectID, searchEngine, docIDs) : deleteResultsResponse
Description🔗
The delete results service deletes all results specified as IDs stored under the project's searchEngine. Results requested for deletion but not found in the database are ignored. No error is reported in that case. 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 |
| projectID | string | identifier for the project, may be null for default project |
| searchEngine | string | the searchEngine where the results belong to |
| docIDs | list of strings | the document IDs of results to be deleted |
Returns🔗
| Result Name | Type | Description |
|---|---|---|
| deleteResultsResponse | Integer | The new revision number of the version |
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.
Post-Condition🔗
Each saved result is deleted from the database if it exists.
Error Handling🔗
See the description of common errors.
Method deleteResultsWithToken🔗
Method call🔗
deleteResultsWithToken(accessToken, saveResults) : deleteResultsResponse
Description🔗
Same as deleteResults method but with accessToken instead of environment, password, and user.
Method listResults🔗
Method call🔗
listResults(environment, password, user, accessRoles, projectID) : listResultsResponse
Description🔗
The save results service gets all saved results from the database associated with project defined by projectID. If the projectID is not specified the results of the user's default project are listed.
The response contains only the document IDs (metadata field is empty). The retrieveMetadata service retrieves the metadata belonging to the saved results.
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 |
|---|---|---|
| listResultsResponse | SavedResults object | the saved results for each searcher. The results contain only doc ID, the metadata is empty. See description of SavedResults 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 results they must have been saved to the database by the given user.
Post-Condition🔗
None.
Error Handling🔗
See the description of common errors.
Method listResultsWithToken🔗
Method call🔗
listResultsWithToken(accessToken, projectID) : listResultsResponse
Description🔗
Same as listResults method but with accessToken instead of environment, password, and user.
Method retrieveMetadata🔗
Method call🔗
retrieveMetadata(environment, password, user, accessRoles, accessOptions, projectID, searchEngine, docIDs, language) : retrieveMetadataResponse
Description🔗
This method gets the metadata for the provided documentIDs by looking in the database and the index - except for external searchers for which only the database is queried.
As a side effect, if data from the index is different from the data in the database (and the user is owner of the project), the database will be immediately updated. If no data is found in the database, the index check is skipped and no metadata is returned. If no data is found in the index, the database value is returned.
If "deleteStale" setting is set to true and no data is found in the index, then the result is immediately removed from the database and no metadata is returned instead of returning what is found in the database.
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 the project, may be null for default project |
| searchEngine | string | the searchEngine where the results are saved to. SearchEngine must be of type elasticsearch |
| docIDs | list of strings | the document IDs of results to be deleted |
| language | string | The language of the search result translations (codes, field labels, and date strings). |
Returns🔗
| Result Name | Type | Description |
|---|---|---|
| retrieveMetadataResponse | Map of string to string | Map of documentID to saved result metadata json |
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.
Post-Condition🔗
- The metadata in the database is updated if the result is different in the index and the user owns the project.
- If the results were found in the database, but not in the index, the requesting user is the owner of the project and "deleteStale" configuration parameter is set to true, the saved results corresponding to the projectID and documentIDs are deleted from the database.
Error Handling🔗
See the description of common errors.
Method retrieveMetadataWithToken🔗
Method call🔗
retrieveMetadataWithToken(accessToken, projectID, searchEngine, docIDs, language) : retrieveMetadataResponse
Description🔗
Same as retrieveMetadata method but with accessToken instead of environment, password, user, and accessRoles.