From 64f519f100e2a168a2b4f2116a06c171f1e4b541 Mon Sep 17 00:00:00 2001 From: Kresnadi Budisantoso Date: Thu, 6 Jun 2024 12:30:29 +0200 Subject: [PATCH] RED-9225 / RED-9114 RedactManager API Specs for BASF - Added possibility to retrieve the available report templates Additionally: * Added `approverIds` to `DossierRequest` schema * Harmonized some descriptions between RedactManager and DocuMine specs --- .../src/main/resources/api/documine.yaml | 111 ++++++++++++++++-- .../src/main/resources/api/redactmanager.yaml | 109 +++++++++++++++-- 2 files changed, 198 insertions(+), 22 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 ae26de2cf..f1e20977e 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 @@ -850,6 +850,37 @@ paths: $ref: '#/components/responses/429' "500": $ref: '#/components/responses/500' + /api/dossier-templates/{dossierTemplateId}/report-templates: + get: + summary: Returns the list of all available report templates + tags: + - 1. Dossier Templates + description: | + Use this endpoint to retrieve a collection of report templates associated with a specific dossier template. Each report + template includes details such as the report's name, whether the report is per file or for multiple files, and if the UI + should pre-select it in a download dialog. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + responses: + "200": + content: + '*/*': + schema: + $ref: '#/components/schemas/ReportTemplateList' + 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 @@ -2657,7 +2688,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 component extractions." + example: "Dossiers with this status should only contain approved files and indicate that the users have completed working on it." rank: format: int32 type: integer @@ -2790,24 +2821,24 @@ components: FileAttributeDisplaySettings: type: object description: | - Display setting for the DocuMine user interface. These settings control how the UI handles and presents the file attributes. + Display setting for the user interface. These settings control how the UI handles and presents the file attributes. properties: primaryAttribute: type: boolean description: | - If `true`, the DocuMine user interfaces show the value of the file attribute in the file list below the file name. + If `true`, the user interfaces show the value of the file attribute in the file list below the file name. editable: type: boolean description: | - If `true`, the DocuMine user interfaces allow manual editing of the value. Otherwise only importing and setting by rules would be possible. + If `true`, the 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 DocuMine user interfaces add filter options to the file list. + If `true`, the user interfaces add filter options to the file list. displayedInFileList: type: boolean description: | - if `true`, the DocuMine user interfaces show the values in the file list. + if `true`, the user interfaces show the values in the file list. required: - primaryAttribute - editable @@ -2836,7 +2867,7 @@ components: dossierCount: 3 - 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." + description: "Dossiers with this status should only contain approved files and indicate that the users have completed working on it." rank: 1 color: "#5eb160" dossierCount: 42 @@ -2927,6 +2958,52 @@ components: filenameMappingCsvColumnHeader: "Filename" delimiter: "," encoding: "UTF-8" + ReportTemplate: + type: object + description: | + This object contains details about a report template. + properties: + id: + type: string + format: uuid + description: | + A unique identifier for the report template. This ID is automatically generated by + the system upon creation and is used for referencing the report template in API calls. + example: "123e4567-e89b-12d3-a456-426614174000" + name: + type: string + description: | + The name of the report template. + example: "Summary Report" + createdOn: + type: string + format: date-time + description: | + The date when the report template was uploaded. This is automatically set by the system upon the report template record creation. + example: "2000-01-23T04:56:07.000+00:00" + multiFile: + type: boolean + description: | + A toggle that indicates if a report applies to multiple files: If `false` (default), a separate report file is generated for each file that was + selected for creating a report. If `true`, a single report file is generated containing the information for all selected files. + example: true + preSelect: + type: boolean + description: | + An indicator for the user interface if the report should be pre-selected in the "create dossier" dialog: If `false` (default), the report should not + be pre-selected. If `true`, the UI should pre-select the report, i.e. the create dossier request should be populated with the identifier of this + report template. + example: false + required: + - name + ReportTemplateList: + type: object + description: A list of report templates. + properties: + reportTemplates: + items: + $ref: '#/components/schemas/ReportTemplate' + type: array ReportTemplateIdList: type: array items: @@ -3216,6 +3293,17 @@ components: type: string description: A unique identifier for a member with access to the dossier. uniqueItems: true + approverIds: + type: array + description: | + An array of unique identifiers for users who have approval permission in the dossier. Needed if using an approval workflow. + + > **Note:** The DocuMine application does not have an approval workflow and this **list can be left empty**. However, every member will be + > elevated to a privileged member to ensure full functionality. + items: + type: string + description: A unique identifier for a member with approval permission. + uniqueItems: true reportTemplateIds: $ref: "#/components/schemas/ReportTemplateIdList" dossierStatusId: @@ -3235,6 +3323,7 @@ components: - a0044ae9-ddca-4f97-b0a1-3cb2517dbf39 - c2e33246-e50a-4c43-831c-6789a5637db8 - 6123fa16-6943-4b74-8524-54b0046a0ce6 + approverIds: [] reportTemplateIds: - daadea5f-917b-482a-b7d2-e65afe8f80ca - 8130acf6-4910-4123-827c-caacd8111402 @@ -4202,7 +4291,7 @@ components: filename: type: string description: The name of the download file. - example: my-component-dossier.zip + example: my-dossier.zip mimeType: type: string description: The mime type of the download file. @@ -4212,7 +4301,7 @@ components: 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. + bug report if the error occurs repeatedly and indicates a general problem with the application. example: "" status: type: string @@ -4228,7 +4317,7 @@ components: - `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. + for a certain period. This period can be configured in the settings of your workspace. - `FAILED` - An error occurred while preparing the download. The `errorCause` field might contain additional details on the error. example: READY @@ -4333,7 +4422,7 @@ components: type: array description: | The roles of the user. In particular: - - `USER` - default user permission to work with DocuMine + - `USER` - default user permission to work with the application - `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 77cf14b2c..dd0fa68bc 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 @@ -219,6 +219,37 @@ paths: $ref: '#/components/responses/429' "500": $ref: '#/components/responses/500' + /api/dossier-templates/{dossierTemplateId}/report-templates: + get: + summary: Returns the list of all available report templates + tags: + - 1. Dossier Templates + description: | + Use this endpoint to retrieve a collection of report templates associated with a specific dossier template. Each report + template includes details such as the report's name, whether the report is per file or for multiple files, and if the UI + should pre-select it in a download dialog. + parameters: + - $ref: '#/components/parameters/dossierTemplateId' + responses: + "200": + content: + '*/*': + schema: + $ref: '#/components/schemas/ReportTemplateList' + 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 @@ -1414,7 +1445,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 working on it." rank: format: int32 type: integer @@ -1547,24 +1578,24 @@ components: FileAttributeDisplaySettings: type: object description: | - Display setting for the RedactManager user interface. These settings control how the UI handles and presents the file attributes. + Display setting for the 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. + If `true`, the 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. + If `true`, the 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. + If `true`, the 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. + if `true`, the user interfaces show the values in the file list. required: - primaryAttribute - editable @@ -1593,7 +1624,7 @@ components: dossierCount: 3 - 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." + description: "Dossiers with this status should only contain approved files and indicate that the users have completed working on it." rank: 1 color: "#5eb160" dossierCount: 42 @@ -1684,6 +1715,52 @@ components: filenameMappingCsvColumnHeader: "Filename" delimiter: "," encoding: "UTF-8" + ReportTemplate: + type: object + description: | + This object contains details about a report template. + properties: + id: + type: string + format: uuid + description: | + A unique identifier for the report template. This ID is automatically generated by + the system upon creation and is used for referencing the report template in API calls. + example: "123e4567-e89b-12d3-a456-426614174000" + name: + type: string + description: | + The name of the report template. + example: "Summary Report" + createdOn: + type: string + format: date-time + description: | + The date when the report template was uploaded. This is automatically set by the system upon the report template record creation. + example: "2000-01-23T04:56:07.000+00:00" + multiFile: + type: boolean + description: | + A toggle that indicates if a report applies to multiple files: If `false` (default), a separate report file is generated for each file that was + selected for creating a report. If `true`, a single report file is generated containing the information for all selected files. + example: true + preSelect: + type: boolean + description: | + An indicator for the user interface if the report should be pre-selected in the "create dossier" dialog: If `false` (default), the report should not + be pre-selected. If `true`, the UI should pre-select the report, i.e. the create dossier request should be populated with the identifier of this + report template. + example: false + required: + - name + ReportTemplateList: + type: object + description: A list of report templates. + properties: + reportTemplates: + items: + $ref: '#/components/schemas/ReportTemplate' + type: array ReportTemplateIdList: type: array items: @@ -1970,6 +2047,14 @@ components: type: string description: A unique identifier for a member with access to the dossier. uniqueItems: true + approverIds: + type: array + description: | + An array of unique identifiers for users who have approval permission in the dossier. Needed if using an approval workflow. + items: + type: string + description: A unique identifier for a member with approval permission. + uniqueItems: true reportTemplateIds: $ref: "#/components/schemas/ReportTemplateIdList" dossierStatusId: @@ -1989,6 +2074,8 @@ components: - a0044ae9-ddca-4f97-b0a1-3cb2517dbf39 - c2e33246-e50a-4c43-831c-6789a5637db8 - 6123fa16-6943-4b74-8524-54b0046a0ce6 + approverIds: + - a0044ae9-ddca-4f97-b0a1-3cb2517dbf39 reportTemplateIds: - daadea5f-917b-482a-b7d2-e65afe8f80ca - 8130acf6-4910-4123-827c-caacd8111402 @@ -2744,7 +2831,7 @@ components: filename: type: string description: The name of the download file. - example: my-redacted-dossier.zip + example: my-dossier.zip mimeType: type: string description: The mime type of the download file. @@ -2754,7 +2841,7 @@ components: 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. + bug report if the error occurs repeatedly and indicates a general problem with the application. example: "" status: type: string @@ -2770,7 +2857,7 @@ components: - `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. + for a certain period. This period can be configured in the settings of your workspace. - `FAILED` - An error occurred while preparing the download. The `errorCause` field might contain additional details on the error. example: READY @@ -2875,7 +2962,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 the application - `MANAGER` - additional privileges to create and manage dossiers - `USER_ADMIN` - administration privileges limited to manage users only - `ADMIN` - general administration privileges -- 2.47.2