diff --git a/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/documine.yaml b/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/documine.yaml index 66f94bd9e..5c17507fb 100644 --- a/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/documine.yaml +++ b/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/documine.yaml @@ -10,7 +10,7 @@ info: Obtain a JWT token for authentication and send it in the 'Authorization' header with the format `Bearer {JWT_TOKEN}`. Please also note that the `authorizationUrl` and `tokenUrl` in this specification contain `{workspaceId}` placeholders that - must be replaced by your respective RedactManager workspace identifier. + must be replaced by your respective DocuMine workspace identifier. Example Headers: ```properties @@ -39,9 +39,11 @@ tags: description: Operations for managing files within a dossier. - name: 4. Components description: Operations related to components of a file within a dossier. - - name: 5. Users + - name: 5. Downloads + description: Operations related to download packages. + - name: 6. Users description: Operations related to users. - - name: 6. License + - name: 7. License description: Operations related to license information and usage metrics. paths: /api/dossier-templates: @@ -560,6 +562,47 @@ paths: $ref: '#/components/responses/429' "500": $ref: '#/components/responses/500' + /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/create-download: + post: + operationId: prepareDossierDownload + tags: + - 2. Dossiers + summary: Initiate the creation of a download package for all files of a dossier. + description: | + To download files and reports, a download package needs to be prepared. This endpoint + facilitates to define the content of the download package and to start the creation of it for all + files of the dossier. The response of this endpoint contains an identifier for the download that + is needed to query the status until the download package is prepared, and finally to actually + download the file once it is available. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + - $ref: '#/components/parameters/dossierId' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DownloadRequest' + required: true + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/DownloadStatus' + description: | + Successfully started the creation of the download package for all files of the requested dossier. + "400": + $ref: '#/components/responses/400' + "401": + $ref: '#/components/responses/401' + "403": + $ref: '#/components/responses/403' + "404": + $ref: '#/components/responses/404-dossier' + "429": + $ref: '#/components/responses/429' + "500": + $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/files: get: operationId: getDossierStatus @@ -724,6 +767,48 @@ paths: $ref: '#/components/responses/429' "500": $ref: '#/components/responses/500' + /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/files/{fileId}/create-download: + post: + operationId: prepareFileDownload + tags: + - 3. Files + summary: Initiate the creation of a download package for a single file of a dossier. + description: | + To download files and reports, a download package needs to be prepared. This endpoint + facilitates to define the content of the download package and to start the creation of it for the + file. The response of this endpoint contains an identifier for the download that is needed to + query the status until the download package is prepared for download, and finally to actually + download the file once it is available. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + - $ref: '#/components/parameters/dossierId' + - $ref: '#/components/parameters/fileId' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DownloadRequest' + required: true + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/DownloadStatus' + description: | + Successfully started the creation of the download package for the requested file. + "400": + $ref: '#/components/responses/400' + "401": + $ref: '#/components/responses/401' + "403": + $ref: '#/components/responses/403' + "404": + $ref: '#/components/responses/404-file' + "429": + $ref: '#/components/responses/429' + "500": + $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/files/bulk/delete: post: operationId: deleteFiles @@ -764,6 +849,47 @@ paths: $ref: '#/components/responses/429' "500": $ref: '#/components/responses/500' + /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/files/bulk/create-download: + post: + operationId: prepareBulkDownload + tags: + - 3. Files + summary: Initiate the creation of a download package for specific files within a dossier. + description: | + To download files and reports, a download package needs to be prepared. This endpoint + facilitates to define the content of the download package and to start the creation of it for + multiple files of a dossier. The response of this endpoint contains an identifier for the download + that is needed to query the status until the download package is prepared for download, and finally + to actually download the file once it is available. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + - $ref: '#/components/parameters/dossierId' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/BulkDownloadRequest' + required: true + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/DownloadStatus' + description: | + Successfully started the creation of the download package for the requested files. + "400": + $ref: '#/components/responses/400' + "401": + $ref: '#/components/responses/401' + "403": + $ref: '#/components/responses/403' + "404": + $ref: '#/components/responses/404-dossier' + "429": + $ref: '#/components/responses/429' + "500": + $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/files/{fileId}/attributes: post: operationId: setFileAttributes @@ -881,11 +1007,131 @@ paths: $ref: '#/components/responses/429' "500": $ref: '#/components/responses/500' + /api/download: + get: + operationId: getDownloadStatusList + tags: + - 5. Downloads + summary: Get the list of downloads for the current user + description: | + This endpoint facilitates to retrieve the list of downloads for the current user. The response contains + status objects that represent each download and provide information on whether the download is still + in preparation, is already available or whether an error occurred when the download package was created. + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/DownloadStatusList' + description: List of all downloads of the current users successfully retrieved. + "400": + $ref: '#/components/responses/400' + "401": + $ref: '#/components/responses/401' + "403": + $ref: '#/components/responses/403' + "429": + $ref: '#/components/responses/429' + "500": + $ref: '#/components/responses/500' + /api/downloads/{downloadId}: + get: + operationId: getDownloadStatus + tags: + - 5. Downloads + summary: Get the status for a specific download of the current user + description: | + This endpoint facilitates to retrieve the status for a specific download. In addition to other + information, the status indicates whether the download is still being prepared, is already + available, or whether an error occurred when the download package was created. + parameters: + - $ref: '#/components/parameters/downloadId' + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/DownloadStatus' + description: Status of the download successfully retrieved. + "400": + $ref: '#/components/responses/400' + "401": + $ref: '#/components/responses/401' + "403": + $ref: '#/components/responses/403' + "404": + $ref: '#/components/responses/404-download' + "429": + $ref: '#/components/responses/429' + "500": + $ref: '#/components/responses/500' + delete: + operationId: deleteDownload + tags: + - 5. Downloads + summary: Deletes a specific download. + description: | + This endpoint facilitates the removal of a download. + parameters: + - $ref: '#/components/parameters/downloadId' + responses: + "204": + description: | + Download deletion successful. This confirms the absence of the specified download, irrespective of its previous existence. + "400": + $ref: '#/components/responses/400' + "401": + $ref: '#/components/responses/401' + "403": + $ref: '#/components/responses/403' + "404": + $ref: '#/components/responses/404-download' + "429": + $ref: '#/components/responses/429' + "500": + $ref: '#/components/responses/500' + /api/downloads/{downloadId}/download: + get: + operationId: download + tags: + - 5. Downloads + - persistence-service + summary: Download the download package. + description: | + This endpoint facilitates to actually download the created download package. The request will + only be successful if the status of the download is `READY`. + parameters: + - $ref: '#/components/parameters/downloadId' + responses: + "200": + headers: + Content-Disposition: + schema: + type: string + example: attachment; filename*=utf-8''example.zip + content: + application/octet-stream: + schema: + type: string + format: binary + description: Successfully downloaded the requested file. + "400": + $ref: '#/components/responses/400' + "401": + $ref: '#/components/responses/401' + "403": + $ref: '#/components/responses/403' + "404": + $ref: '#/components/responses/404-download' + "429": + $ref: '#/components/responses/429' + "500": + $ref: '#/components/responses/500' /api/users: get: operationId: getUsers tags: - - 5. Users + - 6. Users - tenant-user-management summary: Get a list of users description: | @@ -916,7 +1162,7 @@ paths: get: operationId: getUserById tags: - - 5. Users + - 6. Users summary: Retrieve a specific user by its identifier. description: | This endpoint facilitates to retrieve a specific user. @@ -943,7 +1189,7 @@ paths: post: operationId: getLicenseReport tags: - - 6. License + - 7. License summary: Generate and retrieve a license usage report. description: | This endpoint enables users to create and fetch a report detailing the active usage of licenses. The report contains @@ -1302,6 +1548,15 @@ components: - `true`: The component object's field `componentDetails` stores detailed information about the *source* of its respective value(s). - `false` (default): The component object does not contain a field `componentDetails`. + downloadId: + name: downloadId + in: path + required: true + schema: + type: string + style: simple + explode: false + description: The identifier for the file to download. username: name: username in: query @@ -1636,7 +1891,7 @@ components: description: | A text that can be added to provide further details about the status. E.g., what it is intended for or the circumstances under which it can be used. - example: "Dossiers with this status should only contain approved files and indicate that the users have completed the redactions." + example: "Dossiers with this status should only contain approved files and indicate that the users have completed the component extractions." rank: format: int32 type: integer @@ -2935,6 +3190,124 @@ components: $ref: '#/components/schemas/RuleValidationMessage' type: array type: object + DownloadStatus: + type: object + description: Detailed information about a specific download. + properties: + id: + type: string + format: uuid + description: The unique identifier of the download. + example: b5e2cf01-8bb6-4fcd-ad88-0efb611195da + userId: + type: string + format: uuid + description: The unique identifier of the user who initiated the download. + example: caa8b54a-eb5e-4134-8ae2-a3946a428ec7 + filename: + type: string + description: The name of the download file. + example: my-component-dossier.zip + mimeType: + type: string + description: The mime type of the download file. + example: application/octet-stream + errorCause: + type: string + description: | + If the status is `FAILED`, this field contains information about the error that happened + while preparing the download package. This information is intended to be included in a + bug report if the error occurs repeatedly and indicates a general problem with DocuMine. + example: "" + status: + type: string + enum: + - QUEUED + - GENERATING + - COMPRESSING + - READY + - FAILED + description: | + The status of the download file. In particular: + - `QUEUED` - The download job has been created and is waiting to be processed by the system. + - `GENERATING` - The system currently creates the files for the download package. + - `COMPRESSING` - The system creates a ZIP archive that will contain all files of the download package. + - `READY` - The download package is ready for download. Please note that the download will be kept only + for a certain period. This period can be configured in the settings of your DocuMine workspace. + - `FAILED` - An error occurred while preparing the download. The `errorCause` field might contain + additional details on the error. + example: READY + creationDate: + type: string + format: date-time + description: The date and time when the user initiated the download. + example: 2023-03-29T11:41:08.886Z + lastDownload: + type: string + format: date-time + description: The date and time when the user last downloaded the file. + example: 2023-03-29T13:11:05.123Z + fileSize: + type: integer + format: int64 + description: The size of the download file in bytes. + example: 1654231 + dossierId: + type: string + format: uuid + description: The identifier of the dossier to which the content of the download package belongs. + example: 20354d7a-e4fe-47af-8ff6-187bca92f3f9 + fileIds: + type: array + items: + type: string + description: The list of file identifiers to which the content of the download package belongs. + example: + - 51d3f70ac322c98dc4db70a2ac44115a + - 1fdbd888b39059c8cf171df26f62f8a5 + downloadFileTypes: + $ref: '#/components/schemas/DownloadFileTypes' + reportTemplateIds: + $ref: '#/components/schemas/ReportTemplateIdList' + DownloadStatusList: + type: object + description: Represents a list detailing the status of multiple downloads. + properties: + downloadStatus: + type: array + items: + $ref: '#/components/schemas/DownloadStatus' + description: Each item contains the status details of a download. + DownloadRequest: + type: object + description: Request payload to initiate the preparation of the download. + properties: + downloadFileTypes: + $ref: '#/components/schemas/DownloadFileTypes' + reportTemplateIds: + $ref: '#/components/schemas/ReportTemplateIdList' + redactionPreviewColor: + type: string + example: "#9398a0" + description: | + A hexadecimal color code that is used to define the highlighting color of the redaction annotations in + the `PREVIEW` file. + + - Black is `#000000` + - White is `#ffffff` + - Grey is `#cccccc` + BulkDownloadRequest: + allOf: + - $ref: '#/components/schemas/DownloadRequest' + - type: object + description: Request payload to initiate the preparation of the download of multiple files. + properties: + fileIds: + type: array + description: A list with unique identifiers of the files for which the download is to be prepared. + items: + type: string + description: The unique identifier of a file. User: type: object description: Basic information about a user. @@ -2965,7 +3338,7 @@ components: type: array description: | The roles of the user. In particular: - - `USER` - default user permission to work with RedactManager + - `USER` - default user permission to work with DocuMine - `MANAGER` - additional privileges to create and manage dossiers - `USER_ADMIN` - administration privileges limited to manage users only - `ADMIN` - general administration privileges diff --git a/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/redactmanager.yaml b/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/redactmanager.yaml index c9e09c4c7..c95c3def8 100644 --- a/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/redactmanager.yaml +++ b/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/redactmanager.yaml @@ -39,11 +39,13 @@ tags: description: Operations for managing dossiers that are based on a dossier template. - name: 3. Files description: Operations for managing files within a dossier. - - name: 4. Downloads + - name: 4. Components + description: Operations related to components of a file within a dossier. These endpoints are not available for RedactManager. + - name: 5. Downloads description: Operations related to download packages. - - name: 5. Users + - name: 6. Users description: Operations related to users. - - name: 6. License + - name: 7. License description: Operations related to license information and usage metrics. paths: /api/dossier-templates: @@ -775,7 +777,7 @@ paths: get: operationId: getDownloadStatusList tags: - - 4. Downloads + - 5. Downloads summary: Get the list of downloads for the current user description: | This endpoint facilitates to retrieve the list of downloads for the current user. The response contains @@ -802,7 +804,7 @@ paths: get: operationId: getDownloadStatus tags: - - 4. Downloads + - 5. Downloads summary: Get the status for a specific download of the current user description: | This endpoint facilitates to retrieve the status for a specific download. In addition to other @@ -832,7 +834,7 @@ paths: delete: operationId: deleteDownload tags: - - 4. Downloads + - 5. Downloads summary: Deletes a specific download. description: | This endpoint facilitates the removal of a download. @@ -858,7 +860,7 @@ paths: get: operationId: download tags: - - 4. Downloads + - 5. Downloads - persistence-service summary: Download the download package. description: | @@ -895,7 +897,7 @@ paths: get: operationId: getUsers tags: - - 5. Users + - 6. Users - tenant-user-management summary: Get a list of users description: | @@ -926,7 +928,7 @@ paths: get: operationId: getUserById tags: - - 5. Users + - 6. Users summary: Retrieve a specific user by its identifier. description: | This endpoint facilitates to retrieve a specific user. @@ -953,7 +955,7 @@ paths: post: operationId: getLicenseReport tags: - - 6. License + - 7. License summary: Generate and retrieve a license usage report. description: | This endpoint enables users to create and fetch a report detailing the active usage of licenses. The report contains