From 8a4560f3a1fd8d70584c43637f6e43ffe45469d7 Mon Sep 17 00:00:00 2001 From: Phil Schneider Date: Mon, 7 Oct 2024 12:54:57 +0200 Subject: [PATCH] docs: add documentation to add policies and attributes * adjust documentation structure to align with TRG1 * add documentation to add policies and policy attributes Refs: #178 #197 --- .github/pull_request_template.md | 2 +- README.md | 4 +- charts/policy-hub/README.md | 2 +- charts/policy-hub/README.md.gotmpl | 2 +- docs/README.md | 20 +++ docs/admin/Admin_Guide.md | 14 ++ docs/admin/add-policies/add-policies.md | 142 ++++++++++++++++++ .../dev-process/Dev-flow_deploy-dev-env.md | 0 .../dev-process/Dev-flow_git-diagram.md | 0 .../dev-process/Enumeration Handling.md | 0 .../dev-process/How to contribute.md | 0 .../known-issues-and-limitations.md | 2 +- .../release-process/Release Process.md | 2 +- docs/api/API_Doc.md | 19 +++ .../postman}/example-requests.md | 2 +- .../policy-hub.postman_collection.json | 0 .../02_architecture_constraints.md} | 0 .../03_system_scope_and_context.md} | 2 +- .../04_solution_strategy.md} | 0 .../05_building_block_view.md} | 2 +- .../08_01_operational_concept.md} | 0 .../08_02_development_concept.md} | 2 +- .../08_03_security_concept.md} | 6 +- docs/architecture/08_concepts.md | 15 ++ .../09_quality_requirements.md} | 2 +- docs/architecture/Index.md | 21 +++ .../authentication/authentication.md | 0 .../database/db-view.md | 0 .../database/seeding.md | 0 29 files changed, 246 insertions(+), 15 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/admin/Admin_Guide.md create mode 100644 docs/admin/add-policies/add-policies.md rename docs/{technical-documentation => admin}/dev-process/Dev-flow_deploy-dev-env.md (100%) rename docs/{technical-documentation => admin}/dev-process/Dev-flow_git-diagram.md (100%) rename docs/{technical-documentation => admin}/dev-process/Enumeration Handling.md (100%) rename docs/{technical-documentation => admin}/dev-process/How to contribute.md (100%) rename docs/{technical-documentation/known-knowns => admin}/known-issues-and-limitations.md (62%) rename docs/{technical-documentation => admin}/release-process/Release Process.md (98%) create mode 100644 docs/api/API_Doc.md rename docs/{technical-documentation/requests => api/postman}/example-requests.md (97%) rename docs/{technical-documentation/requests => api/postman}/policy-hub.postman_collection.json (100%) rename docs/{technical-documentation/architecture/Architecture Constraints.md => architecture/02_architecture_constraints.md} (100%) rename docs/{technical-documentation/architecture/Context and scope.md => architecture/03_system_scope_and_context.md} (97%) rename docs/{technical-documentation/architecture/Solution strategy.md => architecture/04_solution_strategy.md} (100%) rename docs/{technical-documentation/architecture/Whitebox Overall System.md => architecture/05_building_block_view.md} (96%) rename docs/{technical-documentation/architecture/operational-concept.md => architecture/08_01_operational_concept.md} (100%) rename docs/{technical-documentation/architecture/Development Concept.md => architecture/08_02_development_concept.md} (98%) rename docs/{technical-documentation/architecture/Security_Assessment.md => architecture/08_03_security_concept.md} (98%) create mode 100644 docs/architecture/08_concepts.md rename docs/{technical-documentation/architecture/Requirements.md => architecture/09_quality_requirements.md} (97%) create mode 100644 docs/architecture/Index.md rename docs/{technical-documentation => architecture}/authentication/authentication.md (100%) rename docs/{technical-documentation => architecture}/database/db-view.md (100%) rename docs/{technical-documentation => architecture}/database/seeding.md (100%) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index d24a08d1..4e481219 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -14,7 +14,7 @@ Link to Github issue. Please delete options that are not relevant. -- [ ] I have followed the [contributing guidelines](https://github.com/eclipse-tractusx/policy-hub/blob/main/docs/technical-documentation/dev-process/How%20to%20contribute.md) +- [ ] I have followed the [contributing guidelines](https://github.com/eclipse-tractusx/policy-hub/blob/main/docs/admin/dev-process/How%20to%20contribute.md) - [ ] I have performed [IP checks](https://eclipse-tractusx.github.io/docs/release/trg-7/trg-7-04#checking-libraries-using-the-eclipse-dash-license-tool) for added or updated 3rd party libraries - [ ] I have created and linked IP issues or requested their creation by a committer - [ ] I have performed a self-review of my own code diff --git a/README.md b/README.md index 4e2ec5f7..16d942a2 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ This repository contains the backend code for the Policy-Hub written in C#. -For **information about the policy hub**, please refer to the documentation, especially the context and scope section in the [architecture documentation](./docs/technical-documentation/architecture). +For **information about the policy hub**, please refer to the documentation, especially the context and scope section in the [architecture documentation](./docs/architecture). For **installation** details, please refer to the [README.md](./charts/policy-hub/README.md) of the provided helm chart. @@ -25,7 +25,7 @@ dotnet run ## Known Issues and Limitations -See [Known Knowns](/docs/technical-documentation/known-knowns/known-issues-and-limitations.md). +See [Known Knowns](/docs/admin/known-issues-and-limitations.md). ## Notice for Docker image diff --git a/charts/policy-hub/README.md b/charts/policy-hub/README.md index d545eddf..592e77df 100644 --- a/charts/policy-hub/README.md +++ b/charts/policy-hub/README.md @@ -2,7 +2,7 @@ This helm chart installs the Catena-X Policy Hub application. -For further information please refer to [Technical Documentation](../../docs/technical-documentation/). +For further information please refer to [Technical Documentation](../../docs/admin/). The referenced container images are for demonstration purposes only. diff --git a/charts/policy-hub/README.md.gotmpl b/charts/policy-hub/README.md.gotmpl index 4a27da79..ab72e52c 100644 --- a/charts/policy-hub/README.md.gotmpl +++ b/charts/policy-hub/README.md.gotmpl @@ -2,7 +2,7 @@ This helm chart installs the Catena-X Policy Hub application. -For further information please refer to [Technical Documentation](../../docs/technical-documentation/). +For further information please refer to [Technical Documentation](../../docs/admin/). The referenced container images are for demonstration purposes only. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..5c9692a8 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,20 @@ +# Introduction + +This repository provides the backend code for the Policy Hub. + +The following table links you to the respective documentations. + +| Documentation | Purpose | +| ----------------------------------------------------------------- | ---------------------------------------------------------------------- | +| [Arc42](architecture/Index.md) | Architecture Documentation for the Policy Hub. | +| [How to contribute](./admin/dev-process/How%20to%20contribute.md) | Information relevant, if you contribute in the policy hub development. | +| [Administration Guide](admin/Admin_Guide.md) | Information relevant, if you want to use the policy hub application. | +| [API Documentation](api/API_Doc.md) | Information about the endpoints. | + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/policy-hub diff --git a/docs/admin/Admin_Guide.md b/docs/admin/Admin_Guide.md new file mode 100644 index 00000000..48d9fac5 --- /dev/null +++ b/docs/admin/Admin_Guide.md @@ -0,0 +1,14 @@ +# Admin Guide + +## Getting started + +To start the application refer to the [Installation Guide](../../charts/policy-hub/README.md). +It provides information on deployment via helm. + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/policy-hub diff --git a/docs/admin/add-policies/add-policies.md b/docs/admin/add-policies/add-policies.md new file mode 100644 index 00000000..377529ea --- /dev/null +++ b/docs/admin/add-policies/add-policies.md @@ -0,0 +1,142 @@ +# Summary + +The following documentation gives an overview of how to add additional data to the Policy Hub. + +## Adding new Policies + +To add new policies the following steps must be executed: + +### Add Policy + +To add new Attributes you need to add an entry to the [policies](/src/database/PolicyHub.Migrations/Seeder/Data/policies.json) Seeding file. + +The entry should look like the following: + +```json + { + "id": "uuid for the policy, this is needed in the process later on", + "kind_id": "one of the policy kinds mentioned below (as number)", + "technical_key": "the technical key which is used to query it later in the process", + "description": "a description of the policy", + "is_active": "either true if the attribute should be active or false if the attribute shouldn't be active", + "attribute_key_id": "one of the attribute keys mentioned below (as number)", + }, +``` + +**PolicyKindId** + +```c# +public enum PolicyKindId +{ + BusinessPartnerNumber = 1, + Membership = 2, + Framework = 3, + Purpose = 4, + Dismantler = 5, + ContractReference = 6 +} +``` + +**Attribute Keys** + +```c# +public enum AttributeKeyId +{ + Regex = 1, + Static = 2, + DynamicValue = 3, + Brands = 4, + Version = 5 +} +``` + +### Assign policy to type + +The created policy must be assigned to at least one policy type. To assign the policy to a type you need to add an entry to the [policy_assigned_types](/src/database/PolicyHub.Migrations/Seeder/Data/policy_assigned_types.json) Seeding file. + +The entry should look like the following: + +```json +{ + "policy_id": "value of the id column of the newly added policy", + "policy_type_id": "one of the policy type ids mentioned below (as number)", + "is_active": "either true if the attribute should be active or false if the attribute shouldn't be active" +} +``` + +**PolicyTypeId** + +```c# +public enum PolicyTypeId +{ + Access = 1, + Usage = 2 +} +``` + +### Assign policy to use case + +The created policy must be assigned to at least one use case. To assign the policy to a use case you need to add an entry to the [policy_assigned_use_cases](/src/database/PolicyHub.Migrations/Seeder/Data/policy_assigned_use_cases.json) Seeding file. + +The entry should look like the following: + +```json +{ + "policy_id": "value of the id column of the newly added policy", + "use_case_id": "one of the use case ids mentioned below (as number)", + "is_active": "either true if the attribute should be active or false if the attribute shouldn't be active" +} +``` + +**UseCaseId** + +```c# +public enum UseCaseId +{ + Traceability = 1, + Quality = 2, + PCF = 3, + Behavioraltwin = 4, + Businesspartner = 5, + CircularEconomy = 6, + DemandCapacity = 7 +} +``` + +## Adding new Attributes + +To add new Attributes you need to add an entry to the [policy_attributes](/src/database/PolicyHub.Migrations/Seeder/Data/policy_attributes.json) Seeding file. + +The entry should look like the following: + +```json +{ + "id": "uuid", + "policy_id": "id of an policy you want to link the attribute to", + "key": "one of the attribute keys mentioned above (as number)", + "attribute_value": "the specific value of the attribute you want to set", + "is_active": "either true if the attribute should be active or false if the attribute shouldn't be active" +} +``` + +Depending on the attribute key which is set the output will slightly change. A regex Attribute will check the set value of a policy if it matches the regex. A dynamic value will take the user input of the value field. If non is set by the user `{dynamicValue}` is taken. For `Static`, `Brands` and `Version` Attributes the value will just render the content of the `attribute_value` column. + +To make a Attribute available it must be set to `is_active` = `true` and a link to a use case must be added. For that a new entry in the [policy_attribute_assigned_use_cases](/src/database/PolicyHub.Migrations/Seeder/Data/policy_attribute_assigned_use_cases.json) must be added. The entry should look like the following: + +```json +{ + "attribute_id": "value of the id column of the newly added policy_attribute", + "use_case_id": "one of the use case ids mentioned above (as number)", + "is_active": "either true if the attribute should be active or false if the attribute shouldn't be active" +} +``` + +It is possible to link an attribute to multiple UseCases. + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/policy-hub diff --git a/docs/technical-documentation/dev-process/Dev-flow_deploy-dev-env.md b/docs/admin/dev-process/Dev-flow_deploy-dev-env.md similarity index 100% rename from docs/technical-documentation/dev-process/Dev-flow_deploy-dev-env.md rename to docs/admin/dev-process/Dev-flow_deploy-dev-env.md diff --git a/docs/technical-documentation/dev-process/Dev-flow_git-diagram.md b/docs/admin/dev-process/Dev-flow_git-diagram.md similarity index 100% rename from docs/technical-documentation/dev-process/Dev-flow_git-diagram.md rename to docs/admin/dev-process/Dev-flow_git-diagram.md diff --git a/docs/technical-documentation/dev-process/Enumeration Handling.md b/docs/admin/dev-process/Enumeration Handling.md similarity index 100% rename from docs/technical-documentation/dev-process/Enumeration Handling.md rename to docs/admin/dev-process/Enumeration Handling.md diff --git a/docs/technical-documentation/dev-process/How to contribute.md b/docs/admin/dev-process/How to contribute.md similarity index 100% rename from docs/technical-documentation/dev-process/How to contribute.md rename to docs/admin/dev-process/How to contribute.md diff --git a/docs/technical-documentation/known-knowns/known-issues-and-limitations.md b/docs/admin/known-issues-and-limitations.md similarity index 62% rename from docs/technical-documentation/known-knowns/known-issues-and-limitations.md rename to docs/admin/known-issues-and-limitations.md index bad74432..f8ae7e79 100644 --- a/docs/technical-documentation/known-knowns/known-issues-and-limitations.md +++ b/docs/admin/known-issues-and-limitations.md @@ -1,6 +1,6 @@ # Known Issues and Limitations -- There is currently a discussion ongoing about the value types of PolicyKindId `ContractReference` that can be found [here](https://github.com/eclipse-tractusx/policy-hub/issues/186) +- There are currently no known issues nor limitations. ## NOTICE diff --git a/docs/technical-documentation/release-process/Release Process.md b/docs/admin/release-process/Release Process.md similarity index 98% rename from docs/technical-documentation/release-process/Release Process.md rename to docs/admin/release-process/Release Process.md index dc725dca..a3ff1c9c 100644 --- a/docs/technical-documentation/release-process/Release Process.md +++ b/docs/admin/release-process/Release Process.md @@ -33,7 +33,7 @@ Be aware that migrations coming release branches for release candidates or from The version needs to be updated in the `src` directory within the 'Directory.Build.props' file. -Also, bump the chart and app version in the [Chart.yaml](../../../charts/policy-hub/Chart.yaml) and the version of the images in the [values.yaml](../../../charts/policy-hub/values.yaml). +Also, bump the chart and app version in the [Chart.yaml](../../../charts/policy-hub/Chart.yaml) and the version of the images in the [values.yaml](../../../charts/charts/policy-hub/values.yaml). _Consortia relevant: Update the version of the targetRevision tag in the [argocd-app-templates](../../../consortia/argocd-app-templates/), used for consortia-environments._ diff --git a/docs/api/API_Doc.md b/docs/api/API_Doc.md new file mode 100644 index 00000000..d134affc --- /dev/null +++ b/docs/api/API_Doc.md @@ -0,0 +1,19 @@ +# API Documentation + +This document provides information on the endpoints. + +## OpenAPI Specifications + +There is an [OpenAPI 3.0.1 specification document](./hub-service.yaml) available. + +## Postman + +There is a [postman collection](./postman) containing information on how to provide master data and some basic data to test the application. + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation +- Source URL: https://github.com/eclipse-tractusx/policy-hub \ No newline at end of file diff --git a/docs/technical-documentation/requests/example-requests.md b/docs/api/postman/example-requests.md similarity index 97% rename from docs/technical-documentation/requests/example-requests.md rename to docs/api/postman/example-requests.md index b40485a9..27238da5 100644 --- a/docs/technical-documentation/requests/example-requests.md +++ b/docs/api/postman/example-requests.md @@ -217,7 +217,7 @@ Multiple constrains example: ``` -If you want to try it out, check the [postman collection](/docs/developer/Technical-Documentation/requests/policy-hub.postman_collection.json) +If you want to try it out, check the [postman collection](./policy-hub.postman_collection.json) ## NOTICE diff --git a/docs/technical-documentation/requests/policy-hub.postman_collection.json b/docs/api/postman/policy-hub.postman_collection.json similarity index 100% rename from docs/technical-documentation/requests/policy-hub.postman_collection.json rename to docs/api/postman/policy-hub.postman_collection.json diff --git a/docs/technical-documentation/architecture/Architecture Constraints.md b/docs/architecture/02_architecture_constraints.md similarity index 100% rename from docs/technical-documentation/architecture/Architecture Constraints.md rename to docs/architecture/02_architecture_constraints.md diff --git a/docs/technical-documentation/architecture/Context and scope.md b/docs/architecture/03_system_scope_and_context.md similarity index 97% rename from docs/technical-documentation/architecture/Context and scope.md rename to docs/architecture/03_system_scope_and_context.md index 414c379f..f3731266 100644 --- a/docs/technical-documentation/architecture/Context and scope.md +++ b/docs/architecture/03_system_scope_and_context.md @@ -1,4 +1,4 @@ -# Content and Scope +# System Context and Scope ## Business Context diff --git a/docs/technical-documentation/architecture/Solution strategy.md b/docs/architecture/04_solution_strategy.md similarity index 100% rename from docs/technical-documentation/architecture/Solution strategy.md rename to docs/architecture/04_solution_strategy.md diff --git a/docs/technical-documentation/architecture/Whitebox Overall System.md b/docs/architecture/05_building_block_view.md similarity index 96% rename from docs/technical-documentation/architecture/Whitebox Overall System.md rename to docs/architecture/05_building_block_view.md index a6725788..ef87a75e 100644 --- a/docs/technical-documentation/architecture/Whitebox Overall System.md +++ b/docs/architecture/05_building_block_view.md @@ -1,4 +1,4 @@ -# Whitebox Overall System +# Building Block View ## Summary diff --git a/docs/technical-documentation/architecture/operational-concept.md b/docs/architecture/08_01_operational_concept.md similarity index 100% rename from docs/technical-documentation/architecture/operational-concept.md rename to docs/architecture/08_01_operational_concept.md diff --git a/docs/technical-documentation/architecture/Development Concept.md b/docs/architecture/08_02_development_concept.md similarity index 98% rename from docs/technical-documentation/architecture/Development Concept.md rename to docs/architecture/08_02_development_concept.md index e99e60f1..9307fce9 100644 --- a/docs/technical-documentation/architecture/Development Concept.md +++ b/docs/architecture/08_02_development_concept.md @@ -2,7 +2,7 @@ ## Build, test, deploy -Details to the build, test and deploy process can get found under the following md file: [Release Process](/docs/technical-documentation/release-process/Release%20Process.md) +Details to the build, test and deploy process can get found under the following md file: [Release Process](/docs/admin/release-process/Release%20Process.md) ## Development Guidelines diff --git a/docs/technical-documentation/architecture/Security_Assessment.md b/docs/architecture/08_03_security_concept.md similarity index 98% rename from docs/technical-documentation/architecture/Security_Assessment.md rename to docs/architecture/08_03_security_concept.md index 2e1328d0..c3cb3731 100644 --- a/docs/technical-documentation/architecture/Security_Assessment.md +++ b/docs/architecture/08_03_security_concept.md @@ -1,4 +1,4 @@ -# Security Assessment Policy-Hub +# Security Assessment Policy-Hub | | | | ------------------------- | -------------------------------------------------------------------------------------------------------- | @@ -57,7 +57,7 @@ flowchart LR ### Changes compared to last Security Assessment * upgrade to .NET 8 -* new seeding data +* new seeding data ### Features for Upcoming Versions @@ -69,7 +69,7 @@ All potential threats discussed during the assessment were already mitigated. ### Mitigated Threats -N/A +N/A ### Performed Security Checks diff --git a/docs/architecture/08_concepts.md b/docs/architecture/08_concepts.md new file mode 100644 index 00000000..4185213c --- /dev/null +++ b/docs/architecture/08_concepts.md @@ -0,0 +1,15 @@ +# Cross-cutting Concepts + +## Table of Content + +- [Operational concepts](./08_01_operational_concept.md) +- [Developer concepts](./08_02_development_concept.md) +- [Security Concept](./08_03_security_concept.md) + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +- SPDX-License-Identifier: Apache-2.0 +- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation +- Source URL: