From 83b0616a5a4ca8be76165e2f90eeedfd53809c28 Mon Sep 17 00:00:00 2001 From: Kresnadi Budisantoso Date: Thu, 25 Apr 2024 17:03:49 +0200 Subject: [PATCH 01/11] Renamed spec file from openapi.yaml to documine.yaml --- .../src/main/resources/api/{openapi.yaml => documine.yaml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/{openapi.yaml => documine.yaml} (100%) diff --git a/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/openapi.yaml b/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/documine.yaml similarity index 100% rename from persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/openapi.yaml rename to persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/documine.yaml -- 2.47.2 From 8c7c50b89f61cfa1ccf795c2df33f48a77d6454a Mon Sep 17 00:00:00 2001 From: Kresnadi Budisantoso Date: Fri, 26 Apr 2024 23:39:32 +0200 Subject: [PATCH 02/11] RedactManager API Specs for BASF - additional endpoints --- .../src/main/resources/api/documine.yaml | 4 - .../src/main/resources/api/redactmanager.yaml | 2958 +++++++++++++++++ 2 files changed, 2958 insertions(+), 4 deletions(-) create mode 100644 persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/redactmanager.yaml 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 4ccd4fb90..8a636dacd 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 @@ -6,15 +6,11 @@ info: The DocuMine API provides a comprehensive solution for managing resources such as dossiers and their associated files. Users can also retrieve components of files that have been processed and extracted by the system. - Given that DocuMine supports multi-tenancy, it is essential to include the 'X-Tenant-ID' header with every request. - This tenant ID is referred to as the "Workspace ID" within the application. - All endpoints are secured using OAuth2, with the "authorizationCode" being the supported authorization flow. Obtain a JWT token for authentication and send it in the 'Authorization' header with the format `Bearer {JWT_TOKEN}`. Example Headers: ```properties - X-Tenant-ID: my-workspace Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI... ``` license: 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 new file mode 100644 index 000000000..cc81a88d9 --- /dev/null +++ b/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/redactmanager.yaml @@ -0,0 +1,2958 @@ +openapi: 3.0.2 +info: + title: RedactManager API + version: "4.0.0" + description: | + The RedactManager API provides a comprehensive solution for managing resources such as dossiers and their associated files. + Users can also retrieve the results package for files that have been processed by the system and reviewed by the users. + The results package can contain the optimized PDF file, the preview PDF, the redacted PDF and correlating redaction reports in different formats. + + All endpoints are secured using OAuth2, with the "authorizationCode" being the supported authorization flow. + Obtain a JWT token for authentication and send it in the 'Authorization' header with the format `Bearer {JWT_TOKEN}`. + + Example Headers: + ```properties + Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI... + ``` + license: + name: knecon License + contact: + name: knecon Service Desk + email: support@redactmanager.com + url: https://support.redactmanager.com +externalDocs: + description: Find out more about RedactManager + url: https://docs.redactmanager.com +servers: + - url: https://app.redactmanager.com + description: RedactManager Cloud Service +security: + - FF-OAUTH: [ ] +tags: + - name: 1. Dossier Templates + description: Operations related to dossier templates. + - name: 2. Dossiers + 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 + description: Operations related to download packages. + - name: 5. License + description: Operations related to license information and usage metrics. +paths: + /api/dossier-templates: + get: + operationId: getAllDossierTemplates + tags: + - 1. Dossier Templates + summary: Retrieve a list of all available dossier templates. + description: | + This endpoint provides a list of all dossier templates stored in the system. + + It returns an object containing an array of dossier template objects under the key `dossierTemplates`. + Each template object contains an identifier, a name, a dossier template status, and other fields with + further details about the template. + + Use this endpoint to fetch all templates before performing actions on specific ones. + responses: + "200": + content: + '*/*': + schema: + $ref: '#/components/schemas/DossierTemplateList' + description: | + Successfully retrieved the list of dossier templates. + + The response could be an empty list if there are no dossier templates at all. + "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/dossier-templates/{dossierTemplateId}: + get: + operationId: getDossierTemplate + tags: + - 1. Dossier Templates + summary: Retrieve a specific dossier template by its identifier. + description: | + Utilize this endpoint to retrieve comprehensive details about a designated dossier template. The response encompasses + various attributes such as the dossier template's identifier, name, status, among other pertinent details. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/DossierTemplate' + description: | + Successfully retrieved the requested dossier template. + "400": + $ref: '#/components/responses/400' + "401": + $ref: '#/components/responses/401' + "403": + $ref: '#/components/responses/403' + "404": + $ref: '#/components/responses/404-dossier-template' + "429": + $ref: '#/components/responses/429' + "500": + $ref: '#/components/responses/500' + /api/dossier-templates/{dossierTemplateId}/dossier-attribute-definitions: + get: + summary: Returns the list of all existing dossier attribute definitions + tags: + - 1. Dossier Templates + description: | + Retrieves a collection of dossier attribute definitions associated with a specific dossier template. Each dossier + attribute definition includes details such as attribute type, name, and other relevant metadata. This endpoint + is useful for clients needing to understand what attributes are expected or allowed for dossiers under a particular + dossier template. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + responses: + "200": + content: + '*/*': + schema: + $ref: '#/components/schemas/DossierAttributeDefinitionList' + description: | + Successfully returned the dossier attribute definitions for the specified dossier template. + # TODO: missing responses + /api/dossier-templates/{dossierTemplateId}/file-attribute-definitions: + get: + summary: Returns the list of all existing file attribute definitions + tags: + - 1. Dossier Templates + description: | + Retrieves a collection of file attribute definitions associated with a specific dossier template. Each file + attribute definition includes details such as attribute type, name, and other relevant metadata. This endpoint + is useful for clients needing to understand what attributes are expected or allowed for files under a particular + dossier template. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + responses: + "200": + content: + '*/*': + schema: + $ref: '#/components/schemas/FileAttributeDefinitionList' + description: | + Successfully returned the file attribute definitions for the specified dossier template. + # TODO: missing responses + /api/dossier-templates/{dossierTemplateId}/dossiers: + get: + operationId: getDossiers + tags: + - 2. Dossiers + summary: Retrieve a list of dossiers based on a specific dossier template. + description: | + By default, this endpoint provides a list of all *active* dossiers that are based on a specific dossier template. + + It returns an object containing an array of dossier objects under the key `dossiers`. Each dossier object contains + an identifier, a name, a description, an owner, and other fields with further details about the dossier. + + Use this endpoint to fetch the required dossiers before performing actions on specific ones. Use the query parameters + to modify the response. E.g., set the `includeArchivedDossiers` parameter to `true` so that the response also contains + *archived* dossiers. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + - $ref: '#/components/parameters/includeActiveDossiers' + - $ref: '#/components/parameters/includeArchivedDossiers' + - $ref: '#/components/parameters/includeSoftDeletedDossiers' + responses: + "200": + content: + '*/*': + schema: + $ref: '#/components/schemas/DossierList' + description: | + Successfully retrieved the dossiers that are based on the requested dossier template. + + The response could be an empty + list if there are no *active* dossiers based on it. If query parameters have been set, an empty list will be returned if + no dossier matches the respective combination. + "400": + $ref: '#/components/responses/400' + "401": + $ref: '#/components/responses/401' + "403": + $ref: '#/components/responses/403' + "404": + $ref: '#/components/responses/404-dossier-template' + "429": + $ref: '#/components/responses/429' + "500": + $ref: '#/components/responses/500' + post: + operationId: createOrUpdateDossier + tags: + - 2. Dossiers + summary: Creates or updates a dossier for a specific dossier template. + description: | + This endpoint is meant to create a new dossier or to update an existing one. + + To create a new dossier, do not set the identifier of the dossier object provided in the request body. + + To update an existing dossier, the set identifier needs to be valid. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DossierRequest' + required: true + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Dossier' + description: | + Successfully saved the dossier. + "201": + content: + application/json: + schema: + $ref: '#/components/schemas/Dossier' + description: | + successfully created the dossier. + "400": + $ref: '#/components/responses/400' + "401": + $ref: '#/components/responses/401' + "403": + $ref: '#/components/responses/403' + "404": + $ref: '#/components/responses/404-dossier' + "409": + $ref: '#/components/responses/409-dossier-conflict' + "429": + $ref: '#/components/responses/429' + "500": + $ref: '#/components/responses/500' + /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}: + delete: + operationId: deleteDossier + tags: + - 2. Dossiers + summary: Deletes a specific dossier by its identifier. + description: | + Removes a dossier either in a recoverable manner (soft-delete) or permanently. By default, a soft-deleted dossier + remains recoverable for a retention period determined by application settings. The default retention period is + 96 hours (4 days) but may vary based on configuration. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + - $ref: '#/components/parameters/dossierId' + - $ref: '#/components/parameters/permanentlyDeleteDossier' + responses: + "204": + description: | + Dossier deletion successful. Note that the absence of the dossier with the given `dossierId` is confirmed, + regardless of whether it was pre-existing, already removed, or never present. + "400": + $ref: '#/components/responses/400' + "401": + $ref: '#/components/responses/401' + "403": + $ref: '#/components/responses/403' + "404": + $ref: '#/components/responses/404-dossier-template' + "429": + $ref: '#/components/responses/429' + "500": + $ref: '#/components/responses/500' + get: + operationId: getDossier + tags: + - 2. Dossiers + summary: Retrieve a specific dossier by its identifier. + description: | + Utilize this endpoint to retrieve comprehensive details about a designated dossier. The response encompasses various + attributes such as the dossier's unique ID, name, description, associated owner, among other pertinent details. + + If the dossier has been soft-deleted but not yet permanently deleted, the `includeSoftDeleted` parameter can be utilized + to get it. Without this, a soft-deleted dossier would return a `404 Dossier not found` error. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + - $ref: '#/components/parameters/dossierId' + - $ref: '#/components/parameters/includeSoftDeletedDossier' + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Dossier' + description: | + Successfully retrieved 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}/attributes: + post: # TODO: review endpoint to set or update dossier attribute values + operationId: setDossierAttributes + tags: + - 2. Dossiers + summary: (DRAFT) Update or set attributes for a specific dossier. + description: | + This endpoint facilitates the updating or setting of specific dossier attributes for a given dossier. + Ensure you provide the necessary dossier attributes within the request body. + + Use this route to maintain or enhance dossier metadata and properties. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + - $ref: '#/components/parameters/dossierId' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DossierAttributes' + required: true + responses: + "200": + description: | + File attributes successfully updated. + "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}/create-download: + post: # TODO: review endpoint to prepare a download for all files of a dossier + operationId: prepareDossierDownload + tags: + - 3. Dossiers + summary: (DRAFT) Trigger the creation of a download package for all files of a dossier. + description: | + # TODO: add description for endpoint to prepare a download for all files of a dossier + 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 + tags: + - 3. Files + summary: Retrieves the status of the files of a specific dossier. + description: | + This endpoint provides status information for each file within a designated dossier. + + The file status encompasses attributes such as identifier, file name, number of pages, file size, + processing and workflow status, among other pertinent details. By default, only active files + are fetched. However, various parameters can be combined to adjust the scope of the response. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + - $ref: '#/components/parameters/dossierId' + - $ref: '#/components/parameters/includeActiveFiles' + - $ref: '#/components/parameters/includeArchivedFiles' + - $ref: '#/components/parameters/includeSoftDeletedFiles' + responses: + "200": + content: + '*/*': + schema: + $ref: '#/components/schemas/FileStatusList' + description: | + Successfully retrieved file status information. + + The response could be an empty list if the dossier contains no *active* files. If query parameters + have been set, an empty list will be returned if no file matches the respective combination. + "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' + post: + operationId: upload + tags: + - 3. Files + summary: Upload a file and associate it with a specific dossier. + description: | + This endpoint facilitates the upload of files to a specific dossier. + + Upon successful upload, the system returns the unique identifier of the uploaded file. In cases where the dossier already + contains a file with the same name, the new file will replace the existing one. + + Supported file formats include PDF documents, Microsoft Office documents (if supported by your license), CSV files, and + ZIP archives. + + Notably, Microsoft office files (file extensions `docx`, `xlsx`, or `pptx`) are automatically converted into PDF format + upon upload. Be aware that due to potential font discrepancies, the resulting PDF may slightly differ in appearance from + the original. Nevertheless, our system ensures maximum fidelity to the original content. + + CSV files offer support for bulk importing of file attributes. If the dossier is set up to map specific CSV fields to + file attributes and the uploaded CSV aligns with this mapping, the system will process the CSV accordingly. Mismatched + CSVs will be disregarded. For successfully processed CSV files, the response contains information about the file attributes + and the annotated files. + + ZIP archives offer support to upload multiple files at once. In case of an upload of a ZIP archive, the system returns a + list of unique identifiers of the contained files. The archive can even contain a mix of files like some PDF files and + a CSV file that will annotate some file attributes. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + - $ref: '#/components/parameters/dossierId' + - $ref: '#/components/parameters/keepManualChanges' + requestBody: + content: + multipart/form-data: + schema: + $ref: '#/components/schemas/UploadRequest' + responses: + "201": + content: + application/json: + schema: + $ref: '#/components/schemas/FileUploadResult' + description: | + Successfully uploaded the file. Returns an object with the unique identifier of the uploaded file, a list of unique + identifiers in case of an uploaded ZIP archive, or some annotation information in case of a successfully processing + of an uploaded CSV file. + "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}: + delete: + operationId: deleteFile + tags: + - 3. Files + summary: Deletes a specific file associated with a dossier and its template. + description: | + This endpoint facilitates the removal of a file linked to a specific dossier under a dossier template. By default, the + file undergoes a soft-delete, meaning it can be restored within the retention period determined by application settings. + The default retention period is 96 hours (4 days) but may vary based on configuration. Use the `deletePermanently` query + parameter to opt for a permanent deletion, preventing any future restoration. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + - $ref: '#/components/parameters/dossierId' + - $ref: '#/components/parameters/fileId' + - $ref: '#/components/parameters/permanentlyDeleteFile' + responses: + "204": + description: | + File deletion successful. This confirms the absence of the specified file, 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-file' + "429": + $ref: '#/components/responses/429' + "500": + $ref: '#/components/responses/500' + get: + operationId: getFileStatus + tags: + - 3. Files + summary: Retrieves the status of a particular file. + description: | + This endpoint is designed to fetch the status of a specific file associated to a dossier based on a dossier template. If + the file has been soft-deleted but not yet permanently deleted, the `includeSoftDeleted` parameter can be utilized to get + the status of such files. Without this, a soft-deleted file would return a `404 File not found` error. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + - $ref: '#/components/parameters/dossierId' + - $ref: '#/components/parameters/fileId' + - $ref: '#/components/parameters/includeSoftDeletedFile' + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/FileStatus' + description: | + Successfully retrieved the status of 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/{fileId}/create-download: + post: # TODO: review endpoint to prepare a download of a single file + operationId: prepareFileDownload + tags: + - 3. Files + summary: (DRAFT) Trigger the creation of a download package for a single file of a dossier. + description: | + # TODO: add description for endpoint to prepare a download of a single file + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + - $ref: '#/components/parameters/dossierId' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/FileDownloadRequest' + 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 + tags: + - 3. Files + summary: Bulk delete specific files within a dossier. (DELETE with body payload) + description: | + This endpoint allows for the bulk deletion of specified files associated with a certain dossier. + + It provides the flexibility to perform either a soft-delete (by default) or a permanent deletion. A soft-deleted + file remains restorable within the retention period set by the application (96h by default). In contrast, permanently + deleted files are irrevocably removed and cannot be restored. + + Use this route to manage large file deletions efficiently. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + - $ref: '#/components/parameters/dossierId' + - $ref: '#/components/parameters/permanentlyDeleteFiles' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/FileDeleteRequest' + required: true + responses: + "204": + description: | + Bulk file deletion successful. + "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/bulk/create-download: + post: # TODO: review endpoint to prepare a bulk download of multiple files + operationId: prepareBulkDownload + tags: + - 3. Files + summary: (DRAFT) Trigger the creation of a download package for specific files within a dossier. + description: | + # TODO: add description for endpoint to prepare a bulk download of multiple files + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + - $ref: '#/components/parameters/dossierId' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/BulkFileDownloadRequest' + 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 + tags: + - 3. Files + summary: Update or set attributes for a specific file. + description: | + This endpoint facilitates the updating or setting of specific file attributes for a given file within a dossier. + Ensure you provide the necessary file attributes within the request body. + + Use this route to maintain or enhance file metadata and properties. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + - $ref: '#/components/parameters/dossierId' + - $ref: '#/components/parameters/fileId' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/FileAttributes' + required: true + responses: + "200": + description: | + File attributes successfully updated. + "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/download: + get: # TODO: review endpoint to get the status of all downloads of the current user + operationId: getDownloadStatusList + tags: + - 4. Downloads + summary: TODO + description: | + # TODO: add description for endpoint to get the status of all downloads of the current user + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/DownloadStatusList' + description: TODO + "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: # TODO: review endpoint to get a single download status by id + operationId: getDownloadStatus + tags: + - 4. Downloads + summary: TODO + description: | + # TODO: add description for endpoint to get a single download status by id + parameters: + - $ref: '#/components/parameters/downloadId' + responses: + "200": # TODO: complete response + content: + application/json: + schema: + $ref: '#/components/schemas/DownloadStatus' + description: TODO + "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: # TODO: review endpoint to delete a single download by id + operationId: deleteDownload + tags: + - 4. Downloads + summary: Deletes a specific download. + description: | + This endpoint facilitates the removal of a download. + parameters: + - $ref: '#/components/parameters/downloadId' + responses: + "204": # TODO: complete response + 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: # TODO: review endpoint to actually do the download + operationId: download + tags: + - 4. Downloads + summary: TODO + description: | + # TODO: add description for endpoint to actually do the download + parameters: + - $ref: '#/components/parameters/downloadId' + responses: + "200": # TODO: complete response + description: TODO + "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: # TODO: review endpoint to get a user list + operationId: getUsers + tags: + - 5. Users + summary: TODO + description: | + # TODO: add filter parameters to find a user by login or email (optional) + responses: + 200: + content: + application/json: + schema: + $ref: '#/components/schemas/UserList' + description: TODO + "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/users/{userId}: + get: # TODO: review endpoint to get a single user by id + operationId: getUserById + tags: + - 5. Users + summary: TODO + description: | + # TODO: add description for endpoint to get a single user by id + responses: + 200: + content: + application/json: + schema: + $ref: '#/components/schemas/User' + description: TODO + "400": + $ref: '#/components/responses/400' + "401": + $ref: '#/components/responses/401' + "403": + $ref: '#/components/responses/403' + "404": + $ref: '#/components/responses/404-user' + "429": + $ref: '#/components/responses/429' + "500": + $ref: '#/components/responses/500' + /api/license/active/usage: + post: + operationId: getLicenseReport + tags: + - 6. 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 + valuable insights and metrics that can aid in monitoring and managing license consumption. Ensure your request body + contains the necessary parameters for generating this report. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LicenseReportRequest' + required: true + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/LicenseReport' + description: | + License report successfully generated and 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' +components: + headers: + X-Tenant-ID: + description: Tenant identifier, also known as the *Workspace ID* in the application. + required: true + schema: + type: string + example: 'my-workspace' + Authorization: + description: JWT token for authorization. Format should be `Bearer {JWT_TOKEN}`. + required: true + schema: + type: string + example: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI...' + responses: + "400": + content: + '*/*': + schema: + $ref: '#/components/schemas/ErrorMessage' + description: | + The request was malformed or invalid. Double-check the request structure or parameters. + "401": + content: + '*/*': + schema: + $ref: '#/components/schemas/ErrorMessage' + description: | + Unauthorized access. You must provide valid authentication credentials to access this + resource. This error can happen if the access token was revoked or has expired. + "403": + content: + '*/*': + schema: + $ref: '#/components/schemas/ErrorMessage' + description: | + Forbidden. Your credentials are valid, but you do not have permission to access this resource. + "404-dossier-template": + content: + '*/*': + schema: + $ref: '#/components/schemas/ErrorMessage' + description: | + Dossier template not found. This happens if the requested dossier template does not exist. + "404-dossier": + content: + '*/*': + schema: + $ref: '#/components/schemas/ErrorMessage' + description: | + Dossier not found. This happens if the dossier template or the dossier is deleted or did never exist. + + Some endpoints support a `includeSoftDeleted` parameter: If this is set to `true`, this response is returned + for a previously existing dossier only if it is actually deleted permanently. + "404-file": + content: + '*/*': + schema: + $ref: '#/components/schemas/ErrorMessage' + description: | + File not found. This indicates that the dossier, dossier template, or file is deleted or did never exist. + + Some endpoints support a `includeSoftDeleted` parameter: If this is set to `true`, this response is returned + only if the file is deleted permanently. + "409-dossier-conflict": + content: + '*/*': + schema: + $ref: '#/components/schemas/ErrorMessage' + description: | + Name conflict: The provided name is already in use by another dossier. It needs to be unique in the scope of your workspace. + 422-rules: + content: + '*/*': + schema: + $ref: '#/components/schemas/RuleValidation' + description: | + Invalid rules file: There were validation errors, the rules file is unprocessable. + "429": + content: + '*/*': + schema: + $ref: '#/components/schemas/ErrorMessage' + description: | + Too many requests have been made in a given time frame. Rate limiting is in place to prevent abuse. + "500": + content: + '*/*': + schema: + $ref: '#/components/schemas/ErrorMessage' + description: Internal Server Error. An unexpected error occurred on the server side. Please try again later or contact support. + parameters: + dossierTemplateId: + name: dossierTemplateId + in: path + required: true + schema: + type: string + style: simple + explode: false + description: The identifier of a dossier template + dryRun: + name: dryRun + in: query + required: false + schema: + default: false + type: boolean + style: form + explode: true + description: | + A toggle to activate the dry-run mode: If set to `false` (default), the request will update the system. + If set to `true`, the request will just be evaluated without actual changes in the system. + dossierId: + name: dossierId + in: path + required: true + schema: + type: string + style: simple + explode: false + description: The identifier of a dossier + fileId: + name: fileId + in: path + required: true + schema: + type: string + style: simple + explode: false + description: The identifier of a file + includeActiveDossiers: + name: includeActive + in: query + required: false + schema: + default: true + type: boolean + style: form + explode: true + description: | + A toggle to include or exclude active dossiers: If `true` (default), dossiers + that are neither archived nor soft-deleted are included. If `false`, they are + ignored. + includeActiveFiles: + name: includeActive + in: query + required: false + schema: + default: true + type: boolean + style: form + explode: true + description: | + A toggle to include or exclude active files: If set to `true` (default), files + that neither belong to an archived dossier nor have been soft-deleted are + included. If set to `false`, they are ignored. + includeArchivedDossiers: + name: includeArchived + in: query + required: false + schema: + default: false + type: boolean + style: form + explode: true + description: | + A toggle to include or exclude archived dossiers: If set to `true`, archived + dossiers are included. If set to `false` (default), they are ignored. + includeArchivedFiles: + name: includeArchived + in: query + required: false + schema: + default: false + type: boolean + style: form + explode: true + description: | + A toggle to include or exclude archived files (i.e., files of archived dossiers): + If set to `true`, files of archived dossiers are included. If set to `false` + (default), they are ignored. + includeSoftDeletedDossiers: + name: includeSoftDeleted + in: query + required: false + schema: + default: false + type: boolean + style: form + explode: true + description: | + A toggle to include soft-deleted dossiers: + - `true`: The response will include soft-deleted dossiers. + - `false` (default): Soft-deleted dossiers are ignored and will not be part of the response. + + Soft-deleted means that the dossier has not been deleted permanently. + includeSoftDeletedDossier: + name: includeSoftDeleted + in: query + required: false + schema: + default: false + type: boolean + style: form + explode: true + description: | + A Toggle to return a soft-deleted dossier: + - `true`: The system returns the dossier regardless whether it has been soft-deleted or not. + - `false` (default): The system returns only non-deleted dossiers. It would return a `404 Dossier not found` error + if the requested dossier has been soft-deleted. + + Soft-deleted means that the dossier has not been deleted permanently. + includeSoftDeletedFiles: + name: includeSoftDeleted + in: query + required: false + schema: + default: false + type: boolean + style: form + explode: true + description: | + A toggle to include soft-deleted files: + - `true`: The response will include soft-deleted files. + - `false` (default): Soft-deleted files are ignored and will not be part of the response. + + Soft-deleted means that the file or dossier of the file has not been deleted permanently. + includeSoftDeletedFile: + name: includeSoftDeleted + in: query + required: false + schema: + default: false + type: boolean + style: form + explode: true + description: | + A Toggle to return the status of soft-deleted files: + - `true`: The system returns the status of the file regardless whether it has been soft-deleted or not. + - `false` (default): The system returns only non-deleted files. It would return a `404 File not found` error + if the requested file has been soft-deleted. + + Soft-deleted means that the file or dossier of the file has not been deleted permanently. + permanentlyDeleteDossier: + name: deletePermanently + in: query + required: false + schema: + default: false + type: boolean + style: form + explode: true + description: | + A toggle to determine the deletion mode for a dossier: + - `true`: The dossier will be permanently deleted and can't be restored. + - `false` (default): Soft-delete, allowing restoration within the application-configured retention period. + + Using this parameter, you can also permanently delete a previously soft-deleted dossier during its retention period. + + Note: Deleting a dossier also deletes all associated files. + permanentlyDeleteFile: + name: deletePermanently + in: query + required: false + schema: + default: false + type: boolean + style: form + explode: true + description: | + Determines the deletion mode for a file. + - `true`: The file will be permanently deleted and can't be restored. + - `false` (default): Soft-delete, allowing restoration within the retention period, provided its parent dossier + hasn't been deleted. If the parent dossier has been deleted meanwhile, it needs to be restored first. + + Using this parameter, you can also permanently delete a previously soft-deleted file during its retention period. + permanentlyDeleteFiles: + name: deletePermanently + in: query + required: false + schema: + default: false + type: boolean + style: form + explode: true + description: | + Determines the deletion mode for a list of files: + - `true`: The files will be permanently deleted and can't be restored. + - `false` (default): Soft-delete, allowing restoration within the retention period, provided the files' parent dossier + hasn't been deleted. If the parent dossier has been deleted meanwhile, it needs to be restored first. + + Using this parameter, you can also permanently delete a previously soft-deleted files during their retention period. + keepManualChanges: + name: keepManualChanges + in: query + required: false + schema: + default: false + type: boolean + style: form + explode: true + description: | + A toggle to keep manual changes, i.e., to preserve manually added annotations or manipulations on existing ones when + overwriting a file: + - `true`: The system keeps the manual changes on re-uploading (overwriting) the file. + - `false` (default): Manual changes get discarded on re-uploading the file. + includeComponentDetails: + name: includeDetails + in: query + required: false + schema: + default: false + type: boolean + style: form + explode: true + description: | + A toggle to decide whether to include detailed component information in the response: + - `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`. + schemas: + EntityReference: + type: object + description: | + Represents a reference to an entity object discovered in a document. Together with the unique identifier + of the entity, the reference contains some basic details of the entity. + properties: + id: + type: string + description: | + The unique identifier for the entity. + + Note: In general, it is a valid UUID. Only if an entity spans over multiple pages, it is split on page breaks. Each + part becomes an own entity object and the first one keeps the UUID while the following get an additional suffix. + + Example: Even is `bcd22239-c3df-442f-a5a1-1664cba94dc6_2` is not a valid UUID it is still a valid identifier for an + entity object. + entityRuleId: + type: string + description: An identifier that represents a specific rule associated with the entity. + type: + type: string + description: The name of the entity. + page: + type: integer + format: int32 + description: The page number in the document where the entity is located. + example: + id: bcd22239-cedf-442f-a5a1-1664cba94dc6 + entityRuleId: ABC.0.0 + type: entity_type + page: 123 + Component: + type: object + description: Represents a component with its associated values. + properties: + name: + type: string + description: The name of the component. + componentValues: + type: array + description: A list of value objects associated with the component. + items: + $ref: '#/components/schemas/ComponentValue' + example: + name: the component name + componentValues: + - value: my overwritten component value + originalValue: the original value + componentRuleId: COM.0.0 + valueDescription: My value description + entityReferences: + - id: bcd22239-cedf-442f-a5a1-1664cba94dc6 + entityRuleId: ABC.0.0 + type: entity_type + page: 123 + - id: bcd22239-c3df-442f-a5a1-1664cba94dc6_2 + entityRuleId: ABC.0.0 + type: entity_type + page: 124 + - id: b748b89a-5679-4254-9286-1dd652d9970b + entityRuleId: DEF.13.37 + type: another_entity_type + page: 456 + - value: yet another component value + originalValue: yet another component value + componentRuleId: COM.0.1 + valueDescription: Another value description + entityReferences: + - id: 70496456-a016-4679-81b1-6c8856dded6e + entityRuleId: XYZ.0.0 + type: yet_another_entity_type + page: 123 + ComponentValue: + type: object + description: Describes a value associated with a component, including its origin and related entities found in the document. + properties: + value: + type: string + description: The current value of the component. + originalValue: + type: string + description: The original value before any modifications. + componentRuleId: + type: string + description: Identifier for the rule associated with this component value. + valueDescription: + type: string + description: A brief description of the value. + entityReferences: + items: + $ref: '#/components/schemas/EntityReference' + type: array + example: + value: my overwritten component value + originalValue: the original value + componentRuleId: COM.0.0 + valueDescription: My value description + entityReferences: + - id: bcd22239-cedf-442f-a5a1-1664cba94dc6 + entityRuleId: ABC.0.0 + type: entity_type + page: 123 + - id: b748b89a-5679-4254-9286-1dd652d9970b + entityRuleId: DEF.13.37 + type: another_entity_type + page: 456 + FileComponents: + type: object + description: Represents file details along with its associated components and values. + properties: + dossierTemplateId: + format: uuid + type: string + description: Identifier for the template associated with the dossier. + dossierId: + format: uuid + type: string + description: Identifier for the dossier. + fileId: + type: string + description: Identifier for the file. + filename: + type: string + description: Name of the file. + components: + type: object + description: A map of component names to their list of values. + additionalProperties: + items: + type: string + type: array + componentDetails: + type: object + description: A map of component names to their detailed representations. + additionalProperties: + $ref: '#/components/schemas/Component' + example: + dossierTemplateId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91 + dossierId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91 + fileId: 1fdbd888b39059c8cf171df26f62f8a5 + filename: MyFile.pdf + components: + "my component": + - my overwritten component value + - yet another component value + "yet another component": + - only one value + componentDetails: + - name: my component + componentValues: + - value: my overwritten component value + originalValue: the original value + componentRuleId: COM.0.0 + valueDescription: My value description + entityReferences: + - id: bcd22239-cedf-442f-a5a1-1664cba94dc6 + entityRuleId: ABC.0.0 + type: entity_type + page: 123 + - id: b748b89a-5679-4254-9286-1dd652d9970b + entityRuleId: DEF.13.37 + type: another_entity_type + page: 456 + - value: yet another component value + originalValue: yet another component value + componentRuleId: COM.0.1 + valueDescription: Another value description + entityReferences: + - id: 70496456-a016-4679-81b1-6c8856dded6e + entityRuleId: XYZ.0.0 + type: yet_another_entity_type + page: 123 + - name: yet another component + componentValues: + - value: only one value + originalValue: only one value + componentRuleId: COM.0.0 + valueDescription: My value description + entityReferences: + - id: bcd22239-cedf-442f-a5a1-1664cba94dc6 + entityRuleId: ABC.0.0 + type: entity_type + page: 123 + - id: b748b89a-5679-4254-9286-1dd652d9970b + entityRuleId: DEF.13.37 + type: another_entity_type + page: 456 + FileComponentsList: + type: object + description: A list of files and their associated components. + properties: + files: + type: array + description: List of files with their component details. + items: + $ref: '#/components/schemas/FileComponents' + example: + files: + - dossierTemplateId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91 + dossierId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91 + fileId: 1fdbd888b39059c8cf171df26f62f8a5 + filename: MyFile.pdf + components: + "my component": + - my overwritten component value + - yet another component value + "yet another component": + - only one value + componentDetails: + - name: my component + componentValues: + - value: my overwritten component value + originalValue: the original value + componentRuleId: COM.0.0 + valueDescription: My value description + entityReferences: + - id: bcd22239-cedf-442f-a5a1-1664cba94dc6 + entityRuleId: ABC.0.0 + type: entity_type + page: 123 + - id: b748b89a-5679-4254-9286-1dd652d9970b + entityRuleId: DEF.13.37 + type: another_entity_type + page: 456 + - value: yet another component value + originalValue: yet another component value + componentRuleId: COM.0.1 + valueDescription: Another value description + entityReferences: + - id: 70496456-a016-4679-81b1-6c8856dded6e + entityRuleId: XYZ.0.0 + type: yet_another_entity_type + page: 123 + - name: yet another component + componentValues: + - value: only one value + originalValue: only one value + componentRuleId: COM.0.0 + valueDescription: My value description + entityReferences: + - id: bcd22239-cedf-442f-a5a1-1664cba94dc6 + entityRuleId: ABC.0.0 + type: entity_type + page: 123 + - id: b748b89a-5679-4254-9286-1dd652d9970b + entityRuleId: DEF.13.37 + type: another_entity_type + page: 456 + - dossierTemplateId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91 + dossierId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91 + fileId: 4d2334def5fced0003888e47cbc270f7 + filename: Copy of MyFile.pdf + components: + "my component": + - my overwritten component value + - yet another component value + "yet another component": + - only one value + componentDetails: + - name: my component + componentValues: + - value: my overwritten component value + originalValue: the original value + componentRuleId: COM.0.0 + valueDescription: My value description + entityReferences: + - id: dadb54d4-587b-4e69-8c07-be9446a33537 + entityRuleId: ABC.0.0 + type: entity_type + page: 123 + - id: 30339f5a-4c19-447f-b0a0-0f14c094037e + entityRuleId: DEF.13.37 + type: another_entity_type + page: 456 + - value: yet another component value + originalValue: yet another component value + componentRuleId: COM.0.1 + valueDescription: Another value description + entityReferences: + - id: 086cd500-97da-44f8-8628-3324d11b4e8d + entityRuleId: XYZ.0.0 + type: yet_another_entity_type + page: 123 + - name: yet another component + componentValues: + - value: only one value + originalValue: only one value + componentRuleId: COM.0.0 + valueDescription: My value description + entityReferences: + - id: dadb54d4-587b-4e69-8c07-be9446a33537 + entityRuleId: ABC.0.0 + type: entity_type + page: 123 + - id: 30339f5a-4c19-447f-b0a0-0f14c094037e + entityRuleId: DEF.13.37 + type: another_entity_type + page: 456 + DossierAttributeDefinition: + type: object + description: | + The `DossierAttributeDefinition` object contains the relevant information to define a dossier attribute. Dossier attributes + are used to manage additional meta-data of dossiers. + properties: + id: + type: string + format: uuid + description: | + A unique identifier for the dossier attribute definition. This ID is automatically generated by + the system upon creation and is used for referencing the dossier attribute definition in API calls. + name: + type: string + description: | + User-defined name of the dossier attribute definition, capturing its essence. The name needs to be unique + for the dossier template. + type: + type: string + enum: + - TEXT + - NUMBER + - DATE + description: | + Determines the type of the dossier attribute's value. Please note that currently the system + does not validate the values against this definition. This is just a hint for a user interface + that needs to handle invalid entries. Possible values for the type: + - `TEXT`: The value is just a string, i.e., any sequence of characters. + - `NUMBER`: The value is a string expressing a number, with or without decimals. + - `DATE`: The value is a string expressing a date information. + reportingPlaceholder: + type: string + description: | + The name of the placeholder of the dossier attribute that can be used in report templates. The + placeholder follows a specific format convention: + `{{dossier.attribute.}}` while the name is transformed into 'PascalCase' and does not contain + whitespaces. The placeholder is unique in a dossier template. + required: + - name + - type + example: + id: "123e4567-e89b-12d3-a456-426614174000" + name: "Document Summary" + type: "TEXT" + reportingPlaceholder: "{{dossier.attribute.DocumentSummary}}" + FileAttributeDefinition: + type: object + description: | + The `FileAttributeDefinition` object contains the relevant information to define a file attribute. File attributes + are used to manage additional meta-data of files. + properties: + id: + type: string + format: uuid + description: | + A unique identifier for the file attribute definition. This ID is automatically generated by + the system upon creation and is used for referencing the file attribute definition in API calls. + name: + type: string + description: | + User-defined name of the file attribute definition, capturing its essence. The name needs to be unique + for the dossier template. + type: + type: string + enum: + - TEXT + - NUMBER + - DATE + description: | + Determines the type of the file attribute's value. Please note that currently the system + does not validate the values against this definition. This is just a hint for a user interface + that needs to handle invalid entries. Possible values for the type: + - `TEXT`: The value is just a string, i.e., any sequence of characters. + - `NUMBER`: The value is a string expressing a number, with or without decimals. + - `DATE`: The value is a string expressing a date information. + mappedCsvColumnHeader: + type: string + description: | + The name of a CSV column. When importing a CSV file with additional file information the system gets the value from the respective CSV column. + reportingPlaceholder: + type: string + description: | + The name of the placeholder of the file attribute that can be used in report templates. The placeholder follows a specific format convention: + `{{file.attribute.}}` while the name is transformed into 'PascalCase' and does not contain whitespaces. The placeholder is unique in a dossier template. + displaySettings: + $ref: '#/components/schemas/FileAttributeDisplaySettings' + required: + - name + - type + example: + id: "123e4567-e89b-12d3-a456-426614174000" + name: "Document Type" + type: "TEXT" + mappedCsvColumnHeader: "DocumentCategory" + reportingPlaceholder: "{{file.attribute.DocumentType}}" + displaySettings: + primaryAttribute: true + editable: true + filterable: true + displayedInFileList: false + FileAttributeDisplaySettings: + type: object + description: | + Display setting for the RedactManager user interface. These settings control how the UI handles and presents the file attributes. + properties: + primaryAttribute: + type: boolean + description: | + If `true`, the RedactManager user interfaces show the value of the file attribute in the file list below the file name. + editable: + type: boolean + description: | + If `true`, the RedactManager user interfaces allow manual editing of the value. Otherwise only importing and setting by rules would be possible. + filterable: + type: boolean + description: | + If `true`, the RedactManager user interfaces add filter options to the file list. + displayedInFileList: + type: boolean + description: | + if `true`, the RedactManager user interfaces show the values in the file list. + required: + - primaryAttribute + - editable + - filterable + - displayedInFileList + example: + primaryAttribute: false + editable: true + filterable: true + displayedInFileList: false + DossierAttributeDefinitionList: + type: object + description: A list of dossier attribute definitions. + properties: + dossierAttributeDefinitions: + items: + $ref: '#/components/schemas/DossierAttributeDefinition' + type: array + example: + dossierAttributeDefinitions: + - id: "123e4567-e89b-12d3-a456-426614174000" + name: "Dossier Summary" + type: "TEXT" + reportingPlaceholder: "{{dossier.attribute.DossierSummary}}" + - id: "23e45678-e90b-12d3-a456-765114174321" + name: "Comment" + type: "TEXT" + reportingPlaceholder: "{{dossier.attribute.Comment}}" + FileAttributeDefinitionList: + type: object + description: A list of file attribute definitions. + properties: + csvImportSettings: + $ref: '#/components/schemas/CsvImportSettings' + fileAttributeDefinitions: + items: + $ref: '#/components/schemas/FileAttributeDefinition' + type: array + example: + csvImportSettings: + csvMappingActive: true + filenameMappingCsvColumnHeader: "Filename" + delimiter: "," + encoding: "UTF-8" + fileAttributeDefinitions: + - id: "123e4567-e89b-12d3-a456-426614174000" + name: "Document Type" + type: "TEXT" + mappedCsvColumnHeader: "DocumentCategory" + reportingPlaceholder: "{{file.attribute.DocumentType}}" + displaySettings: + primaryAttribute: true + editable: true + filterable: true + displayedInFileList: false + - id: "23e45678-e90b-12d3-a456-765114174321" + name: "Comment" + type: "TEXT" + reportingPlaceholder: "{{file.attribute.Comment}}" + displaySettings: + primaryAttribute: false + editable: true + filterable: false + displayedInFileList: false + CsvImportSettings: + type: object + description: | + This object defines the settings for importing data from a CSV file. It includes + information that indicates if the CSV mapping is active, specifies the column header + used for filename matching, sets the delimiter for column separation, and determines + the encoding of the CSV file. These settings are crucial for accurately importing and + mapping file attributes based on the corresponding CSV records. + properties: + csvMappingActive: + type: boolean + description: | + If `true`, the CSV mapping is active. + filenameMappingCsvColumnHeader: + type: string + description: | + The header of a specific column in the CSV file that should contain values + matching the filenames. A matching value identifies the record that is used + to import the mapped file attributes. + delimiter: + type: string + maxLength: 1 + description: | + The delimiter of the CSV file that is used to distinguish different columns. + encoding: + type: string + description: | + The encoding of the CSV file that is expected when uploading for the import of file attributes. + example: + csvMappingActive: true + filenameMappingCsvColumnHeader: "Filename" + delimiter: "," + encoding: "UTF-8" + DossierAttributes: + type: object + description: (DRAFT) Additional dossier attributes that can be set + properties: + attributeIdToValue: + additionalProperties: + type: string + type: object + example: + myDossierAttribute: This is a file attribute value + yetAnotherDossierAttribute: This is yet another file attribute value + numericValuesNeedToBeStrings: "1234" + myDossierDate: "1. January 1337" + Dossier: + type: object + description: | + The `Dossier` object captures all relevant information related to a specific dossier. A dossier is a collection + of documents, managed and analyzed based on settings and rules of the `DossierTemplate` it is derived from. + properties: + id: + type: string + format: uuid + description: | + A unique identifier for the dossier. This ID is automatically generated by + the system upon creation and is used for referencing the dossier in API calls. + name: + type: string + description: | + User-defined name of the dossier, capturing its essence. The name needs to be unique + for the entire workspace (i.e., tenant). + date: + type: string + format: date-time + description: | + The date when the dossier was created. This is automatically set by the system upon the dossier's creation. + dossierTemplateId: + type: string + format: uuid + description: The unique identifier for the template that governs the settings and rules for this dossier. + description: + type: string + description: A detailed narrative explaining the purpose and contents of the dossier. + ownerId: + type: string + format: uuid + description: | + The identifier of the user or entity responsible for the dossier. Typically, + this is the creator or main contact point for the dossier. Only users with "Manager" + privileges can create dossiers and become dossier owners. + memberIds: + type: array + items: + type: string + format: uuid + uniqueItems: true + description: List of unique user identifiers associated with this dossier, such as contributors or viewers. + approverIds: + type: array + items: + type: string + format: uuid + uniqueItems: true + description: | + List of unique user identifiers with elevated permissions. Needed if using an approval workflow. + visibility: + type: string + enum: + - PRIVATE + - PUBLIC + description: | + Determines who can see the dossier. Possible values include: + - `PRIVATE`: Visible to dossier members only. + - `PUBLIC`: Visible to all users. + + The system sets the value based on the permissions defined in the application. + startDate: + type: string + format: date-time + description: The starting date for the lifecycle of this dossier. + dueDate: + type: string + format: date-time + description: The end date or deadline for actions related to this dossier. + dossierStatusId: + type: string + format: uuid + description: The unique identifier of the current status of the dossier. The status definitions are managed in the dossier template. + watermarkId: + type: string + format: uuid + deprecated: true + description: | + Identifier for the watermark that's to be applied on redacted documents within this dossier. + previewWatermarkId: + type: string + format: uuid + deprecated: true + description: | + Identifier for the watermark pattern used for generated previews documents within this dossier. + dossierAttributes: + $ref: '#/components/schemas/DossierAttributes' + downloadFileTypes: + $ref: '#/components/schemas/DownloadFileTypes' + reportTemplateIds: + type: array + items: + type: string + format: uuid + uniqueItems: true + description: | + List of template identifiers indicating which templates are to be used for generating reports or outputs + for this dossier. The reports are generated when requesting a download package. + archivedTime: + type: string + format: date-time + description: The date and time when the dossier was archived. Archived dossiers are read-only and cannot be modified. + softDeletedTime: + type: string + format: date-time + description: | + The timestamp indicating when the dossier was softly deleted, i.e., hidden from + most users but not completely removed from the system. `null` if not deleted. + + A soft-deleted dossier can be restored within a retention period configured in the application. + hardDeletedTime: + type: string + format: date-time + description: The timestamp indicating when the dossier was permanently removed from the system. `null` if not deleted. + example: + id: 2ef05d6a-6fb3-4f27-b3c7-9a6438b38c3b + name: Project Alpha + date: 2000-01-23T04:56:07.000+00:00 + dossierTemplateId: 1ed2db85-9cd5-48b0-855f-77ca2a688501 + description: Collection of documents for Project Alpha. + ownerId: a0044ae9-ddca-4f97-b0a1-3cb2517dbf39 + memberIds: + - da8d5f98-ae61-4696-85bf-27986d93877c + - f4a0beb4-4034-4b92-a75e-5f37591326ea + approverIds: + - da8d5f98-ae61-4696-85bf-27986d93877c + - f4a0beb4-4034-4b92-a75e-5f37591326ea + visibility: PRIVATE + startDate: null + dueDate: 2001-01-23T04:56:07.000+00:00 + dossierStatusId: b8280985-f558-43c0-852a-a3fa86803548 + watermarkId: null + previewWatermarkId: null + downloadFileTypes: + - ORIGINAL + - PREVIEW + reportTemplateIds: + - daadea5f-917b-482a-b7d2-e65afe8f80ca + - 8130acf6-4910-4123-827c-caacd8111402 + archivedTime: null + softDeletedTime: null + hardDeletedTime: null + DossierList: + type: object + description: A list of dossiers. + properties: + dossiers: + items: + $ref: '#/components/schemas/Dossier' + type: array + example: + dossiers: + - id: 2ef05d6a-6fb3-4f27-b3c7-9a6438b38c3b + name: Project Alpha + date: 2000-01-23T04:56:07.000+00:00 + dossierTemplateId: 1ed2db85-9cd5-48b0-855f-77ca2a688501 + description: Collection of documents for Project Alpha. + ownerId: a0044ae9-ddca-4f97-b0a1-3cb2517dbf39 + memberIds: + - da8d5f98-ae61-4696-85bf-27986d93877c + - f4a0beb4-4034-4b92-a75e-5f37591326ea + approverIds: + - da8d5f98-ae61-4696-85bf-27986d93877c + - f4a0beb4-4034-4b92-a75e-5f37591326ea + visibility: PUBLIC + startDate: null + dueDate: 2001-01-23T04:56:07.000+00:00 + dossierStatusId: b8280985-f558-43c0-852a-a3fa86803548 + watermarkId: null + previewWatermarkId: null + downloadFileTypes: + - ORIGINAL + - PREVIEW + reportTemplateIds: + - daadea5f-917b-482a-b7d2-e65afe8f80ca + - 8130acf6-4910-4123-827c-caacd8111402 + archivedTime: null + softDeletedTime: null + hardDeletedTime: null + - id: dc28cc82-2682-4b7f-ae0b-2132b205d47a + name: Project Beta + date: 2001-01-23T04:56:07.000+00:00 + dossierTemplateId: 1ed2db85-9cd5-48b0-855f-77ca2a688501 + description: Collection of documents for Project Beta. + ownerId: 0d53a7c3-7b3a-4c57-857d-ec5e0fc3019b + memberIds: + - a0044ae9-ddca-4f97-b0a1-3cb2517dbf39 + - c2e33246-e50a-4c43-831c-6789a5637db8 + - 6123fa16-6943-4b74-8524-54b0046a0ce6 + visibility: PUBLIC + startDate: null + dueDate: 2001-01-23T04:56:07.000+00:00 + dossierStatusId: b8280985-f558-43c0-852a-a3fa86803548 + watermarkId: null + previewWatermarkId: null + downloadFileTypes: + - ORIGINAL + - PREVIEW + reportTemplateIds: + - daadea5f-917b-482a-b7d2-e65afe8f80ca + - 8130acf6-4910-4123-827c-caacd8111402 + archivedTime: null + softDeletedTime: null + hardDeletedTime: null + DossierRequest: + type: object + description: | + Object containing essential attributes for creating or updating a dossier. + Includes information about ownership, members, approvers, and various configurations + like watermarks and download file types. + properties: + id: + type: string + format: uuid + description: | + The unique identifier of the dossier to update. This property needs to be null for create requests, + as the system will generate it automatically. If the value is not a valid identifier, the + endpoint will return a `400 Bad request` error. + name: + type: string + description: | + A human-readable name for the dossier. The name must be unique among all dossiers + within the scope of the workspace (tenant). + description: + type: string + description: | + A textual description providing additional context or information + about the purpose and content of the dossier. + dueDate: + type: string + format: date-time + description: | + Specifies the deadline by which actions related to this dossier should be completed. + The date is in ISO 8601 date-time format. + ownerId: + type: string + format: uuid + description: | + A unique identifier representing the user who owns or created this dossier. + If `null` when creating the dossier, the current user will be set as the owner. + Must not be `null` when updating a dossier. + memberIds: + type: array + description: An array of unique identifiers for users who have access to the dossier. + items: + type: string + description: A unique identifier for a member with access to the dossier. + uniqueItems: true + reportTemplateIds: + type: array + description: | + An array of identifiers representing templates used for generating reports + or exports from this dossier. + items: + description: An identifier for a report template. + type: string + uniqueItems: true + dossierStatusId: + type: string + description: | + An identifier representing the current status of the dossier. + Use `null` to unset the current status. + required: + - name + example: + id: dc28cc82-2682-4b7f-ae0b-2132b205d47a + name: Project Beta + description: Collection of documents for Project Beta. + dueDate: 2001-01-23T04:56:07.000+00:00 + ownerId: 0d53a7c3-7b3a-4c57-857d-ec5e0fc3019b + memberIds: + - a0044ae9-ddca-4f97-b0a1-3cb2517dbf39 + - c2e33246-e50a-4c43-831c-6789a5637db8 + - 6123fa16-6943-4b74-8524-54b0046a0ce6 + reportTemplateIds: + - daadea5f-917b-482a-b7d2-e65afe8f80ca + - 8130acf6-4910-4123-827c-caacd8111402 + dossierStatusId: b8280985-f558-43c0-852a-a3fa86803548 + DossierTemplate: + description: | + The `DossierTemplate` object represents the blueprint for creating and + managing dossiers and for handling and analyzing the files of dossiers. + It contains various settings, rules, and metadata to control the behavior + of individual dossiers that get created based on this template. + example: + id: 1e07cde0-d36a-4ab7-b389-494ca694a0cb + name: RedactManager Example + description: Typical settings for RedactManager. + dateAdded: 2020-01-23T04:56:07.000+00:00 + dateModified: 2021-01-23T04:56:07.000+00:00 + createdBy: c2e33246-e50a-4c43-831c-6789a5637db6 + modifiedBy: c2e33246-e50a-4c43-831c-6789a5637db6 + validFrom: 2020-01-01T00:00:00.000+00:00 + validTo: 2030-12-31T23:59:59.999+00:00 + dossierTemplateStatus: ACTIVE + removeWatermark: false + keepImageMetadata: false + ocrByDefault: false + keepHiddenText: false + keepOverlappingObjects: false + applyDictionaryUpdatesToAllDossiersByDefault: false + downloadFileTypes: + - PREVIEW + - REDACTED + properties: + id: + description: | + A unique identifier generated by the system when the dossier template + is created. This ID is used to reference the template in API calls. + type: string + format: uuid + name: + description: The user-defined name of the dossier template, required for create and update operations. + type: string + description: + description: A detailed description of the purpose and usage of this dossier template. + type: string + dateAdded: + description: The date when this dossier template was first created. Automatically set by the system. + format: date-time + type: string + dateModified: + description: | + The most recent date when modifications were made to this dossier template. + Automatically set by the system. + format: date-time + type: string + createdBy: + description: The identifier of the user who initially created this dossier template. Automatically set by the system. + type: string + format: uuid + modifiedBy: + description: The identifier of the user who last modified this dossier template. Automatically set by the system. + type: string + format: uuid + validFrom: + description: | + The starting date for the validity of this dossier template. Dossiers can only be created + based on this template after this date. + format: date-time + type: string + validTo: + description: | + The ending date for the validity of this dossier template. Dossiers will no longer be able to + be created based on this template after this date. + format: date-time + type: string + downloadFileTypes: + $ref: '#/components/schemas/DownloadFileTypes' + status: + description: | + Indicates the current status of the dossier template: + * `INCOMPLETE`: The dossier template is missing some information or settings. Dossiers cannot be created based + on this template until the missing information and settings are added. + * `INACTIVE`: The dossier template cannot be used for creating dossiers based on it. + * `ACTIVE`: The dossier template can be used for creating dossiers based on it. + enum: + - INCOMPLETE + - INACTIVE + - ACTIVE + type: string + keepImageMetadata: + description: Flag indicating whether metadata from images in PDFs should be retained or removed. + type: boolean + keepHiddenText: + description: Flag indicating whether hidden text in PDFs should be retained or removed. + type: boolean + keepOverlappingObjects: + description: Flag indicating whether overlapping objects in PDFs should be retained or flattened. + type: boolean + applyDictionaryUpdatesToAllDossiersByDefault: + description: | + Flag indicating whether updates to the dictionary should automatically be applied to all dossiers + created from this template. + type: boolean + ocrByDefault: + description: Flag specifying if OCR should be automatically applied to PDFs that get upload to dossiers based on this template. + type: boolean + removeWatermark: + description: Flag specifying if the system should try to remove watermarks in documents prior to OCR processing. + type: boolean + type: object + DownloadFileTypes: + type: array + uniqueItems: true + description: | + Specifies the types of files that will part of the created download package. The defaults can be defined in the dossier template + and can be overwritten individually on each download. + + RedactManager supports `ORIGINAL`, `PREVIEW`, `DELTA_PREVIEW`, and `REDACTED`: + + - `ORIGINAL` Contrary to intuition, this is not the uploaded file, but the pre-processed, + optimized PDF, which may also contain the OCR results. + This is the PDF that used by the system for further processing. + - `PREVIEW` The annotated version of the PDF indicating what gets redacted by the + system. Note that the content to redact is actually still present and readable. + The redaction information is embedded so you can restore the redactions when uploading the + `PREVIEW` PDF into RedactManager. + - `DELTA_PREVIEW` Shows changes if redactions were imported (e.g., by uploading a Preview PDF + with redaction annotations): + Unchanged imported redactions are highlighted in green, removed imported redactions are + highlighted in red, changed imported redactions (e.g. resized) are highlighted in yellow, + and additional redactions are highlighted in blue. + - `REDACTED` The ISO27038 compliant sanitized PDF file that contains all redactions. + items: + enum: + - ORIGINAL + - PREVIEW + - DELTA_PREVIEW + - REDACTED + type: string + DossierTemplateList: + description: Represents a list of dossier templates, each encapsulating a set of rules and settings. + example: + dossierTemplates: + - id: 1e07cde0-d36a-4ab7-b389-494ca694a0cb + name: RedactManager Example + description: Typical settings for RedactManager. + dateAdded: 2020-01-23T04:56:07.000+00:00 + dateModified: 2021-01-23T04:56:07.000+00:00 + createdBy: c2e33246-e50a-4c43-831c-6789a5637db6 + modifiedBy: c2e33246-e50a-4c43-831c-6789a5637db6 + validFrom: 2020-01-01T00:00:00.000+00:00 + validTo: 2030-12-31T23:59:59.999+00:00 + dossierTemplateStatus: ACTIVE + removeWatermark: false + keepImageMetadata: false + ocrByDefault: false + keepHiddenText: false + keepOverlappingObjects: false + applyDictionaryUpdatesToAllDossiersByDefault: false + downloadFileTypes: + - PREVIEW + - REDACTED + - id: 8d8cae48-5c33-4617-ac27-1643f29b79d8 + name: RedactManager Example + description: Typical settings for RedactManager. + dateAdded: 2023-09-01T06:54:32.000+00:00 + dateModified: 2023-09-01T06:54:32.000+00:00 + createdBy: 46a7f9d3-6ba0-41d7-b312-b8e708aa6f4d + modifiedBy: 46a7f9d3-6ba0-41d7-b312-b8e708aa6f4d + validFrom: 2023-01-01T00:00:00.000+00:00 + validTo: 2033-12-31T23:59:59.999+00:00 + dossierTemplateStatus: ACTIVE + removeWatermark: true + keepImageMetadata: true + ocrByDefault: true + keepHiddenText: true + keepOverlappingObjects: true + applyDictionaryUpdatesToAllDossiersByDefault: false + downloadFileTypes: + - ORIGINAL + properties: + dossierTemplates: + description: Each entry is a dossier template with its details. + items: + $ref: '#/components/schemas/DossierTemplate' + type: array + type: object + ErrorMessage: + type: object + description: | + Represents an error message returned by the API, providing details on when the error occurred + and a description of the issue. + properties: + timestamp: + type: string + format: date-time + description: The exact date and time when the error was encountered. This can be useful for logging or troubleshooting. + message: + type: string + description: A detailed description of the error, providing insights on the problem and potentially how to resolve or avoid it. + example: + timestamp: "2023-09-21T12:45:00Z" + message: "An error occurred while processing the request." + FileAttributes: + type: object + description: Additional file attributes that can be set or imported + properties: + attributeIdToValue: + additionalProperties: + type: string + type: object + example: + myFileAttribute: This is a file attribute value + yetAnotherFileAttribute: This is yet another file attribute value + numericValuesNeedToBeStrings: "1234" + myFileDate: "1. January 1337" + FileDeleteRequest: + type: object + description: Request payload to initiate the deletion of specific files. + properties: + fileIds: + type: array + description: A list of unique identifiers for the files to be deleted. + items: + type: string + description: The unique identifier of a file. + example: + fileIds: + - 51d3f70ac322c98dc4db70a2ac44115a + - 1fdbd888b39059c8cf171df26f62f8a5 + FileErrorInfo: + type: object + description: Detailed information about an error encountered with a file. + properties: + cause: + type: string + description: The underlying reason or cause of the error. + queue: + type: string + description: The queue or process where the error was encountered. + service: + type: string + description: The specific service or component that reported the error. + timestamp: + type: string + format: date-time + description: The exact time when the error was recorded. + example: + service: LayoutParsingService + cause: The reason or cause why something went wrong. + queue: LAYOUT_PARSING_REQUEST_QUEUE + timestamp: 2000-01-23T04:56:07.000+00:00 + FileStatus: + type: object + description: Object containing information on a specific file. + properties: + id: + type: string + description: The unique identifier of the file. + dossierId: + type: string + format: uuid + description: The unique identifier linking the file to its associated dossier. + dossierTemplateId: + type: string + format: uuid + description: The identifier of the dossier template of the file's dossier. + dossierStatusId: + type: string + format: uuid + description: The identifier of the dossier status of the file's dossier. + filename: + description: The file's name. + type: string + dossierArchived: + description: Tells if the dossier of this file is archived or not. + type: boolean + processingStatus: + type: string + enum: + - ANALYSE + - ERROR + - FULLREPROCESS + - IMAGE_ANALYZING + - INDEXING + - NER_ANALYZING + - OCR_PROCESSING_QUEUED + - OCR_PROCESSING + - PROCESSED + - PROCESSING + - REPROCESS + - UNPROCESSED + - FULL_PROCESSING + - PRE_PROCESSING_QUEUED + - PRE_PROCESSING + - PRE_PROCESSED + - FIGURE_DETECTION_ANALYZING + - TABLE_PARSING_ANALYZING + description: | + The processing status of a file. The states give detailed information about the current processing step. + In general, this information is useful for debugging is the file is stuck in a status. + + The status `UNPROCESSED` indicates a newly uploaded file. Status `ERROR` indicates that the system could not + process the file for some reason. Finally, `PROCESSED` is what you usually expect as the final state after + all required processing steps are done. + workflowStatus: + type: string + enum: + - NEW + - UNDER_REVIEW + - UNDER_APPROVAL + - APPROVED + description: | + The workflow status of a file. + + - `NEW` - Initial status of the uploaded files. + - `UNDER_REVIEW` - The redactions of the document are under review. In this status, users can make corrections + and add redactions. + - `UNDER_APPROVAL` - The redactions have been reviewed and the document is ready for final approval. With this additional status, + a four-eyes-principle can be applied. However, users can still make final corrections and add redactions before + approving the file. + - `APPROVED` - Files have been reviewed and finally approved. Redactions of files in this final state are no longer modified by the + system's automatic analysis and are also read-only for users. I.e., the files must be returned to a previous status to make + changes to the redactions. + numberOfPages: + description: The number of pages of the file. + format: int32 + type: integer + added: + description: Date and time when the file was added to the system. + format: date-time + type: string + lastUpdated: + description: Date and time when the file was last updated. + format: date-time + type: string + numberOfAnalyses: + description: The number of times the file has been analyzed. + format: int32 + type: integer + assignee: + description: The current assignee's (if any) user id. + type: string + lastReviewer: + description: The last reviewer's (if any) user id. + type: string + lastApprover: + description: The user id of the last approver (if any). + type: string + hasRedactions: + description: Shows if any redactions were found during the analysis. + type: boolean + hasHints: + description: Shows if any hints were found during the analysis. + type: boolean + hasRequests: + description: Shows if any requests were found during the analysis. + type: boolean + hasUpdates: + description: | + Shows if there is any change between the previous and current + analysis. + type: boolean + hasImages: + description: Shows if any images were found during the analysis. + type: boolean + ocrStartTime: + description: | + Shows if this file has been OCRed by us. Start time of OCR + Process + format: date-time + type: string + numberOfPagesToOCR: + description: Number of pages to be OCRed by us + format: int32 + type: integer + numberOfOCRedPages: + description: Number of pages already OCRed by us + format: int32 + type: integer + ocrEndTime: + description: Shows if this file has been OCRed by us. End time of OCR Process + format: date-time + type: string + hasAnnotationComments: + description: Shows if this file has comments on annotations. + type: boolean + uploader: + description: The ID of the user who uploaded the file. + type: string + dictionaryVersion: + description: Shows which dictionary versions was used during the analysis. + format: int64 + type: integer + rulesVersion: + description: Shows which rules versions was used during the analysis. + format: int64 + type: integer + legalBasisVersion: + description: Shows which legal basis versions was used during the analysis. + format: int64 + type: integer + excluded: + description: Shows if the file was excluded from analysis. + type: boolean + lastProcessed: + description: Shows the last date of a successful analysis. + format: date-time + type: string + lastLayoutProcessed: + description: Shows the last date of a layout parsing. + format: date-time + type: string + approvalDate: + description: Shows the date of approval, if approved. + format: date-time + type: string + lastUploaded: + description: Shows last date the document was uploaded. + format: date-time + type: string + analysisDuration: + description: Shows how long the last analysis took + format: int64 + type: integer + fileAttributes: + $ref: '#/components/schemas/FileAttributes' + dossierDictionaryVersion: + description: | + Shows which dossier dictionary versions was used during the + analysis. + format: int64 + type: integer + analysisRequired: + description: Shows if the file requires reanalysis. + type: boolean + excludedPages: + description: Set of excluded pages for this file. + items: + description: Set of excluded pages for this file. + format: int32 + type: integer + type: array + uniqueItems: true + softDeletedTime: + description: Shows if the file is soft deleted. + format: date-time + type: string + lastFileAttributeChange: + description: Date and time when the files attributes was last updated. + format: date-time + type: string + hasSuggestions: + description: Shows if there are any Suggestions in this file. + type: boolean + excludedFromAutomaticAnalysis: + description: Shows if the file is excluded from automatic analysis. + type: boolean + redactionModificationDate: + description: Shows the last redaction modification date of this file. + format: date-time + type: string + fileManipulationDate: + description: Shows the date of the last manipulation of this file. + format: date-time + type: string + lastManualChangeDate: + description: | + Shows the date of the last manual change of an annotation of + this file. + format: date-time + type: string + hasHighlights: + description: | + Shows if there are highlights to remove or convert for this + file. + type: boolean + fileSize: + description: Size of the optimized, internally stored file. + format: int64 + type: integer + analysisVersion: + description: Analysis Version. + format: int32 + type: integer + lastIndexed: + description: Last time the file was indexed in ES. + format: date-time + type: string + fileErrorInfo: + $ref: '#/components/schemas/FileErrorInfo' + lastOCRTime: + description: Shows if this file has been OCRed by us. Last Time of OCR. + format: date-time + type: string + example: + hasRedactions: true + added: 2000-01-23T04:56:07.000+00:00 + workflowStatus: NEW + hasAnnotationComments: true + rulesVersion: 2 + excluded: true + lastUpdated: 2000-01-23T04:56:07.000+00:00 + lastManualChangeDate: 2000-01-23T04:56:07.000+00:00 + lastProcessed: 2000-01-23T04:56:07.000+00:00 + excludedFromAutomaticAnalysis: true + dictionaryVersion: 5 + dossierArchived: true + hasRequests: true + lastFileAttributeChange: 2000-01-23T04:56:07.000+00:00 + id: a7f0303d-a33c-4f2e-bd7a-a2adc1b8f92b + analysisDuration: 9 + hasHighlights: true + dossierStatusId: dossierStatusId + fileErrorInfo: + service: service + cause: cause + queue: queue + timestamp: 2000-01-23T04:56:07.000+00:00 + processingStatus: ANALYSE + numberOfAnalyses: 6 + filename: filename + fileAttributes: + myFileAttribute: This is a file attribute value + yetAnotherFileAttribute: This is yet another file attribute value + numericValuesNeedToBeStrings: "1234" + lastOCRTime: 2000-01-23T04:56:07.000+00:00 + legalBasisVersion: 7 + excludedPages: + - 2 + - 2 + redactionModificationDate: 2000-01-23T04:56:07.000+00:00 + fileSize: 4 + fileManipulationDate: 2000-01-23T04:56:07.000+00:00 + dossierId: dossierId + lastUploaded: 2000-01-23T04:56:07.000+00:00 + assignee: assignee + analysisRequired: true + approvalDate: 2000-01-23T04:56:07.000+00:00 + numberOfPagesToOCR: 1 + ocrEndTime: 2000-01-23T04:56:07.000+00:00 + hasHints: true + softDeletedTime: 2000-01-23T04:56:07.000+00:00 + numberOfPages: 0 + uploader: uploader + lastReviewer: lastReviewer + lastIndexed: 2000-01-23T04:56:07.000+00:00 + numberOfOCRedPages: 5 + analysisVersion: 7 + lastLayoutProcessed: 2000-01-23T04:56:07.000+00:00 + lastApprover: lastApprover + ocrStartTime: 2000-01-23T04:56:07.000+00:00 + dossierDictionaryVersion: 3 + dossierTemplateId: dossierTemplateId + hasImages: true + hasUpdates: true + hasSuggestions: true + FileStatusList: + type: object + description: Represents a list detailing the status of a bunch of files. + properties: + files: + type: array + description: An array of status details for each individual file. + items: + $ref: '#/components/schemas/FileStatus' + example: + files: + - hasRedactions: true + added: 2000-01-23T04:56:07.000+00:00 + workflowStatus: NEW + hasAnnotationComments: true + rulesVersion: 2 + excluded: true + lastUpdated: 2000-01-23T04:56:07.000+00:00 + lastManualChangeDate: 2000-01-23T04:56:07.000+00:00 + lastProcessed: 2000-01-23T04:56:07.000+00:00 + excludedFromAutomaticAnalysis: true + dictionaryVersion: 5 + dossierArchived: true + hasRequests: true + lastFileAttributeChange: 2000-01-23T04:56:07.000+00:00 + id: id + analysisDuration: 9 + hasHighlights: true + dossierStatusId: dossierStatusId + fileErrorInfo: + service: service + cause: cause + queue: queue + timestamp: 2000-01-23T04:56:07.000+00:00 + processingStatus: ANALYSE + numberOfAnalyses: 6 + filename: filename + fileAttributes: + myFileAttribute: This is a file attribute value + yetAnotherFileAttribute: This is yet another file attribute value + numericValuesNeedToBeStrings: "1234" + lastOCRTime: 2000-01-23T04:56:07.000+00:00 + legalBasisVersion: 7 + excludedPages: + - 2 + - 2 + redactionModificationDate: 2000-01-23T04:56:07.000+00:00 + fileSize: 4 + fileManipulationDate: 2000-01-23T04:56:07.000+00:00 + dossierId: 15849e05-5414-498c-b48b-47afa3fd74da + lastUploaded: 2000-01-23T04:56:07.000+00:00 + assignee: assignee + fileId: 4d2334def5fced0003888e47cbc270f7 + analysisRequired: true + approvalDate: 2000-01-23T04:56:07.000+00:00 + numberOfPagesToOCR: 1 + ocrEndTime: 2000-01-23T04:56:07.000+00:00 + hasHints: true + softDeletedTime: 2000-01-23T04:56:07.000+00:00 + numberOfPages: 0 + uploader: uploader + lastReviewer: lastReviewer + lastIndexed: 2000-01-23T04:56:07.000+00:00 + numberOfOCRedPages: 5 + analysisVersion: 7 + lastLayoutProcessed: 2000-01-23T04:56:07.000+00:00 + lastApprover: lastApprover + ocrStartTime: 2000-01-23T04:56:07.000+00:00 + dossierDictionaryVersion: 3 + dossierTemplateId: dossierTemplateId + hasImages: true + hasUpdates: true + hasSuggestions: true + - hasRedactions: true + added: 2000-01-23T04:56:07.000+00:00 + workflowStatus: NEW + hasAnnotationComments: true + rulesVersion: 2 + excluded: true + lastUpdated: 2000-01-23T04:56:07.000+00:00 + lastManualChangeDate: 2000-01-23T04:56:07.000+00:00 + lastProcessed: 2000-01-23T04:56:07.000+00:00 + excludedFromAutomaticAnalysis: true + dictionaryVersion: 5 + dossierArchived: true + hasRequests: true + lastFileAttributeChange: 2000-01-23T04:56:07.000+00:00 + id: id + analysisDuration: 9 + hasHighlights: true + dossierStatusId: dossierStatusId + fileErrorInfo: + service: service + cause: cause + queue: queue + timestamp: 2000-01-23T04:56:07.000+00:00 + processingStatus: ANALYSE + numberOfAnalyses: 6 + filename: filename + fileAttributes: + myFileAttribute: This is a file attribute value + yetAnotherFileAttribute: This is yet another file attribute value + numericValuesNeedToBeStrings: "1234" + lastOCRTime: 2000-01-23T04:56:07.000+00:00 + legalBasisVersion: 7 + excludedPages: + - 2 + - 2 + redactionModificationDate: 2000-01-23T04:56:07.000+00:00 + fileSize: 4 + fileManipulationDate: 2000-01-23T04:56:07.000+00:00 + dossierId: dossierId + lastUploaded: 2000-01-23T04:56:07.000+00:00 + assignee: assignee + fileId: 1fdbd888b39059c8cf171df26f62f8a5 + analysisRequired: true + approvalDate: 2000-01-23T04:56:07.000+00:00 + numberOfPagesToOCR: 1 + ocrEndTime: 2000-01-23T04:56:07.000+00:00 + hasHints: true + softDeletedTime: 2000-01-23T04:56:07.000+00:00 + numberOfPages: 0 + uploader: uploader + lastReviewer: lastReviewer + lastIndexed: 2000-01-23T04:56:07.000+00:00 + numberOfOCRedPages: 5 + analysisVersion: 7 + lastLayoutProcessed: 2000-01-23T04:56:07.000+00:00 + lastApprover: lastApprover + ocrStartTime: 2000-01-23T04:56:07.000+00:00 + dossierDictionaryVersion: 3 + dossierTemplateId: dossierTemplateId + hasImages: true + hasUpdates: true + hasSuggestions: true + FileUploadResult: + description: Object containing information about a successfully uploaded file. + example: + fileIds: + - fileIds + - fileIds + processedFileIds: + - processedFileIds + - processedFileIds + processedAttributes: + - processedAttributes + - processedAttributes + properties: + fileIds: + description: List of fileIds generated for uploaded file(s). + items: + description: List of fileIds generated for uploaded file(s). + type: string + type: array + processedAttributes: + description: | + List processed file attributes, in case the upload contained + a CSV. + items: + description: | + List processed file attributes, in case the upload contained + a CSV. + type: string + type: array + processedFileIds: + description: List processed fileIds, in case the upload contained a CSV. + items: + description: List processed fileIds, in case the upload contained a CSV. + type: string + type: array + type: object + RuleValidationMessage: + description: Object containing information about an uploaded rules file. + example: + line: 123 + column: 45 + message: "Unable to Analyse Expression ..." + properties: + line: + description: The line number where the error or warning occurs. + format: int32 + type: integer + column: + description: The column number where the error or warning occurs. + format: int32 + type: integer + message: + description: The error or warning message that describes the details. + type: string + type: object + RuleValidation: + description: | + Information about the uploaded rules file. The `error` field is empty if there were no validation errors in the uploaded rules file. + example: + errors: + - line: 123 + column: 45 + message: "Unable to Analyse Expression ..." + - line: 234 + column: 5 + message: "Invalid rule syntax ..." + properties: + errors: + description: List of errors found in the uploaded rules file. + items: + $ref: '#/components/schemas/RuleValidationMessage' + type: array + type: object + LicenseReport: + type: object + description: A comprehensive report of licensing metrics and usage statistics. + properties: + startDate: + type: string + format: date-time + description: The starting date of the report. + endDate: + type: string + format: date-time + description: The ending date of the report. + numberOfAnalyzedFiles: + type: integer + format: int32 + description: | + The count of files that have been analyzed in the requested period. The counter is + increased only once for each file, regardless of the number of analysis. + numberOfAnalyzedPages: + type: integer + format: int32 + description: | + The count of pages that have been analyzed in the requested period. The counter is + increased only once for each file, regardless of the number of analysis. + analyzedFilesBytes: + type: integer + format: int64 + description: | + The size in bytes of the files that have been analyzed in the requested period. + The counter is increased only once for each file, regardless of the number of analysis. + totalFilesUploadedBytes: + type: integer + format: int64 + description: The total size in bytes of all present files at the end of the period. + activeFilesUploadedBytes: + type: integer + format: int64 + description: The size in bytes of all active files at the end of the period. + trashFilesUploadedBytes: + type: integer + format: int64 + description: The size in bytes of all soft-deleted files at the end of the period. + archivedFilesUploadedBytes: + type: integer + format: int64 + description: The size in bytes of all archived files at the end of the period. + numberOfOcrFiles: + type: integer + format: int32 + description: | + The count of files that have undergone OCR (Optical Character Recognition) in the + requested period. + numberOfOcrPages: + type: integer + format: int32 + description: The count of pages that have undergone OCR in the requested period. + numberOfDossiers: + type: integer + format: int32 + description: The total number of present dossiers at the end of the period. + monthlyData: + description: A list of data metrics categorized on a monthly basis. + items: + $ref: '#/components/schemas/MonthlyReportData' + type: array + example: + startDate: 2000-01-01T00:00:00.000+00:00 + endDate: 2001-01-01T00:00:00.000+00:00 + numberOfAnalyzedFiles: 5 + numberOfAnalyzedPages: 9 + analyzedFilesBytes: 30000 + totalFilesUploadedBytes: 30000 + activeFilesUploadedBytes: 20000 + archivedFilesUploadedBytes: 5000 + trashFilesUploadedBytes: 5000 + numberOfOcrFiles: 2 + numberOfOcrPages: 2 + numberOfDossiers: 1 + monthlyData: + - startDate: 2000-01-01T00:00:00.000+00:00 + endDate: 2000-02-01T00:00:00.000+00:00 + numberOfAnalyzedPages: 7 + analyzedFilesBytes: 25000 + totalFilesUploadedBytes: 25000 + activeFilesUploadedBytes: 22000 + archivedFilesUploadedBytes: 0 + trashFilesUploadedBytes: 3000 + numberOfOcrPages: 1 + - startDate: 2000-02-01T00:00:00.000+00:00 + endDate: 2000-03-01T00:00:00.000+00:00 + numberOfAnalyzedPages: 2 + analyzedFilesBytes: 5000 + totalFilesUploadedBytes: 30000 + activeFilesUploadedBytes: 20000 + archivedFilesUploadedBytes: 5000 + trashFilesUploadedBytes: 5000 + numberOfOcrPages: 1 + LicenseReportRequest: + type: object + description: Request object to retrieve a license report for a given date range. + properties: + startDate: + type: string + format: date-time + description: The start date for the requested report. + endDate: + type: string + format: date-time + description: The end date for the requested report. + example: + startDate: 2000-01-01T00:00:00.000+00:00 + endDate: 2001-01-01T00:00:00.000+00:00 + MonthlyReportData: + type: object + description: Detailed metrics regarding license usage for a given month. + properties: + startDate: + type: string + format: date-time + description: The starting date of the respective month. + endDate: + type: string + format: date-time + description: The ending date of the respective month. + numberOfAnalyzedPages: + type: integer + format: int32 + description: | + The count of pages that have been analyzed in the respective month. The counter is + increased only once for each file, regardless of the number of analysis. + analyzedFilesBytes: + type: integer + format: int64 + description: | + The size in bytes of the files that have been analyzed in the respective month. + The counter is increased only once for each file, regardless of the number of analysis. + totalFilesUploadedBytes: + type: integer + format: int64 + description: The total size in bytes of all present files at the end of the respective month. + activeFilesUploadedBytes: + type: integer + format: int64 + description: The size in bytes of all active files at the end of the respective month. + trashFilesUploadedBytes: + type: integer + format: int64 + description: The size in bytes of all soft-deleted files at the end of the respective month. + archivedFilesUploadedBytes: + type: integer + format: int64 + description: The size in bytes of all archived files at the end of the respective month. + numberOfOcrPages: + type: integer + format: int32 + description: The count of pages that have undergone OCR in the requested respective month. + example: + startDate: 2000-01-01T00:00:00.000+00:00 + endDate: 2000-02-01T00:00:00.000+00:00 + numberOfAnalyzedPages: 7 + analyzedFilesBytes: 25000 + totalFilesUploadedBytes: 25000 + activeFilesUploadedBytes: 22000 + archivedFilesUploadedBytes: 0 + trashFilesUploadedBytes: 3000 + numberOfOcrPages: 1 + UploadRequest: + type: object + description: Request object to upload a file. + properties: + file: + type: string + format: binary + description: The binary content of the file to be uploaded. + required: + - file + securitySchemes: + FF-OAUTH: + flows: + authorizationCode: + authorizationUrl: /auth/realms/redaction/protocol/openid-connect/auth + scopes: { } + tokenUrl: /auth/realms/redaction/protocol/openid-connect/token + type: oauth2 -- 2.47.2 From c431f9884221c4e6093594b686a47c10f7253235 Mon Sep 17 00:00:00 2001 From: Kresnadi Budisantoso Date: Sun, 28 Apr 2024 15:36:46 +0200 Subject: [PATCH 03/11] RedactManager API Specs for BASF - added some descriptions for download creation --- .../src/main/resources/api/redactmanager.yaml | 54 ++++++++++++++++--- 1 file changed, 47 insertions(+), 7 deletions(-) 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 cc81a88d9..30da534ed 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 @@ -106,7 +106,7 @@ paths: "500": $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossier-attribute-definitions: - get: + get: # TODO: review endpoint to get dossier attribute definitions summary: Returns the list of all existing dossier attribute definitions tags: - 1. Dossier Templates @@ -125,9 +125,20 @@ paths: $ref: '#/components/schemas/DossierAttributeDefinitionList' description: | Successfully returned the dossier attribute definitions for the specified dossier template. - # TODO: missing responses + "400": + $ref: '#/components/responses/400' + "401": + $ref: '#/components/responses/401' + "403": + $ref: '#/components/responses/403' + "404": + $ref: '#/components/responses/404-dossier-template' + "429": + $ref: '#/components/responses/429' + "500": + $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/file-attribute-definitions: - get: + get: # TODO: review endpoint to get file attribute definitions summary: Returns the list of all existing file attribute definitions tags: - 1. Dossier Templates @@ -146,7 +157,18 @@ paths: $ref: '#/components/schemas/FileAttributeDefinitionList' description: | Successfully returned the file attribute definitions for the specified dossier template. - # TODO: missing responses + "400": + $ref: '#/components/responses/400' + "401": + $ref: '#/components/responses/401' + "403": + $ref: '#/components/responses/403' + "404": + $ref: '#/components/responses/404-dossier-template' + "429": + $ref: '#/components/responses/429' + "500": + $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossiers: get: operationId: getDossiers @@ -348,7 +370,13 @@ paths: - 3. Dossiers summary: (DRAFT) Trigger the creation of a download package for all files of a dossier. description: | - # TODO: add description for endpoint to prepare a download for all files of a dossier + To download the results of a redaction, 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 for download, and + finally to actually download the file once it is available. + + Note: The redacted file will be created for `APPROVED` files only. parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/dossierId' @@ -549,7 +577,13 @@ paths: - 3. Files summary: (DRAFT) Trigger the creation of a download package for a single file of a dossier. description: | - # TODO: add description for endpoint to prepare a download of a single file + To download the results of a redaction, 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. + + Note: The redacted PDF will be created for `APPROVED` files only. parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/dossierId' @@ -626,7 +660,13 @@ paths: - 3. Files summary: (DRAFT) Trigger the creation of a download package for specific files within a dossier. description: | - # TODO: add description for endpoint to prepare a bulk download of multiple files + To download the results of a redaction, 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. + + Note: The redacted PDF will be created for `APPROVED` files only. parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/dossierId' -- 2.47.2 From 224def920ef203c5694a77b4d324e90b7272ab4f Mon Sep 17 00:00:00 2001 From: Kresnadi Budisantoso Date: Sun, 28 Apr 2024 15:47:12 +0200 Subject: [PATCH 04/11] RedactManager API Specs for BASF - removed X-tenant-ID header and added some description --- .../src/main/resources/api/redactmanager.yaml | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) 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 30da534ed..135dde0ed 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 @@ -747,7 +747,7 @@ paths: application/json: schema: $ref: '#/components/schemas/DownloadStatusList' - description: TODO + description: List of all downloads of the current users successfully retrieved. "400": $ref: '#/components/responses/400' "401": @@ -774,7 +774,7 @@ paths: application/json: schema: $ref: '#/components/schemas/DownloadStatus' - description: TODO + description: Status of the download successfully retrieved. "400": $ref: '#/components/responses/400' "401": @@ -824,7 +824,7 @@ paths: - $ref: '#/components/parameters/downloadId' responses: "200": # TODO: complete response - description: TODO + description: Successfully downloading the file. (TODO rephrase?) "400": $ref: '#/components/responses/400' "401": @@ -851,7 +851,7 @@ paths: application/json: schema: $ref: '#/components/schemas/UserList' - description: TODO + description: List of users successfully retrieved. "400": $ref: '#/components/responses/400' "401": @@ -876,7 +876,7 @@ paths: application/json: schema: $ref: '#/components/schemas/User' - description: TODO + description: User successfully retrieved. "400": $ref: '#/components/responses/400' "401": @@ -925,12 +925,6 @@ paths: $ref: '#/components/responses/500' components: headers: - X-Tenant-ID: - description: Tenant identifier, also known as the *Workspace ID* in the application. - required: true - schema: - type: string - example: 'my-workspace' Authorization: description: JWT token for authorization. Format should be `Bearer {JWT_TOKEN}`. required: true -- 2.47.2 From a2daa60e7978971411db53d3a1f172f4cc41f37d Mon Sep 17 00:00:00 2001 From: Kresnadi Budisantoso Date: Mon, 29 Apr 2024 17:20:04 +0200 Subject: [PATCH 05/11] RedactManager API Specs for BASF - designed all required endpoints --- .../src/main/resources/api/redactmanager.yaml | 602 +++++++++--------- 1 file changed, 301 insertions(+), 301 deletions(-) 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 135dde0ed..d910e2a15 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 @@ -1,14 +1,18 @@ openapi: 3.0.2 info: - title: RedactManager API - version: "4.0.0" + title: RedactManager API - DRAFT + version: "4.1.0" description: | The RedactManager API provides a comprehensive solution for managing resources such as dossiers and their associated files. Users can also retrieve the results package for files that have been processed by the system and reviewed by the users. - The results package can contain the optimized PDF file, the preview PDF, the redacted PDF and correlating redaction reports in different formats. + The results package can contain the optimized PDF file, the preview PDF, the redacted PDF and correlating redaction reports + in different formats. - All endpoints are secured using OAuth2, with the "authorizationCode" being the supported authorization flow. + All endpoints are secured using OAuth2, with the "authorizationCode" being the general supported authorization flow. 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. Example Headers: ```properties @@ -27,7 +31,7 @@ servers: - url: https://app.redactmanager.com description: RedactManager Cloud Service security: - - FF-OAUTH: [ ] + - FF-OAUTH: [] tags: - name: 1. Dossier Templates description: Operations related to dossier templates. @@ -37,7 +41,9 @@ tags: description: Operations for managing files within a dossier. - name: 4. Downloads description: Operations related to download packages. - - name: 5. License + - name: 5. Users + description: Operations related to users. + - name: 6. License description: Operations related to license information and usage metrics. paths: /api/dossier-templates: @@ -106,7 +112,7 @@ paths: "500": $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossier-attribute-definitions: - get: # TODO: review endpoint to get dossier attribute definitions + get: # TODO: implement endpoint to get dossier attribute definitions summary: Returns the list of all existing dossier attribute definitions tags: - 1. Dossier Templates @@ -138,7 +144,7 @@ paths: "500": $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/file-attribute-definitions: - get: # TODO: review endpoint to get file attribute definitions + get: summary: Returns the list of all existing file attribute definitions tags: - 1. Dossier Templates @@ -328,7 +334,7 @@ paths: "500": $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/attributes: - post: # TODO: review endpoint to set or update dossier attribute values + post: # TODO: implement endpoint to set or update dossier attribute values operationId: setDossierAttributes tags: - 2. Dossiers @@ -348,9 +354,9 @@ paths: $ref: '#/components/schemas/DossierAttributes' required: true responses: - "200": + "204": description: | - File attributes successfully updated. + Dossier attributes successfully updated. "400": $ref: '#/components/responses/400' "401": @@ -364,17 +370,17 @@ paths: "500": $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/create-download: - post: # TODO: review endpoint to prepare a download for all files of a dossier + post: # TODO: implement endpoint to prepare a download for all files of a dossier operationId: prepareDossierDownload tags: - - 3. Dossiers + - 2. Dossiers summary: (DRAFT) Trigger the creation of a download package for all files of a dossier. description: | To download the results of a redaction, 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 for download, and - finally to actually download the file once it is available. + is needed to query the status until the download package is prepared, and finally to actually + download the file once it is available. Note: The redacted file will be created for `APPROVED` files only. parameters: @@ -571,7 +577,7 @@ paths: "500": $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/files/{fileId}/create-download: - post: # TODO: review endpoint to prepare a download of a single file + post: # TODO: implement endpoint to prepare a download of a single file operationId: prepareFileDownload tags: - 3. Files @@ -587,11 +593,12 @@ paths: parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/dossierId' + - $ref: '#/components/parameters/fileId' requestBody: content: application/json: schema: - $ref: '#/components/schemas/FileDownloadRequest' + $ref: '#/components/schemas/DownloadRequest' required: true responses: "200": @@ -654,7 +661,7 @@ paths: "500": $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/files/bulk/create-download: - post: # TODO: review endpoint to prepare a bulk download of multiple files + post: # TODO: implement endpoint to prepare a bulk download of multiple files, check if fileIds match the dossierId operationId: prepareBulkDownload tags: - 3. Files @@ -674,7 +681,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/BulkFileDownloadRequest' + $ref: '#/components/schemas/BulkDownloadRequest' required: true responses: "200": @@ -718,7 +725,7 @@ paths: $ref: '#/components/schemas/FileAttributes' required: true responses: - "200": + "204": description: | File attributes successfully updated. "400": @@ -734,13 +741,15 @@ paths: "500": $ref: '#/components/responses/500' /api/download: - get: # TODO: review endpoint to get the status of all downloads of the current user + get: # TODO: implement endpoint to get the status of all downloads of the current user operationId: getDownloadStatusList tags: - 4. Downloads - summary: TODO + summary: Get the list of downloads for the current user description: | - # TODO: add description for endpoint to get the status of all downloads of the current user + 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: @@ -759,17 +768,19 @@ paths: "500": $ref: '#/components/responses/500' /api/downloads/{downloadId}: - get: # TODO: review endpoint to get a single download status by id + get: # TODO: implement endpoint to get a single download status by id operationId: getDownloadStatus tags: - 4. Downloads - summary: TODO + summary: Get the status for a specific download of the current user description: | - # TODO: add description for endpoint to get a single download status by id + 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": # TODO: complete response + "200": content: application/json: schema: @@ -787,7 +798,7 @@ paths: $ref: '#/components/responses/429' "500": $ref: '#/components/responses/500' - delete: # TODO: review endpoint to delete a single download by id + delete: # TODO: implement endpoint to delete a single download by id operationId: deleteDownload tags: - 4. Downloads @@ -797,7 +808,7 @@ paths: parameters: - $ref: '#/components/parameters/downloadId' responses: - "204": # TODO: complete response + "204": description: | Download deletion successful. This confirms the absence of the specified download, irrespective of its previous existence. "400": @@ -813,18 +824,30 @@ paths: "500": $ref: '#/components/responses/500' /api/downloads/{downloadId}/download: - get: # TODO: review endpoint to actually do the download + get: # TODO: implement endpoint to actually do the download operationId: download tags: - 4. Downloads - summary: TODO + - persistence-service + summary: Download the download package. description: | - # TODO: add description for endpoint to actually do the download + 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": # TODO: complete response - description: Successfully downloading the file. (TODO rephrase?) + "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": @@ -837,14 +860,20 @@ paths: $ref: '#/components/responses/429' "500": $ref: '#/components/responses/500' - /api/users: - get: # TODO: review endpoint to get a user list + /api/users: # /api/users?username=kresnadi@budisantoso.de + get: # TODO: implement endpoint to get a user list operationId: getUsers tags: - 5. Users + - tenant-user-management summary: TODO description: | - # TODO: add filter parameters to find a user by login or email (optional) + This endpoint facilitates to retrieve a list of known users. + + With the `username` parameter you can filter for a specific user name. If the parameter is + used, the returned list either contains a single matching entry or is empty. + parameters: + - $ref: '#/components/parameters/username' responses: 200: content: @@ -863,13 +892,13 @@ paths: "500": $ref: '#/components/responses/500' /api/users/{userId}: - get: # TODO: review endpoint to get a single user by id + get: # TODO: implement endpoint to get a single user by id operationId: getUserById tags: - 5. Users - summary: TODO + summary: Retrieve a specific user by its identifier. description: | - # TODO: add description for endpoint to get a single user by id + This endpoint facilitates to retrieve a specific user. responses: 200: content: @@ -981,6 +1010,20 @@ components: Some endpoints support a `includeSoftDeleted` parameter: If this is set to `true`, this response is returned only if the file is deleted permanently. + "404-download": + content: + '*/*': + schema: + $ref: '#/components/schemas/ErrorMessage' + description: | + Download not found. This happens if the requested download does not exist for the current user. + "404-user": + content: + '*/*': + schema: + $ref: '#/components/schemas/ErrorMessage' + description: | + User not found. This happens if the requested user does not exist. "409-dossier-conflict": content: '*/*': @@ -988,13 +1031,6 @@ components: $ref: '#/components/schemas/ErrorMessage' description: | Name conflict: The provided name is already in use by another dossier. It needs to be unique in the scope of your workspace. - 422-rules: - content: - '*/*': - schema: - $ref: '#/components/schemas/RuleValidation' - description: | - Invalid rules file: There were validation errors, the rules file is unprocessable. "429": content: '*/*': @@ -1238,6 +1274,26 @@ 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 + required: false + schema: + type: string + style: form + explode: true + description: | + If the `username` parameter is set, the user list is filtered for that specific user name. This means the list + either has one matching entry or is empty. schemas: EntityReference: type: object @@ -1345,198 +1401,6 @@ components: entityRuleId: DEF.13.37 type: another_entity_type page: 456 - FileComponents: - type: object - description: Represents file details along with its associated components and values. - properties: - dossierTemplateId: - format: uuid - type: string - description: Identifier for the template associated with the dossier. - dossierId: - format: uuid - type: string - description: Identifier for the dossier. - fileId: - type: string - description: Identifier for the file. - filename: - type: string - description: Name of the file. - components: - type: object - description: A map of component names to their list of values. - additionalProperties: - items: - type: string - type: array - componentDetails: - type: object - description: A map of component names to their detailed representations. - additionalProperties: - $ref: '#/components/schemas/Component' - example: - dossierTemplateId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91 - dossierId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91 - fileId: 1fdbd888b39059c8cf171df26f62f8a5 - filename: MyFile.pdf - components: - "my component": - - my overwritten component value - - yet another component value - "yet another component": - - only one value - componentDetails: - - name: my component - componentValues: - - value: my overwritten component value - originalValue: the original value - componentRuleId: COM.0.0 - valueDescription: My value description - entityReferences: - - id: bcd22239-cedf-442f-a5a1-1664cba94dc6 - entityRuleId: ABC.0.0 - type: entity_type - page: 123 - - id: b748b89a-5679-4254-9286-1dd652d9970b - entityRuleId: DEF.13.37 - type: another_entity_type - page: 456 - - value: yet another component value - originalValue: yet another component value - componentRuleId: COM.0.1 - valueDescription: Another value description - entityReferences: - - id: 70496456-a016-4679-81b1-6c8856dded6e - entityRuleId: XYZ.0.0 - type: yet_another_entity_type - page: 123 - - name: yet another component - componentValues: - - value: only one value - originalValue: only one value - componentRuleId: COM.0.0 - valueDescription: My value description - entityReferences: - - id: bcd22239-cedf-442f-a5a1-1664cba94dc6 - entityRuleId: ABC.0.0 - type: entity_type - page: 123 - - id: b748b89a-5679-4254-9286-1dd652d9970b - entityRuleId: DEF.13.37 - type: another_entity_type - page: 456 - FileComponentsList: - type: object - description: A list of files and their associated components. - properties: - files: - type: array - description: List of files with their component details. - items: - $ref: '#/components/schemas/FileComponents' - example: - files: - - dossierTemplateId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91 - dossierId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91 - fileId: 1fdbd888b39059c8cf171df26f62f8a5 - filename: MyFile.pdf - components: - "my component": - - my overwritten component value - - yet another component value - "yet another component": - - only one value - componentDetails: - - name: my component - componentValues: - - value: my overwritten component value - originalValue: the original value - componentRuleId: COM.0.0 - valueDescription: My value description - entityReferences: - - id: bcd22239-cedf-442f-a5a1-1664cba94dc6 - entityRuleId: ABC.0.0 - type: entity_type - page: 123 - - id: b748b89a-5679-4254-9286-1dd652d9970b - entityRuleId: DEF.13.37 - type: another_entity_type - page: 456 - - value: yet another component value - originalValue: yet another component value - componentRuleId: COM.0.1 - valueDescription: Another value description - entityReferences: - - id: 70496456-a016-4679-81b1-6c8856dded6e - entityRuleId: XYZ.0.0 - type: yet_another_entity_type - page: 123 - - name: yet another component - componentValues: - - value: only one value - originalValue: only one value - componentRuleId: COM.0.0 - valueDescription: My value description - entityReferences: - - id: bcd22239-cedf-442f-a5a1-1664cba94dc6 - entityRuleId: ABC.0.0 - type: entity_type - page: 123 - - id: b748b89a-5679-4254-9286-1dd652d9970b - entityRuleId: DEF.13.37 - type: another_entity_type - page: 456 - - dossierTemplateId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91 - dossierId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91 - fileId: 4d2334def5fced0003888e47cbc270f7 - filename: Copy of MyFile.pdf - components: - "my component": - - my overwritten component value - - yet another component value - "yet another component": - - only one value - componentDetails: - - name: my component - componentValues: - - value: my overwritten component value - originalValue: the original value - componentRuleId: COM.0.0 - valueDescription: My value description - entityReferences: - - id: dadb54d4-587b-4e69-8c07-be9446a33537 - entityRuleId: ABC.0.0 - type: entity_type - page: 123 - - id: 30339f5a-4c19-447f-b0a0-0f14c094037e - entityRuleId: DEF.13.37 - type: another_entity_type - page: 456 - - value: yet another component value - originalValue: yet another component value - componentRuleId: COM.0.1 - valueDescription: Another value description - entityReferences: - - id: 086cd500-97da-44f8-8628-3324d11b4e8d - entityRuleId: XYZ.0.0 - type: yet_another_entity_type - page: 123 - - name: yet another component - componentValues: - - value: only one value - originalValue: only one value - componentRuleId: COM.0.0 - valueDescription: My value description - entityReferences: - - id: dadb54d4-587b-4e69-8c07-be9446a33537 - entityRuleId: ABC.0.0 - type: entity_type - page: 123 - - id: 30339f5a-4c19-447f-b0a0-0f14c094037e - entityRuleId: DEF.13.37 - type: another_entity_type - page: 456 DossierAttributeDefinition: type: object description: | @@ -1755,6 +1619,18 @@ components: filenameMappingCsvColumnHeader: "Filename" delimiter: "," encoding: "UTF-8" + ReportTemplateIdList: + type: array + items: + type: string + format: uuid + uniqueItems: true + description: | + List of template identifiers indicating which templates are used for generating reports or other outputs. + The reports are generated when requesting a download package. + example: + - b79cb3ba-745e-5d9a-8903-4a02327a7e09 + - fb3463a0-7d6e-54a3-bcd8-1b93388c648d DossierAttributes: type: object description: (DRAFT) Additional dossier attributes that can be set @@ -1764,10 +1640,11 @@ components: type: string type: object example: - myDossierAttribute: This is a file attribute value - yetAnotherDossierAttribute: This is yet another file attribute value - numericValuesNeedToBeStrings: "1234" - myDossierDate: "1. January 1337" + attributeIdToValue: + "1049a73c-8013-45d6-8217-0845a4ff1c61": This is a dossier attribute value + "79d5a138-d30a-4014-ad7f-43ffba1f4d04": This is yet another dossier attribute value + "1d30d9e8-4a6c-4ef0-96a0-7bef62e138db": "1234" + "b337b65a-0481-48d9-92e6-79e34760ef01": "1. January 1337" Dossier: type: object description: | @@ -1859,14 +1736,7 @@ components: downloadFileTypes: $ref: '#/components/schemas/DownloadFileTypes' reportTemplateIds: - type: array - items: - type: string - format: uuid - uniqueItems: true - description: | - List of template identifiers indicating which templates are to be used for generating reports or outputs - for this dossier. The reports are generated when requesting a download package. + $ref: '#/components/schemas/ReportTemplateIdList' archivedTime: type: string format: date-time @@ -2018,14 +1888,7 @@ components: description: A unique identifier for a member with access to the dossier. uniqueItems: true reportTemplateIds: - type: array - description: | - An array of identifiers representing templates used for generating reports - or exports from this dossier. - items: - description: An identifier for a report template. - type: string - uniqueItems: true + $ref: "#/components/schemas/ReportTemplateIdList" dossierStatusId: type: string description: | @@ -2180,6 +2043,9 @@ components: - DELTA_PREVIEW - REDACTED type: string + example: + - PREVIEW + - REDACTED DossierTemplateList: description: Represents a list of dossier templates, each encapsulating a set of rules and settings. example: @@ -2253,10 +2119,11 @@ components: type: string type: object example: - myFileAttribute: This is a file attribute value - yetAnotherFileAttribute: This is yet another file attribute value - numericValuesNeedToBeStrings: "1234" - myFileDate: "1. January 1337" + attributeIdToValue: + "9049a73c-8013-45d6-8217-0845a4ff1c61": This is a file attribute value + "59d5a138-d30a-4014-ad7f-43ffba1f4d04": This is yet another file attribute value + "9d30d9e8-4a6c-4ef0-96a0-7bef62e138db": "1234" + "a337b65a-0481-48d9-92e6-79e34760ef01": "1. January 1337" FileDeleteRequest: type: object description: Request payload to initiate the deletion of specific files. @@ -2600,7 +2467,7 @@ components: hasSuggestions: true FileStatusList: type: object - description: Represents a list detailing the status of a bunch of files. + description: Represents a list detailing the status of multiple files. properties: files: type: array @@ -2769,43 +2636,173 @@ components: type: string type: array type: object - RuleValidationMessage: - description: Object containing information about an uploaded rules file. - example: - line: 123 - column: 45 - message: "Unable to Analyse Expression ..." + DownloadStatus: + type: object + description: Detailed information about a specific download. properties: - line: - description: The line number where the error or warning occurs. - format: int32 - type: integer - column: - description: The column number where the error or warning occurs. - format: int32 - type: integer - message: - description: The error or warning message that describes the details. + id: type: string - type: object - RuleValidation: - description: | - Information about the uploaded rules file. The `error` field is empty if there were no validation errors in the uploaded rules file. - example: - errors: - - line: 123 - column: 45 - message: "Unable to Analyse Expression ..." - - line: 234 - column: 5 - message: "Invalid rule syntax ..." - properties: - errors: - description: List of errors found in the uploaded rules file. - items: - $ref: '#/components/schemas/RuleValidationMessage' + 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-redacted-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 RedactManager. + 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 RedactManager 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" + 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. + properties: + id: + type: string + format: uuid + description: The unique identifier of the user. + example: efe7eedd-89c5-56f5-984c-0712ee41a2eb + username: + type: string + description: The user name that is used for logging in. + example: myusername + email: + type: string + description: The email address of the user. + example: myusername@example.com + firstName: + type: string + description: The first name of the user. + example: John + lastName: + type: string + description: The last name of the user. + example: Doe + roles: + uniqueItems: true + type: array + description: | + The roles of the user. In particular: + - `USER` - default user permission to work with RedactManager + - `MANAGER` - additional privileges to create and manage dossiers + - `USER_ADMIN` - administration privileges limited to manage users only + - `ADMIN` - general administration privileges + items: + type: string + enum: + - USER + - MANAGER + - USER_ADMIN + - ADMIN + example: + - MANAGER + - ADMIN + active: + type: boolean + description: Indicator if the user is active or not. Only active users can log in. + UserList: + type: object + description: A list of multiple users. + properties: + downloadStatus: + type: array + items: + $ref: '#/components/schemas/User' + description: Each item contains the details of a user. LicenseReport: type: object description: A comprehensive report of licensing metrics and usage statistics. @@ -2984,9 +2981,12 @@ components: - file securitySchemes: FF-OAUTH: + type: oauth2 flows: authorizationCode: - authorizationUrl: /auth/realms/redaction/protocol/openid-connect/auth - scopes: { } - tokenUrl: /auth/realms/redaction/protocol/openid-connect/token - type: oauth2 + authorizationUrl: /auth/realms/{workspaceId}/protocol/openid-connect/auth + tokenUrl: /auth/realms/{workspaceId}/protocol/openid-connect/token + scopes: {} + clientCredentials: + tokenUrl: /auth/realms/{workspaceId}/protocol/openid-connect/token + scopes: {} \ No newline at end of file -- 2.47.2 From 0002f39707493c8164f403d08a2b22a95f5f761a Mon Sep 17 00:00:00 2001 From: Kresnadi Budisantoso Date: Mon, 29 Apr 2024 17:37:58 +0200 Subject: [PATCH 06/11] RedactManager API Specs for BASF - minor description fixes --- .../src/main/resources/api/redactmanager.yaml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) 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 d910e2a15..e3abc4983 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 @@ -1,7 +1,7 @@ openapi: 3.0.2 info: - title: RedactManager API - DRAFT - version: "4.1.0" + title: RedactManager API + version: "4.1.0-draft" description: | The RedactManager API provides a comprehensive solution for managing resources such as dossiers and their associated files. Users can also retrieve the results package for files that have been processed by the system and reviewed by the users. @@ -338,7 +338,7 @@ paths: operationId: setDossierAttributes tags: - 2. Dossiers - summary: (DRAFT) Update or set attributes for a specific dossier. + summary: Update or set attributes for a specific dossier. description: | This endpoint facilitates the updating or setting of specific dossier attributes for a given dossier. Ensure you provide the necessary dossier attributes within the request body. @@ -374,7 +374,7 @@ paths: operationId: prepareDossierDownload tags: - 2. Dossiers - summary: (DRAFT) Trigger the creation of a download package for all files of a dossier. + summary: Initiate the creation of a download package for all files of a dossier. description: | To download the results of a redaction, 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 @@ -581,7 +581,7 @@ paths: operationId: prepareFileDownload tags: - 3. Files - summary: (DRAFT) Trigger the creation of a download package for a single file of a dossier. + summary: Initiate the creation of a download package for a single file of a dossier. description: | To download the results of a redaction, 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 @@ -665,7 +665,7 @@ paths: operationId: prepareBulkDownload tags: - 3. Files - summary: (DRAFT) Trigger the creation of a download package for specific files within a dossier. + summary: Initiate the creation of a download package for specific files within a dossier. description: | To download the results of a redaction, 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 @@ -866,7 +866,7 @@ paths: tags: - 5. Users - tenant-user-management - summary: TODO + summary: Get a list of users description: | This endpoint facilitates to retrieve a list of known users. @@ -1633,7 +1633,7 @@ components: - fb3463a0-7d6e-54a3-bcd8-1b93388c648d DossierAttributes: type: object - description: (DRAFT) Additional dossier attributes that can be set + description: Additional dossier attributes that can be set properties: attributeIdToValue: additionalProperties: -- 2.47.2 From 5a202904fdafb611994b9e72d89046f68c102b1b Mon Sep 17 00:00:00 2001 From: Kresnadi Budisantoso Date: Mon, 29 Apr 2024 17:48:18 +0200 Subject: [PATCH 07/11] RedactManager API Specs for BASF - removed some DocuMine stuff --- .../src/main/resources/api/redactmanager.yaml | 89 ------------------- 1 file changed, 89 deletions(-) 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 e3abc4983..c5e9e9da4 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 @@ -1260,20 +1260,6 @@ components: overwriting a file: - `true`: The system keeps the manual changes on re-uploading (overwriting) the file. - `false` (default): Manual changes get discarded on re-uploading the file. - includeComponentDetails: - name: includeDetails - in: query - required: false - schema: - default: false - type: boolean - style: form - explode: true - description: | - A toggle to decide whether to include detailed component information in the response: - - `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 @@ -1326,81 +1312,6 @@ components: entityRuleId: ABC.0.0 type: entity_type page: 123 - Component: - type: object - description: Represents a component with its associated values. - properties: - name: - type: string - description: The name of the component. - componentValues: - type: array - description: A list of value objects associated with the component. - items: - $ref: '#/components/schemas/ComponentValue' - example: - name: the component name - componentValues: - - value: my overwritten component value - originalValue: the original value - componentRuleId: COM.0.0 - valueDescription: My value description - entityReferences: - - id: bcd22239-cedf-442f-a5a1-1664cba94dc6 - entityRuleId: ABC.0.0 - type: entity_type - page: 123 - - id: bcd22239-c3df-442f-a5a1-1664cba94dc6_2 - entityRuleId: ABC.0.0 - type: entity_type - page: 124 - - id: b748b89a-5679-4254-9286-1dd652d9970b - entityRuleId: DEF.13.37 - type: another_entity_type - page: 456 - - value: yet another component value - originalValue: yet another component value - componentRuleId: COM.0.1 - valueDescription: Another value description - entityReferences: - - id: 70496456-a016-4679-81b1-6c8856dded6e - entityRuleId: XYZ.0.0 - type: yet_another_entity_type - page: 123 - ComponentValue: - type: object - description: Describes a value associated with a component, including its origin and related entities found in the document. - properties: - value: - type: string - description: The current value of the component. - originalValue: - type: string - description: The original value before any modifications. - componentRuleId: - type: string - description: Identifier for the rule associated with this component value. - valueDescription: - type: string - description: A brief description of the value. - entityReferences: - items: - $ref: '#/components/schemas/EntityReference' - type: array - example: - value: my overwritten component value - originalValue: the original value - componentRuleId: COM.0.0 - valueDescription: My value description - entityReferences: - - id: bcd22239-cedf-442f-a5a1-1664cba94dc6 - entityRuleId: ABC.0.0 - type: entity_type - page: 123 - - id: b748b89a-5679-4254-9286-1dd652d9970b - entityRuleId: DEF.13.37 - type: another_entity_type - page: 456 DossierAttributeDefinition: type: object description: | -- 2.47.2 From 27cc5518d0b2cef854905b2ebabfaa1e295bf7e5 Mon Sep 17 00:00:00 2001 From: Kresnadi Budisantoso Date: Thu, 2 May 2024 15:09:28 +0200 Subject: [PATCH 08/11] RedactManager API Specs for BASF - Added endpoint to retrieve the dossier status definitions --- .../src/main/resources/api/redactmanager.yaml | 111 +++++++++++++++++- 1 file changed, 107 insertions(+), 4 deletions(-) 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 c5e9e9da4..64bfdeb01 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 @@ -111,6 +111,37 @@ paths: $ref: '#/components/responses/429' "500": $ref: '#/components/responses/500' + /api/dossier-templates/{dossierTemplateId}/dossier-status-definitions: + get: # TODO: implement endpoint to get dossier status definitions + summary: Returns the list of all existing dossier status definitions + tags: + - 1. Dossier Templates + description: | + Retrieves a collection of dossier status definitions associated with a specific dossier template. Each dossier + status definition includes details such as the status name, description, and other relevant metadata. This endpoint + is useful for clients needing to display or set the status of a dossier associated with a specific dossier template. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + responses: + "200": + content: + '*/*': + schema: + $ref: '#/components/schemas/DossierStatusDefinitionList' + description: | + Successfully returned the dossier status definitions for the specified dossier template. + "400": + $ref: '#/components/responses/400' + "401": + $ref: '#/components/responses/401' + "403": + $ref: '#/components/responses/403' + "404": + $ref: '#/components/responses/404-dossier-template' + "429": + $ref: '#/components/responses/429' + "500": + $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossier-attribute-definitions: get: # TODO: implement endpoint to get dossier attribute definitions summary: Returns the list of all existing dossier attribute definitions @@ -119,8 +150,8 @@ paths: description: | Retrieves a collection of dossier attribute definitions associated with a specific dossier template. Each dossier attribute definition includes details such as attribute type, name, and other relevant metadata. This endpoint - is useful for clients needing to understand what attributes are expected or allowed for dossiers under a particular - dossier template. + is useful for clients needing to understand what attributes are expected or allowed for dossiers associated with + a specific dossier template. parameters: - $ref: '#/components/parameters/dossierTemplateId' responses: @@ -151,8 +182,8 @@ paths: description: | Retrieves a collection of file attribute definitions associated with a specific dossier template. Each file attribute definition includes details such as attribute type, name, and other relevant metadata. This endpoint - is useful for clients needing to understand what attributes are expected or allowed for files under a particular - dossier template. + is useful for clients needing to understand what attributes are expected or allowed for files associated with + a specific dossier template. parameters: - $ref: '#/components/parameters/dossierTemplateId' responses: @@ -1312,6 +1343,51 @@ components: entityRuleId: ABC.0.0 type: entity_type page: 123 + DossierStatusDefinition: + type: object + description: | + The `DossierStatusDefinition` object contains the relevant information to define a dossier status. The dossier status + is used to assign a custom status to a dossier. + properties: + id: + type: string + format: uuid + description: | + A unique identifier for the dossier status definition. This ID is automatically generated by + the system upon creation and is used for referencing the dossier status definition in API calls. + example: bcd22239-cedf-442f-a5a1-1664cba94dc6 + name: + type: string + description: | + User-defined name of the dossier status definition, capturing its essence. The name needs to be unique + for the dossier template. + example: "Done" + description: + type: string + 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." + rank: + format: int32 + type: integer + description: | + A number that allows to define a custom display order. + default: "" + example: 1 + color: + type: string + description: | + A hexadecimal color code that can be set to assign a color to a + the `PREVIEW` file. + + - Yellow is `#ffda05` + - Green is `#5eb160` + example: "#5eb160" + required: + - name + - rank + - color DossierAttributeDefinition: type: object description: | @@ -1443,6 +1519,26 @@ components: editable: true filterable: true displayedInFileList: false + DossierStatusDefinitionList: + type: object + description: A list of dossier status definitions. + properties: + dossierStatusDefinitions: + items: + $ref: '#/components/schemas/DossierStatusDefinition' + type: array + example: + dossierStatusDefinitions: + - id: "123e7567-e89b-12d3-a456-426614174000" + name: "In Progress" + description: "Dossiers with this status are currently being processed by the users." + rank: 0 + color: "#ffda05" + - id: "23e45378-e90b-12d3-a456-765114174321" + name: "Done" + description: "Dossiers with this status should only contain approved files and indicate that the users have completed the redactions." + rank: 1 + color: "#5eb160" DossierAttributeDefinitionList: type: object description: A list of dossier attribute definitions. @@ -2646,6 +2742,13 @@ components: 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' -- 2.47.2 From d82935d4a53e9203f1c77e4af6129ae05a484cf5 Mon Sep 17 00:00:00 2001 From: Kresnadi Budisantoso Date: Wed, 22 May 2024 16:27:25 +0200 Subject: [PATCH 09/11] RedactManager API Specs for BASF - Removed comments and updated documine specs --- .../src/main/resources/api/documine.yaml | 614 +++++++++++++++--- .../src/main/resources/api/redactmanager.yaml | 34 +- 2 files changed, 526 insertions(+), 122 deletions(-) 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 8a636dacd..66f94bd9e 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 @@ -6,9 +6,12 @@ info: The DocuMine API provides a comprehensive solution for managing resources such as dossiers and their associated files. Users can also retrieve components of files that have been processed and extracted by the system. - All endpoints are secured using OAuth2, with the "authorizationCode" being the supported authorization flow. + All endpoints are secured using OAuth2, with the "authorizationCode" being the general supported authorization flow. 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. + Example Headers: ```properties Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI... @@ -36,7 +39,9 @@ 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. License + - name: 5. Users + description: Operations related to users. + - name: 6. License description: Operations related to license information and usage metrics. paths: /api/dossier-templates: @@ -266,6 +271,69 @@ paths: $ref: '#/components/responses/429' "500": $ref: '#/components/responses/500' + /api/dossier-templates/{dossierTemplateId}/dossier-status-definitions: + get: + summary: Returns the list of all existing dossier status definitions + tags: + - 1. Dossier Templates + description: | + Retrieves a collection of dossier status definitions associated with a specific dossier template. Each dossier + status definition includes details such as the status name, description, and other relevant metadata. This endpoint + is useful for clients needing to display or set the status of a dossier associated with a specific dossier template. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + responses: + "200": + content: + '*/*': + schema: + $ref: '#/components/schemas/DossierStatusDefinitionList' + description: | + Successfully returned the dossier status definitions for the specified dossier template. + "400": + $ref: '#/components/responses/400' + "401": + $ref: '#/components/responses/401' + "403": + $ref: '#/components/responses/403' + "404": + $ref: '#/components/responses/404-dossier-template' + "429": + $ref: '#/components/responses/429' + "500": + $ref: '#/components/responses/500' + /api/dossier-templates/{dossierTemplateId}/dossier-attribute-definitions: + get: + summary: Returns the list of all existing dossier attribute definitions + tags: + - 1. Dossier Templates + description: | + Retrieves a collection of dossier attribute definitions associated with a specific dossier template. Each dossier + attribute definition includes details such as attribute type, name, and other relevant metadata. This endpoint + is useful for clients needing to understand what attributes are expected or allowed for dossiers associated with + a specific dossier template. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + responses: + "200": + content: + '*/*': + schema: + $ref: '#/components/schemas/DossierAttributeDefinitionList' + description: | + Successfully returned the dossier attribute definitions for the specified dossier template. + "400": + $ref: '#/components/responses/400' + "401": + $ref: '#/components/responses/401' + "403": + $ref: '#/components/responses/403' + "404": + $ref: '#/components/responses/404-dossier-template' + "429": + $ref: '#/components/responses/429' + "500": + $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/file-attribute-definitions: get: summary: Returns the list of all existing file attribute definitions @@ -274,8 +342,8 @@ paths: description: | Retrieves a collection of file attribute definitions associated with a specific dossier template. Each file attribute definition includes details such as attribute type, name, and other relevant metadata. This endpoint - is useful for clients needing to understand what attributes are expected or allowed for files under a particular - dossier template. + is useful for clients needing to understand what attributes are expected or allowed for files associated with + a specific dossier template. parameters: - $ref: '#/components/parameters/dossierTemplateId' responses: @@ -286,6 +354,18 @@ paths: $ref: '#/components/schemas/FileAttributeDefinitionList' description: | Successfully returned the file attribute definitions for the specified dossier template. + "400": + $ref: '#/components/responses/400' + "401": + $ref: '#/components/responses/401' + "403": + $ref: '#/components/responses/403' + "404": + $ref: '#/components/responses/404-dossier-template' + "429": + $ref: '#/components/responses/429' + "500": + $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossiers: get: operationId: getDossiers @@ -444,6 +524,42 @@ paths: $ref: '#/components/responses/429' "500": $ref: '#/components/responses/500' + /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/attributes: + post: + operationId: setDossierAttributes + tags: + - 2. Dossiers + summary: Update or set attributes for a specific dossier. + description: | + This endpoint facilitates the updating or setting of specific dossier attributes for a given dossier. + Ensure you provide the necessary dossier attributes within the request body. + + Use this route to maintain or enhance dossier metadata and properties. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + - $ref: '#/components/parameters/dossierId' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DossierAttributes' + required: true + responses: + "204": + description: | + Dossier attributes successfully updated. + "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 @@ -564,10 +680,14 @@ paths: File deletion successful. This confirms the absence of the specified file, 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-file' + "429": + $ref: '#/components/responses/429' "500": $ref: '#/components/responses/500' get: @@ -594,10 +714,14 @@ paths: Successfully retrieved the status of 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: @@ -630,10 +754,14 @@ paths: Bulk file deletion successful. "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: @@ -658,15 +786,19 @@ paths: $ref: '#/components/schemas/FileAttributes' required: true responses: - "200": + "204": description: | File attributes successfully updated. "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/{fileId}/components: @@ -699,10 +831,14 @@ paths: Successfully retrieved file components. "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/get-components: @@ -733,19 +869,81 @@ paths: $ref: '#/components/schemas/FileComponentsList' description: | Successfully fetched components for all files in the dossier. - "404": - $ref: '#/components/responses/404-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/users: + get: + operationId: getUsers + tags: + - 5. Users + - tenant-user-management + summary: Get a list of users + description: | + This endpoint facilitates to retrieve a list of known users. + + With the `username` parameter you can filter for a specific user name. If the parameter is + used, the returned list either contains a single matching entry or is empty. + parameters: + - $ref: '#/components/parameters/username' + responses: + 200: + content: + application/json: + schema: + $ref: '#/components/schemas/UserList' + description: List of 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/users/{userId}: + get: + operationId: getUserById + tags: + - 5. Users + summary: Retrieve a specific user by its identifier. + description: | + This endpoint facilitates to retrieve a specific user. + responses: + 200: + content: + application/json: + schema: + $ref: '#/components/schemas/User' + description: User successfully retrieved. + "400": + $ref: '#/components/responses/400' + "401": + $ref: '#/components/responses/401' + "403": + $ref: '#/components/responses/403' + "404": + $ref: '#/components/responses/404-user' + "429": + $ref: '#/components/responses/429' "500": $ref: '#/components/responses/500' /api/license/active/usage: post: - operationId: getReport + operationId: getLicenseReport tags: - - 5. License + - 6. 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 @@ -767,18 +965,16 @@ paths: License report successfully generated and 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' components: headers: - X-Tenant-ID: - description: Tenant identifier, also known as the *Workspace ID* in the application. - required: true - schema: - type: string - example: 'my-workspace' Authorization: description: JWT token for authorization. Format should be `Bearer {JWT_TOKEN}`. required: true @@ -835,6 +1031,20 @@ components: Some endpoints support a `includeSoftDeleted` parameter: If this is set to `true`, this response is returned only if the file is deleted permanently. + "404-download": + content: + '*/*': + schema: + $ref: '#/components/schemas/ErrorMessage' + description: | + Download not found. This happens if the requested download does not exist for the current user. + "404-user": + content: + '*/*': + schema: + $ref: '#/components/schemas/ErrorMessage' + description: | + User not found. This happens if the requested user does not exist. "409-dossier-conflict": content: '*/*': @@ -1092,6 +1302,17 @@ 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`. + username: + name: username + in: query + required: false + schema: + type: string + style: form + explode: true + description: | + If the `username` parameter is set, the user list is filtered for that specific user name. This means the list + either has one matching entry or is empty. schemas: EntityReference: type: object @@ -1391,6 +1612,96 @@ components: entityRuleId: DEF.13.37 type: another_entity_type page: 456 + DossierStatusDefinition: + type: object + description: | + The `DossierStatusDefinition` object contains the relevant information to define a dossier status. The dossier status + is used to assign a custom status to a dossier. + properties: + id: + type: string + format: uuid + description: | + A unique identifier for the dossier status definition. This ID is automatically generated by + the system upon creation and is used for referencing the dossier status definition in API calls. + example: bcd22239-cedf-442f-a5a1-1664cba94dc6 + name: + type: string + description: | + User-defined name of the dossier status definition, capturing its essence. The name needs to be unique + for the dossier template. + example: "Done" + description: + type: string + 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." + rank: + format: int32 + type: integer + description: | + A number that allows to define a custom display order. + default: "" + example: 1 + color: + type: string + description: | + A hexadecimal color code that can be set to assign a color to a + the `PREVIEW` file. + + - Yellow is `#ffda05` + - Green is `#5eb160` + example: "#5eb160" + required: + - name + - rank + - color + DossierAttributeDefinition: + type: object + description: | + The `DossierAttributeDefinition` object contains the relevant information to define a dossier attribute. Dossier attributes + are used to manage additional meta-data of dossiers. + properties: + id: + type: string + format: uuid + description: | + A unique identifier for the dossier attribute definition. This ID is automatically generated by + the system upon creation and is used for referencing the dossier attribute definition in API calls. + name: + type: string + description: | + User-defined name of the dossier attribute definition, capturing its essence. The name needs to be unique + for the dossier template. + type: + type: string + enum: + - TEXT + - NUMBER + - DATE + description: | + Determines the type of the dossier attribute's value. Please note that currently the system + does not validate the values against this definition. This is just a hint for a user interface + that needs to handle invalid entries. Possible values for the type: + - `TEXT`: The value is just a string, i.e., any sequence of characters. + - `NUMBER`: The value is a string expressing a number, with or without decimals. + - `DATE`: The value is a string expressing a date information. + reportingPlaceholder: + type: string + description: | + The name of the placeholder of the dossier attribute that can be used in report templates. The + placeholder follows a specific format convention: + `{{dossier.attribute.}}` while the name is transformed into 'PascalCase' and does not contain + whitespaces. The placeholder is unique in a dossier template. + required: + - name + - type + example: + id: "123e4567-e89b-12d3-a456-426614174000" + name: "Document Summary" + type: "TEXT" + reportingPlaceholder: "{{dossier.attribute.DocumentSummary}}" FileAttributeDefinition: type: object description: | @@ -1415,7 +1726,7 @@ components: - NUMBER - DATE description: | - Determines the type of the dossier attribute's value. Please note that currently the system + Determines the type of the file attribute's value. Please note that currently the system does not validate the values against this definition. This is just a hint for a user interface that needs to handle invalid entries. Possible values for the type: - `TEXT`: The value is just a string, i.e., any sequence of characters. @@ -1429,7 +1740,7 @@ components: type: string description: | The name of the placeholder of the file attribute that can be used in report templates. The placeholder follows a specific format convention: - `{{file.attribute.}}` while the name transformed into 'PascalCase' and does not contain whitespaces. The placeholder is unique in a dossier template. + `{{file.attribute.}}` while the name is transformed into 'PascalCase' and does not contain whitespaces. The placeholder is unique in a dossier template. displaySettings: $ref: '#/components/schemas/FileAttributeDisplaySettings' required: @@ -1449,24 +1760,24 @@ components: FileAttributeDisplaySettings: type: object description: | - Display setting for the RedactManager and DocuMine user interface. These settings control how the UI handles and presents the file attributes. + Display setting for the DocuMine user interface. These settings control how the UI handles and presents the file attributes. properties: primaryAttribute: type: boolean description: | - If `true`, the RedactManager and DocuMine user interfaces show the value of the file attribute in the file list below the file name. + If `true`, the DocuMine user interfaces show the value of the file attribute in the file list below the file name. editable: type: boolean description: | - If `true`, the RedactManager and DocuMine user interfaces allow manual editing of the value. Otherwise only importing and setting by rules would be possible. + If `true`, the DocuMine user interfaces allow manual editing of the value. Otherwise only importing and setting by rules would be possible. filterable: type: boolean description: | - If `true`, the RedactManager and DocuMine user interfaces add filter options to the file list. + If `true`, the DocuMine user interfaces add filter options to the file list. displayedInFileList: type: boolean description: | - if `true`, the RedactManager and DocuMine user interfaces show the values in the file list. + if `true`, the DocuMine user interfaces show the values in the file list. required: - primaryAttribute - editable @@ -1477,6 +1788,44 @@ components: editable: true filterable: true displayedInFileList: false + DossierStatusDefinitionList: + type: object + description: A list of dossier status definitions. + properties: + dossierStatusDefinitions: + items: + $ref: '#/components/schemas/DossierStatusDefinition' + type: array + example: + dossierStatusDefinitions: + - id: "123e7567-e89b-12d3-a456-426614174000" + name: "In Progress" + description: "Dossiers with this status are currently being processed by the users." + rank: 0 + color: "#ffda05" + - id: "23e45378-e90b-12d3-a456-765114174321" + name: "Done" + description: "Dossiers with this status should only contain approved files and indicate that the users have completed the component extraction." + rank: 1 + color: "#5eb160" + DossierAttributeDefinitionList: + type: object + description: A list of dossier attribute definitions. + properties: + dossierAttributeDefinitions: + items: + $ref: '#/components/schemas/DossierAttributeDefinition' + type: array + example: + dossierAttributeDefinitions: + - id: "123e4567-e89b-12d3-a456-426614174000" + name: "Dossier Summary" + type: "TEXT" + reportingPlaceholder: "{{dossier.attribute.DossierSummary}}" + - id: "23e45678-e90b-12d3-a456-765114174321" + name: "Comment" + type: "TEXT" + reportingPlaceholder: "{{dossier.attribute.Comment}}" FileAttributeDefinitionList: type: object description: A list of file attribute definitions. @@ -1546,6 +1895,32 @@ components: filenameMappingCsvColumnHeader: "Filename" delimiter: "," encoding: "UTF-8" + ReportTemplateIdList: + type: array + items: + type: string + format: uuid + uniqueItems: true + description: | + List of template identifiers indicating which templates are used for generating reports or other outputs. + The reports are generated when requesting a download package. + example: + - b79cb3ba-745e-5d9a-8903-4a02327a7e09 + - fb3463a0-7d6e-54a3-bcd8-1b93388c648d + DossierAttributes: + type: object + description: Additional dossier attributes that can be set + properties: + attributeIdToValue: + additionalProperties: + type: string + type: object + example: + attributeIdToValue: + "1049a73c-8013-45d6-8217-0845a4ff1c61": This is a dossier attribute value + "79d5a138-d30a-4014-ad7f-43ffba1f4d04": This is yet another dossier attribute value + "1d30d9e8-4a6c-4ef0-96a0-7bef62e138db": "1234" + "b337b65a-0481-48d9-92e6-79e34760ef01": "1. January 1337" Dossier: type: object description: | @@ -1628,42 +2003,19 @@ components: format: uuid deprecated: true description: | - Identifier for the watermark that's to be applied on redacted documents within this dossier. - In DocuMine, watermarks are not supported. previewWatermarkId: type: string format: uuid deprecated: true description: | - Identifier for the watermark pattern used for generated previews documents within this dossier. - In DocuMine, watermarks are not supported. + dossierAttributes: + $ref: '#/components/schemas/DossierAttributes' downloadFileTypes: - type: array - items: - enum: - - ORIGINAL - - PREVIEW - - REDACTED - - ANNOTATED - - FLATTEN - - DELTA_PREVIEW - type: string - uniqueItems: true - description: | - Types of files available for download from the dossier. These types can - differ based on the application. DocuMine only supports `ORIGINAL`. The files are - provided or generated when requesting a download package. + $ref: '#/components/schemas/DownloadFileTypes' reportTemplateIds: - type: array - items: - type: string - format: uuid - uniqueItems: true - description: | - List of template identifiers indicating which templates are to be used for generating reports or outputs - for this dossier. The reports are generated when requesting a download package. + $ref: '#/components/schemas/ReportTemplateIdList' archivedTime: type: string format: date-time @@ -1815,14 +2167,7 @@ components: description: A unique identifier for a member with access to the dossier. uniqueItems: true reportTemplateIds: - type: array - description: | - An array of identifiers representing templates used for generating reports - or exports from this dossier. - items: - description: An identifier for a report template. - type: string - uniqueItems: true + $ref: "#/components/schemas/ReportTemplateIdList" dossierStatusId: type: string description: | @@ -1852,8 +2197,8 @@ components: of individual dossiers that get created based on this template. example: id: 1e07cde0-d36a-4ab7-b389-494ca694a0cb - name: RedactManager Example - description: Typical settings for RedactManager. + name: DocuMine Example + description: Typical settings for DocuMine. dateAdded: 2020-01-23T04:56:07.000+00:00 dateModified: 2021-01-23T04:56:07.000+00:00 createdBy: c2e33246-e50a-4c43-831c-6789a5637db6 @@ -1862,14 +2207,13 @@ components: validTo: 2030-12-31T23:59:59.999+00:00 dossierTemplateStatus: ACTIVE removeWatermark: false - keepImageMetadata: false - ocrByDefault: false - keepHiddenText: false - keepOverlappingObjects: false + keepImageMetadata: true + ocrByDefault: true + keepHiddenText: true + keepOverlappingObjects: true applyDictionaryUpdatesToAllDossiersByDefault: false downloadFileTypes: - - PREVIEW - - REDACTED + - ORIGINAL properties: id: description: | @@ -1914,30 +2258,7 @@ components: format: date-time type: string downloadFileTypes: - description: | - Specifies the types of files that will be set as default types to download for dossiers created from - this template. Valid options may vary depending on the system. - - * Valid options for RedactManager: - * `ORIGINAL`: The optimized version of the PDF like it is used by the system for further analysis. - * `PREVIEW`: The optimized PDF with redaction annotations indicating what gets redacted by the - system. Note that the content to redact is actually still present and readable. - * `REDACTED`: The redacted PDF - * `DELTA_PREVIEW`: If redactions were imported (e.g., by uploading a PDF with redaction annotations), - this PDF highlights the changes made to imported redactions in different colors (green: no change, - red: removed, blue: added). - * Valid options for DocuMine: - * `ORIGINAL`: The optimized version of the PDF like it is used by the system for further analysis. - items: - description: Enumerated type indicating a permissible download file type for dossiers under this template. - enum: - - ORIGINAL - - PREVIEW - - REDACTED - - DELTA_PREVIEW - type: string - type: array - uniqueItems: true + $ref: '#/components/schemas/DownloadFileTypes' status: description: | Indicates the current status of the dossier template: @@ -1971,13 +2292,34 @@ components: description: Flag specifying if the system should try to remove watermarks in documents prior to OCR processing. type: boolean type: object + DownloadFileTypes: + type: array + uniqueItems: true + description: | + Specifies the types of files that will part of the created download package. The defaults can be defined in the dossier template + and can be overwritten individually on each download. + + DocuMine supports `ORIGINAL` and `PREVIEW`: + + - `ORIGINAL` Contrary to intuition, this is not the uploaded file, but the pre-processed, + optimized PDF, which may also contain the OCR results. + This is the PDF that used by the system for further processing. + - `PREVIEW` The annotated version of the PDF, highlighting the found entities that were + evaluated to extract the components. + items: + enum: + - ORIGINAL + - PREVIEW + type: string + example: + - ORIGINAL DossierTemplateList: description: Represents a list of dossier templates, each encapsulating a set of rules and settings. example: dossierTemplates: - id: 1e07cde0-d36a-4ab7-b389-494ca694a0cb - name: RedactManager Example - description: Typical settings for RedactManager. + name: DocuMine Example + description: Typical settings for DocuMine. dateAdded: 2020-01-23T04:56:07.000+00:00 dateModified: 2021-01-23T04:56:07.000+00:00 createdBy: c2e33246-e50a-4c43-831c-6789a5637db6 @@ -1986,16 +2328,15 @@ components: validTo: 2030-12-31T23:59:59.999+00:00 dossierTemplateStatus: ACTIVE removeWatermark: false - keepImageMetadata: false - ocrByDefault: false - keepHiddenText: false - keepOverlappingObjects: false + keepImageMetadata: true + ocrByDefault: true + keepHiddenText: true + keepOverlappingObjects: true applyDictionaryUpdatesToAllDossiersByDefault: false downloadFileTypes: - - PREVIEW - - REDACTED + - ORIGINAL - id: 8d8cae48-5c33-4617-ac27-1643f29b79d8 - name: DocuMine Example + name: Another DocuMine Example description: Typical settings for DocuMine. dateAdded: 2023-09-01T06:54:32.000+00:00 dateModified: 2023-09-01T06:54:32.000+00:00 @@ -2044,9 +2385,11 @@ components: type: string type: object example: - myFileAttribute: This is a file attribute value - yetAnotherFileAttribute: This is yet another file attribute value - numericValuesNeedToBeStrings: "1234" + attributeIdToValue: + "9049a73c-8013-45d6-8217-0845a4ff1c61": This is a file attribute value + "59d5a138-d30a-4014-ad7f-43ffba1f4d04": This is yet another file attribute value + "9d30d9e8-4a6c-4ef0-96a0-7bef62e138db": "1234" + "a337b65a-0481-48d9-92e6-79e34760ef01": "1. January 1337" FileDeleteRequest: type: object description: Request payload to initiate the deletion of specific files. @@ -2147,7 +2490,7 @@ components: The workflow status of a file. As DocuMine does not have an approval workflow the meaning of the states is as follows: - - `NEW` means "New", nothing else. + - `NEW` - Initial status of the uploaded files. - `UNDER_REVIEW` is actually not used in DocuMine. - `UNDER_APPROVAL` means "In progress", i.e. a user is checking the extracted components. - `APPROVED` means "Done", i.e. a user has checked and adjusted the components if necessary. @@ -2386,7 +2729,7 @@ components: hasSuggestions: true FileStatusList: type: object - description: Represents a list detailing the status of a bunch of files. + description: Represents a list detailing the status of multiple files. properties: files: type: array @@ -2592,6 +2935,62 @@ components: $ref: '#/components/schemas/RuleValidationMessage' type: array type: object + User: + type: object + description: Basic information about a user. + properties: + id: + type: string + format: uuid + description: The unique identifier of the user. + example: efe7eedd-89c5-56f5-984c-0712ee41a2eb + username: + type: string + description: The user name that is used for logging in. + example: myusername + email: + type: string + description: The email address of the user. + example: myusername@example.com + firstName: + type: string + description: The first name of the user. + example: John + lastName: + type: string + description: The last name of the user. + example: Doe + roles: + uniqueItems: true + type: array + description: | + The roles of the user. In particular: + - `USER` - default user permission to work with RedactManager + - `MANAGER` - additional privileges to create and manage dossiers + - `USER_ADMIN` - administration privileges limited to manage users only + - `ADMIN` - general administration privileges + items: + type: string + enum: + - USER + - MANAGER + - USER_ADMIN + - ADMIN + example: + - MANAGER + - ADMIN + active: + type: boolean + description: Indicator if the user is active or not. Only active users can log in. + UserList: + type: object + description: A list of multiple users. + properties: + downloadStatus: + type: array + items: + $ref: '#/components/schemas/User' + description: Each item contains the details of a user. LicenseReport: type: object description: A comprehensive report of licensing metrics and usage statistics. @@ -2770,9 +3169,12 @@ components: - file securitySchemes: FF-OAUTH: + type: oauth2 flows: authorizationCode: - authorizationUrl: /auth/realms/redaction/protocol/openid-connect/auth + authorizationUrl: /auth/realms/{workspaceId}/protocol/openid-connect/auth + tokenUrl: /auth/realms/{workspaceId}/protocol/openid-connect/token scopes: { } - tokenUrl: /auth/realms/redaction/protocol/openid-connect/token - type: oauth2 + clientCredentials: + tokenUrl: /auth/realms/{workspaceId}/protocol/openid-connect/token + scopes: {} \ No newline at end of file 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 64bfdeb01..c9e09c4c7 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 @@ -112,7 +112,7 @@ paths: "500": $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossier-status-definitions: - get: # TODO: implement endpoint to get dossier status definitions + get: summary: Returns the list of all existing dossier status definitions tags: - 1. Dossier Templates @@ -143,7 +143,7 @@ paths: "500": $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossier-attribute-definitions: - get: # TODO: implement endpoint to get dossier attribute definitions + get: summary: Returns the list of all existing dossier attribute definitions tags: - 1. Dossier Templates @@ -365,7 +365,7 @@ paths: "500": $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/attributes: - post: # TODO: implement endpoint to set or update dossier attribute values + post: operationId: setDossierAttributes tags: - 2. Dossiers @@ -401,7 +401,7 @@ paths: "500": $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/create-download: - post: # TODO: implement endpoint to prepare a download for all files of a dossier + post: operationId: prepareDossierDownload tags: - 2. Dossiers @@ -608,7 +608,7 @@ paths: "500": $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/files/{fileId}/create-download: - post: # TODO: implement endpoint to prepare a download of a single file + post: operationId: prepareFileDownload tags: - 3. Files @@ -692,7 +692,7 @@ paths: "500": $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossiers/{dossierId}/files/bulk/create-download: - post: # TODO: implement endpoint to prepare a bulk download of multiple files, check if fileIds match the dossierId + post: operationId: prepareBulkDownload tags: - 3. Files @@ -772,7 +772,7 @@ paths: "500": $ref: '#/components/responses/500' /api/download: - get: # TODO: implement endpoint to get the status of all downloads of the current user + get: operationId: getDownloadStatusList tags: - 4. Downloads @@ -799,7 +799,7 @@ paths: "500": $ref: '#/components/responses/500' /api/downloads/{downloadId}: - get: # TODO: implement endpoint to get a single download status by id + get: operationId: getDownloadStatus tags: - 4. Downloads @@ -829,7 +829,7 @@ paths: $ref: '#/components/responses/429' "500": $ref: '#/components/responses/500' - delete: # TODO: implement endpoint to delete a single download by id + delete: operationId: deleteDownload tags: - 4. Downloads @@ -855,7 +855,7 @@ paths: "500": $ref: '#/components/responses/500' /api/downloads/{downloadId}/download: - get: # TODO: implement endpoint to actually do the download + get: operationId: download tags: - 4. Downloads @@ -891,8 +891,8 @@ paths: $ref: '#/components/responses/429' "500": $ref: '#/components/responses/500' - /api/users: # /api/users?username=kresnadi@budisantoso.de - get: # TODO: implement endpoint to get a user list + /api/users: + get: operationId: getUsers tags: - 5. Users @@ -923,7 +923,7 @@ paths: "500": $ref: '#/components/responses/500' /api/users/{userId}: - get: # TODO: implement endpoint to get a single user by id + get: operationId: getUserById tags: - 5. Users @@ -2077,7 +2077,7 @@ components: - PREVIEW - REDACTED - id: 8d8cae48-5c33-4617-ac27-1643f29b79d8 - name: RedactManager Example + name: Another RedactManager Example description: Typical settings for RedactManager. dateAdded: 2023-09-01T06:54:32.000+00:00 dateModified: 2023-09-01T06:54:32.000+00:00 @@ -2087,13 +2087,15 @@ components: validTo: 2033-12-31T23:59:59.999+00:00 dossierTemplateStatus: ACTIVE removeWatermark: true - keepImageMetadata: true + keepImageMetadata: false ocrByDefault: true keepHiddenText: true - keepOverlappingObjects: true + keepOverlappingObjects: false applyDictionaryUpdatesToAllDossiersByDefault: false downloadFileTypes: - ORIGINAL + - PREVIEW + - REDACTED properties: dossierTemplates: description: Each entry is a dossier template with its details. -- 2.47.2 From d516239c0ffa1576bd38daad0dc43ad8af5902bb Mon Sep 17 00:00:00 2001 From: Kresnadi Budisantoso Date: Fri, 24 May 2024 11:29:19 +0200 Subject: [PATCH 10/11] Added download endpoints to DocuMine spec to make the DocuMine API a superset of the RedactManager API. --- .../src/main/resources/api/documine.yaml | 389 +++++++++++++++++- .../src/main/resources/api/redactmanager.yaml | 22 +- 2 files changed, 393 insertions(+), 18 deletions(-) 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 -- 2.47.2 From 8b14d0f2dc71fd3463757f0d317aa0f7d84180c3 Mon Sep 17 00:00:00 2001 From: Kresnadi Budisantoso Date: Fri, 24 May 2024 11:38:56 +0200 Subject: [PATCH 11/11] Added missing quotes to response codes to keep the file consistent. --- .../src/main/resources/api/documine.yaml | 4 ++-- .../src/main/resources/api/redactmanager.yaml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) 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 5c17507fb..c8b7784bf 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 @@ -1142,7 +1142,7 @@ paths: parameters: - $ref: '#/components/parameters/username' responses: - 200: + "200": content: application/json: schema: @@ -1167,7 +1167,7 @@ paths: description: | This endpoint facilitates to retrieve a specific user. responses: - 200: + "200": content: application/json: schema: 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 c95c3def8..9cd097d79 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 @@ -908,7 +908,7 @@ paths: parameters: - $ref: '#/components/parameters/username' responses: - 200: + "200": content: application/json: schema: @@ -933,7 +933,7 @@ paths: description: | This endpoint facilitates to retrieve a specific user. responses: - 200: + "200": content: application/json: schema: -- 2.47.2