Projects Service
Projects Service🔗
The projects service allows to manage saved projects, it comes with methods to save, update, 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 not enabled 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). |
Method saveProject🔗
Method call🔗
saveProject(environment, password, user, name, externalID, shares) : saveProjectResponse
Description🔗
Saves a new project with the given name and optional external 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 |
| name | String | desired name for this search |
| externalID | String | the (optional) external project id |
| shares | Shares object | the (optional) Shares object containing sharing settings |
Returns🔗
| Result Name | Type | Description |
|---|---|---|
| saveProjectResponse | String | The projectID of the stored project |
Pre-Condition🔗
- A project with the same name for user may not exist.
- A project with the same externalID for user may not exist.
Post-Condition🔗
A project is created with the returned projectID.
Error Handling🔗
See the description of common errors as well as method-specific errors listed below:
| Error Code | Description |
|---|---|
| PROJECT_DATA_NOT_UNIQUE | The project name or external id is not unique for the given user. |
Method saveProjectWithToken🔗
Method call🔗
saveProjectWithToken(accessToken, name, externalID) : saveProjectResponse
Description🔗
Same as saveProject method but with accessToken instead of environment, password, and user.
Method updateProjectName🔗
Method call🔗
updateProjectName(environment, password, user, projectID, name) : updateProjectNameResponse
Description🔗
The projects service updates the name of the project with the given projectID if the provided user is the owner of that project.
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 |
| projectID | string | the project id |
| name | string | desired name for this search |
Returns🔗
| Result Name | Type | Description |
|---|---|---|
| updateProjectNameResponse | Integer | The new revision number of the updated project |
Pre-Condition🔗
- A project with project_id exists.
- The project with project_id is owned by user.
Post-Condition🔗
The project is renamed.
Error Handling🔗
See the description of common errors as well as method-specific errors listed below:
| Error Code | Description |
|---|---|
| PROJECT_NOT_FOUND | A project with projectID is not existing. |
| PROJECT_ACCESS_DENIED | The project with projectID is not owned by the user. |
Method updateProjectNameWithToken🔗
Method call🔗
updateProjectNameWithToken(accessToken, projectID, name) : updateProjectNameResponse
Description🔗
Same as updateProjectName method but with accessToken instead of environment, password, and user.
Method updateProjectSharing🔗
Method call🔗
updateProjectSharing(environment, password, user, projectID, shares) : updateProjectSharingResponse
Description🔗
The projects service updates the sharing attributes of the project identified by projectID. THe service checks if the given user has ownership of the project.
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 |
| projectID | String | identifier of the project |
| shares | Shares object | the Shares object containing the new sharing attributes |
Returns🔗
| Result Name | Type | Description |
|---|---|---|
| updateProjectSharingResponse | integer | The new revision number of the updated project |
Pre-Condition🔗
- A project with the given identifier exists.
- The project is owned by user.
Post-Condition🔗
The project is shared with the newly specified users.
Error Handling🔗
See the description of common errors as well as method-specific errors listed below:
| Error Code | Description |
|---|---|
| PROJECT_NOT_FOUND | A project with the given projectID does not exist. |
| PROJECT_ACCESS_DENIED | The project is not owned by the user. |
Method updateProjectSharingWithToken🔗
Method call🔗
updateProjectSharingWithToken(accessToken, projectID, shares) : updateProjectSharingResponse
Description🔗
Same as updateProjectSharing method but with accessToken instead of environment, password, and user.
Method deleteProject🔗
Method call🔗
deleteProject(environment, password, user, projectID) : deleteProjectResponse
Description🔗
The projects service deletes the project with the given projectID if the provided user is the owner of that project. All project associated saved queries and results are deleted as well. 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 |
| projectID | string | the project id |
Returns🔗
| Result Name | Type | Description |
|---|---|---|
| deleteProjectResponse | String | "OK" upon a successful task |
Pre-Condition🔗
- A project with project_id exists.
- The project with project_id is owned by user.
Post-Condition🔗
The project is removed along with all dependent Searches and Results (cascading delete).
Error Handling🔗
See the description of common errors as well as method-specific errors listed below:
| Error Code | Description |
|---|---|
| PROJECT_NOT_FOUND | A project with projectID is not existing. |
| PROJECT_ACCESS_DENIED | The project with projectID is not owned by the user. |
Method deleteProjectWithToken🔗
Method call🔗
deleteProjectWithToken(accessToken, projectID) : deleteProjectResponse
Description🔗
Same as deleteProject method but with accessToken instead of environment, password, and user.
Method deleteAllProjects🔗
Method call🔗
deleteAllProjects(environment, password, user) : deleteAllProjectsResponse
Description🔗
The projects service deletes all projects associated with the user (including his default project). All saved queries and results are deleted as well. 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 |
Returns🔗
| Result Name | Type | Description |
|---|---|---|
| deleteAllProjectsResponse | String | "OK" upon a successful task |
Pre-Condition🔗
None.
Post-Condition🔗
All of the user’s Projects (including ‘default’) and associated Searches and Results are deleted (cascading delete).
Error Handling🔗
See the description of common errors.
Method deleteAllProjectsWithToken🔗
Method call🔗
deleteAllProjectsWithToken(accessToken) : deleteAllProjectsResponse
Description🔗
Same as deleteAllProjects method but with accessToken instead of environment, password, and user.
Method listProjects🔗
Method call🔗
listProjects(environment, password, user, accessRoles) : listProjectsResponse
Description🔗
The projects service lists all projects owned by the user and shared with either the user or his role. All related saved queries and results are listed as well.
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 |
Returns🔗
| Result Name | Type | Description |
|---|---|---|
| listProjectsResponse | ProjectResponse | See description of ProjectResponse in chapter Object Structures. |
Pre-Condition🔗
None.
Post-Condition🔗
None.
Error Handling🔗
See the description of common errors.
Method listProjectsWithToken🔗
Method call🔗
listProjectsWithToken(accessToken) : listProjectsResponse
Description🔗
Same as listProjects method but with accessToken instead of environment, password, and user.
Method listUpdates🔗
Method call🔗
listUpdates(environment, password, user, roles, versions) : listVersionsResponse
Description🔗
The projects service lists all changes to the owned/shared projects, respecting the provided versions. If no changes are detected, no projects are returned. In detail, the observed changes are:
- Updates: Owned and shared projects that have a newer version.
- Additions: New projects shared with this user or created by the same user id.
- Deletions: Projects that are no longer shared with the user or no longer exist.
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 |
| versions | ProjectVersions | a map of strings to integers, mapping project IDs to their currently known project versions |
Returns🔗
| Result Name | Type | Description |
|---|---|---|
| listUpdatesResponse | ProjectResponse | See description of ProjectResponse in chapter Object Structures. |
Pre-Condition🔗
None.
Post-Condition🔗
None.
Error Handling🔗
See the description of common errors.
Method listProjectsWithToken🔗
Method call🔗
listUpdatesWithToken(accessToken, projectVersions) : listUpdatesResponse
Description🔗
Same as listUpdates method but with accessToken instead of environment, password, and user.