+
+Beyond this view, the portal allows for component integration of other (sub-products) that need to expose user-faced ui-functionality to the Catena-X community members (company and user level).
+
+Currently integrated (or in the process of being integrated) products are:
+
+* Semantic Hub
+* BPDM
+* Self-Description Factory
+* Clearing House / Gaia-X
+* Digital Twin Registry
diff --git a/developer/Technical Documentation/Architecture/Context and scope.md b/developer/Technical Documentation/Architecture/Context and scope.md
new file mode 100644
index 000000000..2df603e3e
--- /dev/null
+++ b/developer/Technical Documentation/Architecture/Context and scope.md
@@ -0,0 +1,8 @@
+# Content and Scope
+
+## Business Context
+Any uses-case, value stream, function within Catena-X can be exposed an accessed via the portal. It builds the foundation for x-company interaction and collaboration and further provides access to the overall value proposition of Catena-X.
+
+## Technical Context
+The provided components (see building block view) comprise the technical foundation for interaction, integration, authentication, authorization, provisioning, monitoring, auditing and further functionalities. They are state of the art in terms of technology portfolio, consist of open-source components whenever possible and are open-sourced themselves 100%.
+
diff --git a/developer/Technical Documentation/Architecture/Development Concept.md b/developer/Technical Documentation/Architecture/Development Concept.md
new file mode 100644
index 000000000..a561faf42
--- /dev/null
+++ b/developer/Technical Documentation/Architecture/Development Concept.md
@@ -0,0 +1,31 @@
+# Development Concept
+
+## Build, test, deploy
+Details to the build, test and deploy process can get found under following link/md file:
+https://github.com/catenax-ng/tx-portal-assets/blob/945546d91065b8870aa8f69ce94b48eac7a5ade2/docs/Release-Process.md
+
+
+
+
+
+
++ + +To start storing events you’ll need to turn the Save Events switch to on under the Login Events Settings. +
+
+ +Save Events + +
+ + +The Saved Types field allows you to specify which event types you want to store in the event store. The Clear events button allows you to delete all the events in the database. The Expiration field allows you to specify how long you want to keep events stored. Once you’ve enabled storage of login events and decided on your settings, don’t forget to click the Save button on the bottom of this page. +
+ +To view events, go to the Login Events tab. +
+
+ +Login Events + +
+ +As you can see, there’s a lot of information stored and, if you are storing every event, there are a lot of events stored for each login action. The Filter button on this page allows you to filter which events you are actually interested in. +
+
+ +Login Event Filter + +
+ + +In this screenshot, we’re filtering only Login events. Clicking the Update button runs the filter. + +###### Event Types +Login events: + +* Login - A user has logged in. +* Register - A user has registered. +* Logout - A user has logged out. +* Code to Token - An application/client has exchanged a code for a token. +* Refresh Token - An application/client has refreshed a token. +
+
+ +Account events: + +* Social Link - An account has been linked to a social provider. +* Remove Social Link - A social provider has been removed from an account. +* Update Email - The email address for an account has changed. +* Update Profile - The profile for an account has changed. +* Send Password Reset - A password reset email has been sent. +* Update Password - The password for an account has changed. +* Update TOTP - The TOTP settings for an account have changed. +* Remove TOTP - TOTP has been removed from an account. +* Send Verify Email - An email verification email has been sent. +* Verify Email - The email address for an account has been verified. + +For all events there is a corresponding error event. + + +##### Log Files +Per default keycloak logs are configured to only log on INFO level, to get a detailed logging, the log level need to get updated. + +2 options are available to adjust the logging level in the logs: + + Option1: Change the log level of the org.keycloak.events category logger + With this approach, you add an entry in the logging subsystem of the underlying Wildfly configuration. The new entry tells the logging subsystem to print all log messages from the package org.keycloak.events with DEBUG level and above to the log output: + + /subsystem=logging/logger=org.keycloak.events/:add(category=org.keycloak.events,level=DEBUG) + + + Option2: Configure the jboss-logging listener to log on other levels + As per default, there is no eventsListener SPI config in the Keycloak server configuration. The default behaviour for the jboss-logging events listener is the one which is implemented in the code. To be able to change the configuration of the jboss-logging listener, you’ll have to create the proper SPI node in the keycloak-server subsystem first, then add the desired log levels. + + /subsystem=keycloak-server/spi=eventsListener:add + /subsystem=keycloak-server/spi=eventsListener/provider=jboss-logging:add(enabled=true) + /subsystem=keycloak-server/spi=eventsListener/provider=jboss-logging:write-attribute(name=properties.success-level,value=info) + /subsystem=keycloak-server/spi=eventsListener/provider=jboss-logging:write-attribute(name=properties.error-level,value=warn) + Now the SUCCESS-events will occur in the log output with level INFO, as soon as they are emitted by Keycloak. +
+
+ +## Event Listener +Event listeners listen for events and perform an action based on that event. There are two built-in listeners that come with Keycloak: Logging Event Listener and Email Event Listener. +The Logging Event Listener writes to a log file whenever an error event occurs and is enabled by default. Here’s an example log message: +
+ +11:36:09,965 WARN [org.keycloak.events] (default task-51) type=LOGIN_ERROR, realmId=master, + clientId=myapp, + userId=19aeb848-96fc-44f6-b0a3-59a17570d374, ipAddress=127.0.0.1, + error=invalid_user_credentials, auth_method=openid-connect, auth_type=code, + redirect_uri=http://localhost:8180/myapp, + code_id=b669da14-cdbb-41d0-b055-0810a0334607, username=admin +
+ +This logging is very useful if you want to use a tool like Fail2Ban to detect if there is a hacker bot somewhere that is trying to guess user passwords. You can parse the log file for LOGIN_ERROR and pull out the IP Address. Then feed this information into Fail2Ban so that it can help prevent attacks. +
+ +The Email Event Listener sends an email to the user’s account when an event occurs. The Email Event Listener only supports the following events at the moment: + +* Login Error +* Update Password +* Update TOTP +* Remove TOTP +
+ +To enable the Email Listener go to the Config tab and click on the Event Listeners field. This will show a drop down list box where you can select email. +You can exclude one or more events by editing the standalone.xml, standalone-ha.xml, or domain.xml that comes with your distribution and adding for example: + +
+
+ +Requirement +[] Default Password Policies are needed for every realm - the policies are set by Catena-X and identical for all realms +[] Password refresh every 90 days +[] Password length 15+ digits +[] Password characters: letters + minimum 1 number is mandatory +[] Password shouldn't be the same as the username or email +[] If the Password is getting reset by the user and is not fitting the password policies, a error message with a detailed error code will get shown +
+
+ +#### How to configure Password Policies + +Open Keycloak admin page, go to "Authentication" and open the "Password Policy" tab. +Click on the Add policy … to see the list of available password policies. + +
+ +Select the relevant policy and set the policy value by adding the relevant number. Important: only numbers are to be added, no letters. +After saving the policy, Keycloak login enforces the policy for new users. Existing users can still login with theire old password, but as soon as a password change request is getting triggered the new policies will take affect. + +Blacklisting passwords is possible via UTF-8 file, for Catena-X no blacklisting is planned so far. + +#### Implementation + +Password Policies are auto set (as per the definition mentioned above) for each company tenant. +With the new creation of an company tenant; the password policies are automatically configured for the respective realm inside the sharedIdP. +
+
+ +##Password Reset + +If Password reset is enabled, users are able to reset their credentials if they forget their password or lose their OTP generator. + +Requirement +[] Forgot Password option should be available for all users using Shared IdP +[] New Password needs to get validated against the configured Password Policies +[] Config needs to get automatically set whenever a new realm is getting created +
+
+ +#### How to configure Password Recovery + +Go to the Realm Settings left menu item, and click on the Login tab. Switch on the Forgot Password switch. + +
+ + +The new password will get send via email. + +The email text is fully configurable. How: extend or edit the theme associated with it. + +When the user clicks on the email link, they will be asked to update their password, and, if they have an OTP generator set up, they will also be asked to reconfigure this as well. Depending on the security requirements of your organization you may not want users to be able to reset their OTP generator through email. You can change this behavior by going to the Authentication left menu item, clicking on the Flows tab, and selecting the Reset Credentials flow. + +#### Implementation + +tbd + + + + +## 2-Factor-Auth + +Levels of Authentication + +- Level 0: Authentication by username and password only. No 2-factor-auth. +- Level 1: Authentication by username and password; plus additionally 2-factor-auth via Keycloak OTP +- Level 2: Authentication by username and password; plus additionally 2-factor-auth via configured webauth method + +|Level|Username + Password|2-Factor-Method|Customization|Security|Level (0 = low; 2 = high)|Support by CX +|0|||||0|not supported +|1|||||2|available +|2|||||2|available + + + +#### Setup for Catena-X + +Keycloak 2-Factor-Auth is suggested for all users/identities which are managed by Catena-X and not federated by any company identity management system. + +##### Config for the Master Realm + +The Master realm, holding the admin accounts, is configured to + +* Each User needs to mandatorily configure OTP +* Each User needs to mandatorily update the password after the first login +* Password policies as per chapter PasswordPolicies need to get followed +
+ +##### Config for the Catena-X Realm + +tbd +
+
+ +##### Config for the Company Spec. Realm + +The Shared Company realm, holding the user accounts for the company, is configured as following + +* Each User needs to mandatorily configure OTP +* Each User needs to mandatorily update the password after the first login +* Password policies as per chapter PasswordPolicies need to get followed + + +#### How to Setup - Yubikey as 2-Fact-Auth + +The IdP, where the user is stored/created (for SharedIdP Companies its the SharedIdP; for CX Operators its the CentralIdP as well as the SharedIdP) an authentication flow need to get configured. + +##### #1 Create New Auth Flow as shown below + +
+ + +##### #2 Set the Auth Flow as browser flow + +
+ + +##### #3 Update the Required Actions + +
diff --git a/developer/Technical Documentation/Interface Contracts/BPDM (2).md b/developer/Technical Documentation/Interface Contracts/BPDM (2).md new file mode 100644 index 000000000..4fc767153 --- /dev/null +++ b/developer/Technical Documentation/Interface Contracts/BPDM (2).md @@ -0,0 +1,56 @@ +# Business Partner Data Management +
+ +## Interface Summary + +Business Partner Data of all business partners stored inside the catena-x data pool get visually displayed inside the partner network. +This document describes the details of the interface spec between BPDM and Portal product. +
+
+ +## Architecture Overview +
+
++
+ +## Description of the functional interface (WHAT) +Display business partner data via the partner network. +
+
+ +## Description of the physical interfaces (HOW) +
+n/a +
+
+ +### Get Business Partner data +
+ +```diff +! GET /api/catena/legal-entities/legal-addresses/search +``` + +#### Data Mapping for Company Data + +to be added + +
+
+ +#### Get Membership Flag +The endpoint provides all business partner numbers of those comapny records; where the company status is "ACTIVE" (means: company is part of the catena-x network). +Those bpns are mapped with the GET Business Partner Data response (see above) and a membership flag is added for matching companies inside the partner network user interface. +
+ +```diff +! GET /api/administration/partnernetwork/memberCompanies +``` + +#### Data Mapping for Company Data +to be added + +
+
+ diff --git a/developer/Technical Documentation/Interface Contracts/BPDM.md b/developer/Technical Documentation/Interface Contracts/BPDM.md new file mode 100644 index 000000000..164811071 --- /dev/null +++ b/developer/Technical Documentation/Interface Contracts/BPDM.md @@ -0,0 +1,73 @@ +# Business Partner Data Management +
+ +## Interface Summary + +BPDM Data Pool provides an API (Reference Data API) to lookup business partner data via REST endpoint "Lookup Business Partner". This endpoint provides access to several external data sources (trade registers, open data repositories, etc.) +
+API authentication is managed by API keys which is processed via HTTP header. This key manages also authorization, e.g., access to the CX data pool (instead of other community data). +
+
+For the registration process we are using the BPDM data call to pull the company basic data. +
+2 Options are available for the data pull +
+* Via Company Name (Level 2 - not yet implemented) +* Via BPN Number (BPN Generator: BPN Generator: Modes of Operation) +
+
+ +## Architecture Overview +To integrate the API into CX onboarding process, portal team just have to call the lookup REST endpoint and transform the response into a pick list for the portal user. +
+
++
+ +## Description of the functional interface (WHAT) +Retrieving company data from the CX mirror. +
+
+ +## Description of the physical interfaces (HOW) +
+
++
+ +### Service Call via BPN +
+ +```diff +! GET /api/catena/business-partner/{idValue} +``` + +
+ idValue: {BPN-Number}, + idType: BPN +
+
+ +#### Data Mapping for Company Data +
+ +|Data Field Name Portal|Data Field on CX Data Pool|Example| +|--------|--------|--------| +|BPN|"bpn": (first response line)|BPNL0MVP000000Q7| +|Organization Name|"names": [ { "value}]|German Car Factory| +|Registered Name |"names": [ { "value}]|German Car Factory| +|International Name |"names": [ { "value}]|German Car Factory| +|Street & House Number|addresses "country": [ { "technicalKey":}]|DE| +|Country|addresses "postCodes": [ { "value":}]|80809| +|Postal Code|addresses "localities": [ { "value":}]|Munich| + +
+
+ +### Service Call via CompanyName +
+currently not supported +
+
+ + diff --git a/developer/Technical Documentation/Interface Contracts/CX-Membership.md b/developer/Technical Documentation/Interface Contracts/CX-Membership.md new file mode 100644 index 000000000..875be5cec --- /dev/null +++ b/developer/Technical Documentation/Interface Contracts/CX-Membership.md @@ -0,0 +1,45 @@ +# CX-Membership + +## Interface / API / Service Summary +The membership discovery endpoint is used to display/retrieve all cx network members based on the bpn + +
+
+ +## Architecture Overview + +n/a + +
+
+ +## Implementation + +### #1 CX Membership Discovery +The cx membership discovery endpoint can get triggered via technical as well as real users, if relevant roles are available. +For technical user, a company can request the user creation via the link to technical user creation. +For details, click following link: +[Technical User Management](/docs/User%20Management/Technical_User/HowTo) +
+ +```diff +! GET api/administration/partnernetwork/memberCompanies +``` + +###### Request Body + +n/a + +###### Response Body + +the string response includes all bpn's of active network members + + [ + "string" + ] + +
+the string response includes all bpn's of active network members + +
+
diff --git a/developer/Technical Documentation/Interface Contracts/Dataspace-Discovery.md b/developer/Technical Documentation/Interface Contracts/Dataspace-Discovery.md new file mode 100644 index 000000000..b7f81fd11 --- /dev/null +++ b/developer/Technical Documentation/Interface Contracts/Dataspace-Discovery.md @@ -0,0 +1,53 @@ +# Dataspace Discovery + +## Interface / API / Service Summary +The EDC / dataspace discovery interface is a CX network public available endpoint which can get used to retrieve edc endpoints and the related BPNs, as well as search for endpoints via the BPN + +
+
+ +## Architecture Overview + +n/a + +
+
+ +## Implementation + +### #1 EDC Discovery +The edc discovery endpoint can get triggered via technical as well as real users, if relevant roles are available. +For technical user, a company can request the user creation with the technical user creation feature inside the portal. +For details, click following link: +[Technical User Management](/docs/User%20Management/Technical_User/HowTo) +
+ +```diff +! POST: /api/administration/connectors/discovery +``` + +###### Request Body +The request body is expecting a list of BPNs for which the EDC endpoint should get be fetched. Please add minimum one BPN. +
+ + [ + "string" + ] + +###### Response Body + + [ + { + "bpn": "string", + "connectorEndpoint": [ + "string" + ] + } + ] + + +
+In case of an empty response, no edc is found for the requested BPNs + +
+
diff --git a/developer/Technical Documentation/Interface Contracts/Managed Wallets.md b/developer/Technical Documentation/Interface Contracts/Managed Wallets.md new file mode 100644 index 000000000..c3d66be57 --- /dev/null +++ b/developer/Technical Documentation/Interface Contracts/Managed Wallets.md @@ -0,0 +1,49 @@ +# Managed Wallets +
+ +## Interface Summary + +Wallets are the touchpoint of company/participant to SSI as the digital identity. Companies can interact with other actors in the network using their own identity on their wallet. +Since SSI Wallets are not yet common on company level, Catena-X decided to create CX managed wallets for membership companies. This wallets can be used to enable the benefits of SSI for a number of services. +
+The Portal / Managed Service connection is implemented in 2 functions +* Company Registration - initital wallet creation +* EDC Registration - EDC Self-Description creation +
+
+ +## Architecture Overview +
+### #1 Company Registration +
+
++
+ +### #2 Company Registration +
+
++
+ +## Authentication Flow / Details +
+
+
++
+ +## Description of the functional interface (WHAT) +Creation of a managed wallet for the newly registered legal person / company. +
+
+ +## Description of the physical interfaces (HOW) +With the /approvalRequest api, the managed wallet logic is triggered to create for the new member (based on the bpn) a new managed wallet. +
+
+ +## APIs +
+Endpoint: no specific endpoint, part of the portal internal logic, which will call the /selfdescription factory endpoint + diff --git a/developer/Technical Documentation/Interface Contracts/Offer-Autosetup.md b/developer/Technical Documentation/Interface Contracts/Offer-Autosetup.md new file mode 100644 index 000000000..69f222e68 --- /dev/null +++ b/developer/Technical Documentation/Interface Contracts/Offer-Autosetup.md @@ -0,0 +1,169 @@ +# Offer Autosetup + +## Interface / API / Service Summary +For the case of a service setup / app, where an autosetup is available, CX will offer a standardized interface to push the relevant information to the service provider, which can trigger the service setup, if relevant. +
+Following interfaces are relevant to enable the autosetup + +1. POST Service URL (Generic endpoint for service providers to store their autosetup - if available - url inside CX) +2. POST Service Request (Specific endpoint to trigger customer subscription) +3. POST Instance Details (Register service instance for customer inside CX) + +
+
+ +## Architecture Overview + +### #1 Highlevel Architecture picture + +
+
++
+ +### #2 Details + +
+
+ +## Implementation + +### #1 PUT Service URL +The PUT service url is enabling the service / app provider to store/hold the service partner / app partner autosetup url. +
+Logic: the service provider/app provider (must be an cx member) can trigger the endpoint to store the autosetup endpoint. +
+ +
+
++ +```diff +! PUT api/administration/serviceprovider/owncompany +``` + +With the first time calling the endpoint; the url will be set as app/service provider endpoint as a new data set. +With any further endpoint triggers; the existing record will get overwritten. Means; the app/service provider can have only one endpoint configured. + +
+
+ +### #2 POST Service Request +he service request (from the customer, to the provider) is getting stored and managed under this api. +
+ +```diff +! POST /api/services/{serviceId}/subscribe +``` + +
+This API will be used to trigger (if available) the service provider endpoint (stored under #1) with the following body +
+ + + [ + { + "customer" : + { + "organizationName": "companyName"[required] , + + "country": "company country alpha2code" [required], + + "email": "user email address which triggered the service" [required] + } + + "properties": + { + "bpnNumber": "bpn of the company" [required], + + "subscriptionId": "" [required], + + "serviceId": "" [required] + } + } + ] + + + +
+
+ +### #3 POST Service Instance +Post service request is used to create the customer service/app instance inside the portal db. +With the successful client/app instance creation on the portal side, the technical user for the AAS registry will get send within the response +
+ +Request Body +
+ + [ + { + requestId (service request id), + appUrl (service provider endpoint / client / app) + } + ] + +
+ +```diff +! POST: /api/services/autosetup +``` + +API Endpoint Logic + +* Validate if requestId is existing in app_subscription table +* Validate if user calling the endpoint is registered as service provider of the service/app +* Validate if the subscription is in status "PENDING" + * if yes, proceed + * if no, error +* Run client name creation (logic needed - similar like the service account logic implemented by Norbert; but in this case for the client itself) - ideally naming convention should be something like Cl-{AppName}-{CustomerName} +* Add app instance and client for the customer and app id in following tables + * iam_client table + * app_instance table +* Next, create the client in keycloak central IdP - setting + * Client ID: {client name defined by the service before} + * Access Type: {public, might get auto set, please check} + * Standard Flow Enabled: true + * Direct Access Grants Enabled: true + * Valid Redirect URIs: {url send via the request body, likely a "*" needs to get added} + * Web Origins: "+" + * Backchannel Logout Session Required: true + * Full Scope allowed: false + + +* now add roles to the same client by using the roles stored inside user_roles in the portal db and linked to the respective app for which the instance got created +* Create the technical user for the service, by creating another client with following settings + * Client ID: {ideally client name + prefix "sa-"} + * Access Type: {confidential} + * Standard Flow Enabled: false + * Direct Access Grants Enabled: false + * Service Accounts Enabled: true + * Backchannel Logout Session Required: true + + * Full Scope allowed: true + * Service Account Roles: select the service account role "Digital Twin Management" of the client "technical_roles_management" + +* add to the technical user the bpn as attribute (bpn of the customer) and the bpn mapper inside the client. Config see attachment +* store technical user data inside portal db => description "Technical User for app {app name} - {techUserRoleName}" +* Technical user to be mapped to the customer company id +* Back inside the portal db, update the service/app status in the app_subscription table from "PENDING" to "ACTIVE" +* Create Notifications + * customer notification to inform the customer company about the technical user creation via the service provider. (receiver: customer IT admin) + * customer notification to inform the customer company about the activated app/service (receiver: customer app requester, customer IT admin) + +
+ +Response Body +
+ + { + technicalUserId, + technical user secret + } + + +
+
+ + + diff --git a/developer/Technical Documentation/Interface Contracts/Self Description.md b/developer/Technical Documentation/Interface Contracts/Self Description.md new file mode 100644 index 000000000..c1c79c15d --- /dev/null +++ b/developer/Technical Documentation/Interface Contracts/Self Description.md @@ -0,0 +1,117 @@ +# Self Description +
+ +## Interface Summary +Gaia-X requires all providers to describe themselves and their service offerings using standardized, machine-readable metadata called Self-Descriptions. Such Self-Descriptions will for example include information like the address of a company, a specific service description or certificates and labels. +In the Catena-X context, those self-descriptions are implemented between the product Portal and SD Factory. +
+
+In the current implementation level, self-descriptions are considered in the following scenarios +
+* Onboarding / Registration of a company +* Registration of a connector +* Registration / Release of a new app or service +
+
+In the document details below, those interfaces are described / explained. +
+
+ +## Architecture Overview +
+
++
+ +## Description of the functional interface (WHAT) +The Portal - SD Factory Interface is used to generate signed self descriptions which are stored in json ld files. +The json ld file is supposed to get stored - for now normal db document storage linked to the self description owner (usually a company). +
+
+ +## Description of the physical interfaces (HOW) +Portal is pushing the self description via an REST API "POST" developed under the portal context. +Factory will receive the information and create the self-description with signature (with help of the wallet). +A response is getting send to the portal with an "content" section. The content section is getting stored as json file in the portal db. +
+
+ +## 1. Self Description Creation +For self descriptions, 2 different kinds of self descriptions are currently in scope. +Participants and services. In the section below both are explained. + +### 1.1 Participant (Type of SD is "LegalPerson") +The participant self description is getting auto triggered with the CX member approval. +Following data are getting submitted to the factory to create the participant self description. + + JSON Body + + "type": "LegalPerson", + + "registration_number": "application id of the company, in future unique identifier", + + “headquarter_country”: "use the alpha2code of the company identity", + + ”legal_country”: "use the alpha2code of the company identity", + + “bpn”: "company bpn", + + “issuer”: "Catena-X bpn", + + “holder”: "Company bpn" + +
+
+Endpoint: no specific endpoint, part of the portal internal logic, which will call the /selfdescription factory endpoint +
+
+ +### 1.2 Service (Type of SD is "ServiceOffering") +The service self description is currently only triggered for edcs with a limited content scope. +Following you can find the self description json. Same as for participant, there is no self-description endpoint available, the self description is triggered as part of an internal portal logic when registering the connector. + + JSON Body + + "type": "ServiceOffering", + + "providedBy": "participant sd document url", + + “aggregationOf”: "", + + ”termsAndConditions”: "link to AGB of Catena-X"; → to be clarified with Felix Gerbig (Werner Jost will request this), + + “policies”: "the policies declared in the EDC instance to be registered/onboarded" → to be clarified with Stefan Ettl (Werner Jost will request this), + + “issuer”: "Catena-X bpn", + + “holder”: "Company bpn" +
+
+Result: self description of the connector connected to the participant SD via the "provided_by" link. +The self description is stored inside the document table +
+
+ +## 2. Self Description Storage +Created self descriptions are stored against the company account inside the portal db "documents" with binary data. +The self-description can get published again when transferring the binary data into a json ld. +
+
+Storage logic: +* Documents are stored under a own document type "Self-Subscription..." +* With the storage of the document the status is set to "locked" => ensures that user can not easily delete it +* Connector SDs are additional linked to the respective connector, since a company could have multiple connectors +* User which triggered the SD creation is logged +
+
+ +## 3. Self Description Deletion +currently not supported +
+
+ +## 4. Self Description Discovery +currently not supported +
+
+ diff --git a/developer/Technical Documentation/Operations/Auditing.md b/developer/Technical Documentation/Operations/Auditing.md new file mode 100644 index 000000000..b7830b830 --- /dev/null +++ b/developer/Technical Documentation/Operations/Auditing.md @@ -0,0 +1,120 @@ +# Audit Logging + +For db audit logs, 2 generic approaches are used + + * PostgreSQL Session Logging (pgAudit) + * Application Logging +
+
+ +## PostgreSQL Session Logging (pgAudit) +
+PgAudit module is enabled for the portal db via the Bitnami PostgreSQL Image: +
+https://github.com/bitnami/bitnami-docker-postgresql#auditing +
+
+ +Following operations are audited: WRITE, DDL +WRITE: INSERT, UPDATE, DELETE, TRUNCATE, and COPY +DDL: CREATE, ALTER, and DROP schema objects +For a complete list of auditable operations see https://github.com/pgaudit/pgaudit#pgauditlog + +
+ +In addition the parameters time stamp with milliseconds, user name and database name are configured as log line prefixes. + +
+ +Future enhancements: Auditing logging on application side namely in the backend. The auditing on db level with pgAudit doesn't provide the information by which person specific user an operation was triggered because db operations are executed by our generic db users (for instance the 'portal'). + +
+ +## Application Audit Logging + +Application Audit Logging is implemented to fulfill and enable extended audit log functionalities for the CX portal. + +In the implementation the possibility of pgAudit extension and db table logging inside the postgreSQL was validated. + +Due to the functional requirement to enable serach, quick validations and audit traceability, the in-DB audit implementation got preferred. + +
+ +Implementation Details + +What: for each audit relevant table, an audit_tablename_version table is created and storing any original table INSERT, DELETE or UPDATE records. Important, we always store: + +- Who changed +- What +- When + +
+ + Why we use versioning for the audit tables? + + To ensure that an audit table is never modified, but only entries are added, we have introduced versioning for audit table. + + Each audit table has version suffix in the name, this corresponds to the name of the migration in which the audit table was added. + + See the example below for further information: + +
+ + How to enable an entity to be auditable in the code (Example: CompanyUser) + +1. The auditable entity needs to implement interface 'IAuditable' + public class CompanyUser : IAuditable + +2. Create Audit entity which should derive from the auditable entity and implement IAuditEntity + + public class AuditCompanyUser : CompanyUser, IAuditEntity + +3. Add DbSet in PortalDbContext for the newly created Entity + + public virtual DbSet
+ +Up: + + migrationBuilder.AddAuditTrigger
+ +Additional relevant information: + + (warning) If not already existing in the original table, a uuid and last_editor_id attribute need to get added to the original id. + (warning) whenever the original table attributes are changed (e.g. adding an attribute or deleting and attribute) the already existing audit table will be set to frozen and a new audit table is getting created. All new audit relevant records will be stored in the new audit table diff --git a/developer/Technical Documentation/Operations/Release-Process.md b/developer/Technical Documentation/Operations/Release-Process.md new file mode 100644 index 000000000..71700be78 --- /dev/null +++ b/developer/Technical Documentation/Operations/Release-Process.md @@ -0,0 +1,96 @@ +# Release Process + +The release process for a new version can roughly be divided in the following steps: + +* Preparation +* Build of a versioned image +* Release of a new helm chart version +* Merge upstream to eclipse-tractusx + +The process builds on the development flow which takes place within the forks from eclipse-tractusx, located in the catenax-ng organization. + +The relevant frontend repositories are the following: + +* https://github.com/catenax-ng/tx-portal-frontend +* https://github.com/catenax-ng/tx-portal-frontend-registration +* https://github.com/catenax-ng/tx-portal-assets + +The relevant backend repository is the following: +* https://github.com/catenax-ng/tx-portal-backend + +## Preparation + +It's recommended to do step 1-3 in one preparatory pull request to main, or dev respectively. + +#### 1. Update changelog file + +The changelog file tracks all notable changes since the last released version. +During development every developer should extend the changelog under the 'Unreleased' section when raising a pull request to main or dev. +Once a new version is ready to be released, the changelog of the version gets finalized and the release version gets set for the, up to then, unreleased changes. +In the released version, the changelog is structured as following: + +* Changes +* Features +* Technical Support +* Bug Fixes + +In case of breaking change, the breaking change will get highlighted with a breaking change tag =>  + +#### 2. Update dependencies file + +In order to have an up-to-date list, of the used third-party libraries, the dependencies file needs to be updated. + +For the frontend repositories this can be done by running the following statement: + +```bash +yarn licenses list > DEPENDENCIES +``` + +For the backend repository the dependencies file can be updated by running the following statements: + +```bash +dotnet list src package --include-transitive > DEPENDENCIES-PREP +cat DEPENDENCIES-PREP | grep ">" | grep -Pv "\s(Org|Microsoft|NuGet|System|runtime|docker|Docker|NETStandard)" | sed -E -e "s/\s+> ([a-zA-Z\.\-]+).+\s([0-9]+\.[0-9]+\.[0-9]+)\s*/nuget\/nuget\/\-\/\1\/\2/g" > DEPENDENCIES +awk -i inplace '!seen[$0]++' DEPENDENCIES +``` + +Only commit the updated dependencies file, not the 'DEPENDENCIES-PREP' file. + +#### 3. Version bump (frontend repos only) + +The version in the 'package.json' files needs to get bumped, the following statement can be used: + +```bash +yarn version +``` + +#### 4. Merge from dev into main branch + +The merge from dev into main, via pull request, needs to happen before releasing. +This is only necessary for repositories with a dev branch e.g., tx-portal-frontend and tx-portal-frontend-registration. + +## Build of a versioned image + +It's important to pull the latest state from main of every repository. +Then a tag for the released version (e.g. v0.10.0) needs to be created and pushed. +The push of the tag triggers the release workflow action (available in every repository) which creates the versioned image/s. + +## Release of a new helm chart version + +Once the versioned images are available, they can be referenced in the portal helm chart and a new version of the chart can be released. +The consortia specific helm chart is released from the 'helm environments' branch available in the https://github.com/catenax-ng/tx-portal-cd fork. +The official portal helm chart is released from the main branch of https://github.com/eclipse-tractusx/portal-cd. + +## Merge upstream to eclipse-tractusx + +Once a new version has been released, it should be merged upstream to eclipse-tractusx and tagged. + +The relevant frontend repositories are the following: + +* https://github.com/eclipse-tractusx/portal-frontend +* https://github.com/eclipse-tractusx/portal-frontend-registration +* https://github.com/eclipse-tractusx/portal-assets + +The relevant backend repository is the following: + +* https://github.com/eclipse-tractusx/portal-backend diff --git a/developer/Technical Documentation/Operations/test.md b/developer/Technical Documentation/Operations/test.md new file mode 100644 index 000000000..05a15c7b7 --- /dev/null +++ b/developer/Technical Documentation/Operations/test.md @@ -0,0 +1,27 @@ +## Summary + + +
+
+ +## Unit Tests + +Unit tests are available for backend and frontend components and getting automatically executed as part of the code commits inside the CX NG. + +
+
+ +## Test Automation + +Test Automation as part of functional e2e tests are planned for upcomming releases. +Currently all tests are manually handled. + +
+
+ +## Manual Tests + +Manual tests are executed and documented inside the Catena-X consortia. Currently, manual tests are not open source available. + +
+
diff --git a/developer/Technical Documentation/Services/Document_Management.md b/developer/Technical Documentation/Services/Document_Management.md new file mode 100644 index 000000000..4c2f38ae2 --- /dev/null +++ b/developer/Technical Documentation/Services/Document_Management.md @@ -0,0 +1,133 @@ +# Summary + +Inside the portal, we have a number of different places to + +* upload documents +* view documents +* delete documents + + +Documents can be templates, but also signed contracts The uploaded documents must be .pdf documents. +
+In the DB table we have differentiated between documents which are uploaded by a customer because the document is signed or used as legitimation and those kind of documents which are templates. +
+ +Example User Flow which is supported by the document controller: + +
+
++
+ +# Solution Details + +## Database + +Documents are managed inside the postgresql db. + +Mainly 4 tables are used for the documents itself + +* documents +* document_types +* document_status +* offer_assigned_documents +* agreement_assigned_documents + +
+ +
+
++
+ +## Document Storage + +The uploaded documents are getting stored in the postgresql db. +Its possible to change this in a later stage to another tool such as a document storage of any cloud provider or a network/local file store. Storing on dev and int the documents inside the db is providing the necessary flexibility by still considering document access limitations/security. + +
+
+ +## Document Deletion + +The document deletion is designed and implemented in a very limited functionality. The reason of the limitation is extremely relevant since the documents are mostly legal binding agreements, contracts or authentication certificates. +The deletion of legal binding documents will lead to an immense issue on the audit area, if not done carefully. +Based on the reasons above, the document deletion is handled in 2 different functions +
+ +* Deletion triggered by the enduser + The deletion triggered by the enduser is possible as long as the document is in status "PENDING". As soon as any other state is reached the deletion wont be possible anymore. + +* Deletion triggered by an automatic job running at a specific time (batch job) + Specific configured batch job running nigthly to delete INACTIVE documents with a certain age. + +
+
+ +## Document Storage Size + +Uploading documents is limited to 8MB. The configuration for the maximum file size is set in ingress (nginx). See the last line in the screenshot below: +
+ +
+
+Additionally document size validation on FE was implemented lately where the size depends on the process.
+Inside the registration sizes can be following:
++* Registration => up to 8MB +* App Release Process => up to 1MB +* etc. + +
+
+ +# Implementation Details + +## #1 Get Documents + +Documents can get retrieved in the registration and administration service backend for a specific application id. +
+ +```diff +! GET /api/registration/application/{applicationId}/documentType/{documentTypeId}/documents +``` + +
+
+ +## #2 POST Document + +Store documents inside the document table in portal. +Document will get stored with linkage to the user and document type. +
+ +```diff +! POST /api/registration/application/{applicationId}/documentType/{documentTypeId}/documents +``` + +```diff +! PUT: /api/apps/appreleaseprocess/updateappdoc/{appId}/documentType/{documentTypeId}/documents +``` + +
+
+ +## #3 Ad-Hoc Delete Documents + +As mentioned above, the deletion triggered by the enduser is possible as long as the document is in status "PENDING". As soon as any other state is reached the deletion wont be possible anymore. +
+ +```diff +! Delete: /api/registration/documents/{documentId} +``` + +
+
+ +## #4 Batch Delete Documents + +Scheduled deletion job, configurable to run overnight. + +
+
+ diff --git a/developer/Technical Documentation/Services/Email Templates.md b/developer/Technical Documentation/Services/Email Templates.md new file mode 100644 index 000000000..f96811107 --- /dev/null +++ b/developer/Technical Documentation/Services/Email Templates.md @@ -0,0 +1,106 @@ +# Email Templates + +## Summary +As part of the Catena-X shared services, a number of E-Mail messages are send to the customer / business partner. +On this page a summary is provided on which Email Templates are available and used + +* Email Service +* Email Templates +* E-Mail Frame Template +* E-Mail Invite for Registration +* E-Mail Invite additional Users +* E-Mail Submitted Registration & Next Steps +* E-Mail Welcome to Catena-X - Join the Network +* E-Mail Passwort Reset +* E-Mail Invite New User to Portal +* E-Mail Template implementations +
+
+GitHub Email Template Storage: https://github.com/tractusx-team-portal-onboarding/tractusx/tree/feature/CAX-portal/portal/code/tractus-x-portal/Email%20Template +
+
+ +## Email Service +Email templates implemented at Portal Backend side. Templates are prepared as a HTML file and emails sent via API upon corresponding business logic steps. +
+For development and test environments, a Catena-X email mailbox is available to send and receive emails. +The mailbox is managed by the portal team. If you have questions or want to use the service, please contact the PO Julia Jeroch +
+
+Currently the service is used by + +* Traceability (Markus Kreuz; Thomas Braun) +* Portal +
+
+ +## Email Templates + +### E-Mail Frame Template +currently under change +
+... +
+
+
+ +### E-Mail Invite for Registration +Email Trigger: Invite of a new Business Partner by the CX Admin +
+
+
++
+
+ +### E-Mail Invite additional Users +Email Trigger: Invite of a team member to the registration process by the company admin. +
+... +
+
+
+ +### E-Mail Submitted Registration & Next Steps +Email Trigger: User clicked "Submit" button in the last step of the Registration Flow +
+
++
+
+ +### E-Mail Welcome to Catena-X - Join the Network +Email Trigger: CX Admin has approved Company Registration request. +
+... +
+
+
+ +### E-Mail Passwort Reset +Email Trigger: Shared IdP User is selecting "Password reset" on the login screen +
+... +
+
+
+ +### E-Mail Invite New User to Portal +Email Trigger: Admin User is inviting inside the Portal User Management a new user into Catena-X +
+... +
+
+
+ + + + + + + + + + + + diff --git a/developer/Technical Documentation/Services/Multi Language.md b/developer/Technical Documentation/Services/Multi Language.md new file mode 100644 index 000000000..45aafe4da --- /dev/null +++ b/developer/Technical Documentation/Services/Multi Language.md @@ -0,0 +1,47 @@ +# Multi Language + +## Summary +Multi-Language support is planned for the Portal and Registration App in two languages +
+* English +* German +
+
+The multi language function is mainly implemented on front-end side via i18next. +
+I18next is an internationalization-framework for react and ideal to support multi language function in web applications. +
+
+ +i18next provides following add-ons: +* detect the user language +* load the translations +* optionally cache the translations +* extension, by using post-processing - e.g. to enable sprintf support + +=> get more details (https://www.i18next.com/overview/plugins-and-utils) +
+
+ + + +## Technical Implementation + +### Portal-Registration + +There is a locales folder in src which contains subfolders according to respective language codes as shown in the screenshot shared, like 'de'(German), 'en'(English). These folders contain the translation.json file used for translations. +
+
+
+We can add additional translation files if needed for any additional language.
++
+ +### CX-Portal + +Inside the CX Portal, the locales are divided by pages. +
+
++There is one main file holding the generic translation for often used items (e.g. "approval button", headlines,...) and a file for each specific page to translate not often used values. + diff --git a/developer/Technical Documentation/Services/Notifications.md b/developer/Technical Documentation/Services/Notifications.md new file mode 100644 index 000000000..0bdb7fcf0 --- /dev/null +++ b/developer/Technical Documentation/Services/Notifications.md @@ -0,0 +1,310 @@ +## Summary + +Notification Services are used to send messages to one or several users. Usually notification services are known as push services, where a system/application is pushing notifications to a mobile device of the user. +In CX, the idea of push notification to a mobile device is something which is currently not in scope of the implementation, however the initial service of notifications inside the portal is planned as an mvp for Release 2/3. + +
+
+ +## Architecture + +
+
++
+ +## Design + +##### Elements + +
+
+++ highlight messages which have read status "false"
+++ enable urls inside the message
+++ user navigation count is red, if messages with needed actions are unread
+
++ +##### WebApplication User Interface + +###### User Navigation + +Scenario 1 +If unread messages are "0" the notification icon wont show up. Instead only the user icon will be displayed + +
+
++ +Scenario 2 +If unread messages are > 0 AND the actionRequired are = 0; the user icon with notification "false" state will get displayed. Inside the notification count bubble the number of "unread" messages will be shown. + +
+
++ +Scenario 3 +If unread messages are > 0 AND the actionRequired are > 0; the user icon with notification "true" state will get displayed. Inside the notification count bubble the number of "actionRequired" messages will be shown. + +
+
++ +###### Notification Screen + +
+
++ +###### Filtering + +
+
++ +###### Deletion Process for "Action Required" Notifications + +
+
++ +
+
+ +## Implementation Details + +### Database + +
+
++ +Important: the notification message is not available/stored inside the database; instead the db is only storing message metadata and the actual message text is handled inside the FE translation file located in the following repo structure. +Front-End repo cx-portal/src/assets/locales/en/notification.json + +
+
+ +### #1 Get User Notification Count + +The get user notification count job is used to fetch the count of unread notifications, as soon as the user logs in to the CX Network. +Via the user token, all relevant information will get fetched from the portal db and getting displayed in the user account. +
+ +```diff +! GET /api/notification/count-details +``` + +
+
+ +### #2 Get User Notification Count-Details + +With the user notification details, read and unread count per filter can get fetched. +
+The endpoint is a pure calculation/counting of the different metadata found below: + +* read +* unread +* infoUnread +* offerUnread +* actionRequired +
+ +```diff +! GET /api/notification/count-details +``` + +
+
+ +### #3 Get User Notification Details + +The get user notification details is following the "get user notification count" job. +The details job will only run when the user is clicking on the notification sub-menu. +The endpoint supports pagination inside the metadata section. +
+ +Additionally the endpoint supports to + +* only get read messages +* only get unread messages +* get only a specific notification type +* get only due notifications +* sorting by date and read status +
+ +```diff +! GET /api/notification +``` + +
+ +Response Body +Please note, the "content" text is only an example, each service has its own content attributes defined. Details to the actual content can get found here: /notificationDetails + + { + "meta": { + "totalElements": ##, + "totalPages": ##, + "page": ##, + "contentSize": ## + }, + "content": [ + { + "id": "uuid", + "created": "date", + "typeId": "label", + "notificationTopic": "label", + "isRead": false or true, + "content": "{\"OfferId\":\"uuid\",\"CompanyName\":\"string\",\"OfferName\":\"string\"}", + "dueDate": null or date + } + ] + } + +
+
+ +### #4 PUT User Notification "read" / "unread" + +The user can select a notification inside the notification screen and put that notification to "read" or "unread". +This will impact the notification count of #1. Since #1 will only show those notification as "new" or "to be checked" notifications which are not set to "read" +
+ +```diff +! PUT /api/notification/read or /api/notification/read?notificationStatusId=UNREAD +! PUT /api/notification/read or /api/notification/read?notificationStatusId=READ +``` + +
+
+ +### #5 POST User notification + +The post user notification API is a input api only. Means its used in the current project phase to validate the notification service/behavior. +
+ +```diff +! POST /api/notification/{companyUserId:guid} +``` + +
+
+ +### #6 DELETE User notification + +With the delete user notification, a notification can get deleted. The function is triggered by the user himself and will be executed without any chance for notification recovery. +
+ +```diff +! DELETE /api/notification/{notificationId:guid} +``` + +
+
+ +### #7 Implemented Sorting feature + +User can sort results based on given sorting possibilities. The sorting will act jointly with the view component. +Means, if the user did selected the view "Info Only" and now wants to also sort the results; the sorting will get executed on the view "info only" and not on all notifications. +Therefore following endpoints are implemented: +
+ +###### VIEW ALL (inside the filter) +Newest first: {hostname}/api/Notification?page=0&size=15&onlyDueDate=true&sorting=DateDesc +Oldest first. {hostname}/api/Notification?page=0&size=15&sorting=DateAsc +Unread first: {hostname}/api/Notification?page=0&size=15&sorting=ReadStatusAsc + +
+ +###### VIEW APP (inside the filter) +Newest first: {hostname}/api/Notification?page=0&size=15¬ificationTopic=OFFER&sorting=DateDesc +Oldest first. {hostname}/api/Notification?page=0&size=15¬ificationTopic=OFFER&sorting=DateAsc +Unread first: {hostname}/api/Notification?page=0&size=15¬ificationTopic=OFFER&sorting=ReadStatusAsc + +
+ +###### VIEW Info (inside the filter) +Newest first: {hostname}/api/Notification?page=0&size=15¬ificationTopic=INFO&sorting=DateDesc +Oldest first. {hostname}/api/Notification?page=0&size=15¬ificationTopic=INFO&sorting=DateAsc +Unread first: {hostname}/api/Notification?page=0&size=15¬ificationTopic=INFO&sorting=ReadStatusAsc + +
+ +###### View Action Required (inside the filter) +Newest first: {hostname}/api/Notification?page=0&size=15 ¬ificationTopic=ACTION&sorting=DateDesc +Oldest first. {hostname}/api/Notification?page=0&size=15& notificationTopic=ACTION&sorting=DateAsc +Unread first: {hostname}/api/Notification?page=0&size=15& notificationTopic=ACTION&sorting=ReadStatusAsc + +
+
+ +### #8 Implemented Views + +.... +
+ +
+
++ +When the user is opening the page "All" is preselected and the notification as per the endpoint: +https://portal-backend.dev.demo.catena-x.net/api/Notification?page=0&size=15&sorting=DateDesc +
+ +When the user clicks on the view tag "app only" notification as per the endpoint are showing app: +https://portal-backend.dev.demo.catena-x.net/api/Notification?page=0&size=15¬ificationTopic=OFFER&sorting=DateDesc +
+ +When the user clicks on the view tag "info only" notification as per the endpoint are showing app: +https://portal-backend.dev.demo.catena-x.net/api/Notification?page=0&size=15¬ificationTopic=INFO&sorting=DateDesc +
+ +When the user clicks on the view tag "messaged with action required" notification as per the endpoint are showing app: +https://portal-backend.dev.demo.catena-x.net/api/Notification?page=0&size=15&onlyDueDate=true&sorting=DateDesc + +
+
+ +## Configuration + +### Notification Types / Messages + +#### Welcome +Welcome Messages, triggered by the api endpoint +* PUT api/administration/registration/application/{applicationId}/approveRequest + +1 | 2 | 3 | 4 | 5 +-------- | -------- | -------- | -------- | -------- +INFO | WELCOME | n/a | Triggered from the FE locales file
Welcome to the Catena-X Network. To easily get you onboarded, a number of notifications / onboarding steps have been defined. Please check your notifications and start the configuration of your company area inside the portal to have a network experience based on your need. | New Registered Company Admin +INFO | WELCOME_USE_CASES | n/a | Triggered from the FE locales file
The network is quite huge, we want to ensure that you can focus on your preferred use cases. Select your preferred use case from the table below. | New Registered Company Admin +INFO | WELCOME_SERVICE_PROVIDER | n/a | Triggered from the FE locales file
If you need a service provider to help you with setting up your dataspace or an EDC, just follow us to the Service Provider Marketplace LINK | New Registered Company Admin +INFO | WELCOME_CONNECTOR_REGISTRATION | n/a | Triggered from the FE locales file
You do not have any registered Connector so far – have a look at the connector offers and get your connector to participate. LINK | New Registered Company Admin +INFO | WELCOME_APP_MARKETPLACE | n/a | Triggered from the FE locales file
Get a first inside into available apps, just follow us to the marketplace for apps. LINK | New Registered Company Admin + +
+
+ +#### Offer Subscription +Offer Subscription Messages, triggered by the api endpoint + +* POST api/apps/{appID}/subscribe +* POST api/apps/{serviceID}/subscribe +* PUT api/apps/{appID}/subscription/company/{companyId}/activate +* ----autosetup---- + +1 | 2 | 3 | 4 | 5 +-------- | -------- | -------- | -------- | -------- +OFFER | APP_SUBSCRIPTION_REQUEST | OfferId: {offer.id}
CompanyName: {companies.name}
OfferName: {offer.name} | Triggered from the FE locales file
A new app subscription request was triggered by {requestorCompanyName}. Get in contact with {userEmail} to agree on the app usage and setup guidelines. As soon as this is done, you can activate the app for {requestorCompanyName} here: LINK | App Provider - User documented as "Sales Manager" +OFFER | APP_SUBSCRIPTION_ACTIVATION | OfferId: {offer.id} | Triggered from the FE locales file
App {AppName} go activated, you can now assign user permission to this app. LINK | App Subscription Requester +OFFER | SERVICE_SUBSCRIPTION_REQUEST | OfferId: {offer.id}
RequestorCompanyName: {companies.name}
AppName: {offer.name}
UserEmail: {company_user.mail}
AutoSetupExecuted: {status}
AutoSetupError: {status} | Triggered from the FE locales file
A new app subscription request was triggered by {requestorCompanyName}. Get in contact with {userEmail} to agree on the app usage and setup guidelines. As soon as this is done, you can activate the service for {requestorCompanyName} here: LINK | Service Provider - User documented as "Sales Manager" +?? | TECHNICAL_USER_CREATION | | Triggered from the FE locales file
??? | Service Subscription Requester +OFFER | SERVICE_SUBSCRIPTION_ACTIVATION | OfferId: {offer.id} | Triggered from the FE locales file | Service {ServiceName} go activated. Manage your subscriptions via the following service management panel: LINK | Service Subscription Requester + + +Missing inside the documentation: +* CONNECTOR_REGISTERED +* APP_RELEASE_REQUEST + + diff --git a/docs/04. App(s)/App Provider Management Board(s)/01. App Board.md b/docs/04. App(s)/App Provider Management Board(s)/01. App Board.md new file mode 100644 index 000000000..c5764bef2 --- /dev/null +++ b/docs/04. App(s)/App Provider Management Board(s)/01. App Board.md @@ -0,0 +1,44 @@ +# Summary + +The Page "App Overview" is accessible via the top main menu for app providers. + +The main focus / scope of the page is to enable app providers to manage their apps under the release process, inside the marketplace or inactive apps, as well as starting the release process for a complete new app. + +The page includes following functions + +* search +* filter +* trigger app registration (link to be added) + +
+
+ +# Function + +
+
++
+ +"Active" App +All apps in status "Active" are published on the marketplace and can get subscribed by an customer. +
+ +"In Progress" App +Apps currently in progress can get opened inside the app release process and further edited there. If you are happy with the app content; submit your app to get it published on the marketplace. + +
+ +"In Review" App +Apps which are in "In Review" are logged; please wait until the review is finished. + +
+ +"Inactive" App +Apps which are in "Inactive" have been deactivated by the app owner and are not available anymore on the marketplace + +
+ +Additionally the "App Change Process" can get triggered from the app overview page. Details to the app change process are documented under following page App Marketplace - App Change Process +
+
diff --git a/docs/04. App(s)/App-Management/App Management Board - Operator.md b/docs/04. App(s)/App Provider Management Board(s)/App Management Board - Operator.md similarity index 100% rename from docs/04. App(s)/App-Management/App Management Board - Operator.md rename to docs/04. App(s)/App Provider Management Board(s)/App Management Board - Operator.md diff --git a/docs/04. App(s)/App Provider Management Board(s)/Implementation.md b/docs/04. App(s)/App Provider Management Board(s)/Implementation.md new file mode 100644 index 000000000..fd646dddb --- /dev/null +++ b/docs/04. App(s)/App Provider Management Board(s)/Implementation.md @@ -0,0 +1,38 @@ +# Implementation + +### #1 "Last Changed" Apps +Last changed apps is showing the 4 apps latest changed. +
+The function is only supported, if the company has more then minimum 6 apps. Otherwise this section does not exist. +
+ +```diff +! GET: /api/apps/provided +``` +
+ +Details to the data mapping: + +
+
++
+ + +### #2 App Overview +The app overview displays all apps provided by the company to which the user belongs. + + +
+ +```diff +! GET: /api/apps/provided +``` +
+ +Details to the data mapping: + +
+
++
diff --git a/docs/04. App(s)/App Release Approval/01. Summary.md b/docs/04. App(s)/App Release Approval/01. Summary.md new file mode 100644 index 000000000..bb425c7e3 --- /dev/null +++ b/docs/04. App(s)/App Release Approval/01. Summary.md @@ -0,0 +1,27 @@ +## Summary + +The Page "App Approval Board" is accessible via the top main menu for CX Admins. + +The main focus / scope of the page is to enable the operator to manage apps releases for the CX marketplace. + +The page includes following functions + +* search +* filter +* approve a app release +* decline a app release (with message) +* look up app details + +
+
+ +### Page Design +
+
++ +With the initial page load, all apps waiting for a review are displayed. +The user can get to the app details or approve / decline the app release. + +
+
diff --git a/docs/04. App(s)/App Release Approval/02. Approve App Release.md b/docs/04. App(s)/App Release Approval/02. Approve App Release.md new file mode 100644 index 000000000..fc26287c4 --- /dev/null +++ b/docs/04. App(s)/App Release Approval/02. Approve App Release.md @@ -0,0 +1,10 @@ +## Approve App Release + +With the app releae approval, the app is getting activated for the app marketplace. +The approval is triggered by clicking on the approval icon insode the app card: +
+ +
+
++
diff --git a/docs/04. App(s)/App Release Approval/03. Decline App Release.md b/docs/04. App(s)/App Release Approval/03. Decline App Release.md new file mode 100644 index 000000000..b1a0e5b4c --- /dev/null +++ b/docs/04. App(s)/App Release Approval/03. Decline App Release.md @@ -0,0 +1,9 @@ +## Decline App Release + +The app release decline icon can get triggered by clicking on the decline icon inside the app card. Additionally to the cancellation, a message can get added which will get provided to the app manager(s) of the respective company. +
+ +
+
++
diff --git a/docs/04. App(s)/App Release Approval/Implementation.md b/docs/04. App(s)/App Release Approval/Implementation.md new file mode 100644 index 000000000..877c8524c --- /dev/null +++ b/docs/04. App(s)/App Release Approval/Implementation.md @@ -0,0 +1,67 @@ +#x Implementation + +### #1 App Release Overview +Display all apps under review as well as those which are approved. +Endpoint is supporting pagination. +
+ +```diff +! GET: /api/apps/appreleaseprocess/inReview +``` + +Details to the data mapping: + +
+
++ +#### Sorting +
+
++ +Sorting by "Newest First": {hostname}/api/apps/AppReleaseProcess/inReview?page=0&size=15&sorting=DateDesc +Sorting by "App Title A-Z": {hostname}/api/apps/AppReleaseProcess/inReview?page=0&size=15&sorting=NameAsc + +
+ +#### Views +
+
++ +All: {hostname}/api/apps/AppReleaseProcess/inReview?page=0&size=15&sorting=DateDesc +Request Only: {hostname}/api/apps/AppReleaseProcess/inReview?page=0&size=15&sorting=DateDesc&statusID=INREVIEW + +
+
+ +### #2 Approve App Release +The approve app release function is used to release an app which is in status "In Review" to the marketplace. + +With the approval the status of the app is getting updated to "ACTIVE" and the app provider (app manager) is getting informed about the successful release. +
+ +```diff +! PUT /api/apps/appreleaseprocess/{appId}/approveApp +``` + +
+Details regarding the notification can get found in the notification service documentation: Notification Service + + + +### #3 Decline App Release +The decline app release function is used to reject apps and sending the them back to the status "CREATED" . + +With the rejection the app manager will receive an notification as well as an email regarding the rejection and rejection details via a message field. + +
+ +```diff +! PUT /api/apps/{appId}/declineApp +``` + +
+ +Details regarding the notification can get found in the notification service documentation: Notification Service diff --git a/docs/04. App(s)/App-Management/App Management Board - App Provider.md b/docs/04. App(s)/App-Management/App Management Board - App Provider.md deleted file mode 100644 index 1c3c87aec..000000000 --- a/docs/04. App(s)/App-Management/App Management Board - App Provider.md +++ /dev/null @@ -1,96 +0,0 @@ -# Summary - -The Page "App Overview" is accessible via the top main menu for app providers. - -The main focus / scope of the page is to enable app providers to manage their apps under the release process, inside the marketplace or inactive apps, as well as starting the release process for a complete new app. - -The page includes following functions - -* search -* filter -* trigger app registration (link to be added) - -
-
- -# Function - -
-
--
- -### Function: Register a new app -Via the "Register New App" button, the app provider can directly start the registration of a new app inside the network. - -The card is used to get directed to the app release registration form: - -
-
- -### Function: "Active" App - - -
-
- -### Function: "In Progress" App - - -
-
- -### Function: "In Review" App - - -
-
- -### Function: "Inactive" App - - -
-
-Additionally the "App Change Process" can get triggered from the app overview page. Details to the app change process are documented under following page App Marketplace - App Change Process -
-
- -# Implementation - -### #1 "Last Changed" Apps -Last changed apps is showing the 4 apps latest changed. -
-The function is only supported, if the company has more then minimum 6 apps. Otherwise this section does not exist. -
- -```diff -! GET: /api/apps/provided -``` -
- -Details to the data mapping: - -
-
--
- -### #2 App Overview -The app overview displays all apps provided by the company to which the user belongs. - - -
- -```diff -! GET: /api/apps/provided -``` -
- -Details to the data mapping: - -
-
--
- - diff --git a/docs/04. App(s)/App-Subscription/01. Subscription.md b/docs/04. App(s)/App-Subscription/01. Subscription.md new file mode 100644 index 000000000..a81c60d8d --- /dev/null +++ b/docs/04. App(s)/App-Subscription/01. Subscription.md @@ -0,0 +1,27 @@ +# Summary + +The app subscription process is essential for the usage of an business application, no matter if an app is right away usable or any pre-requisites are given, the app subscription process will manage the relationship between interested app user and app provider. + +In the drawing below, the initial process is drafted. Important: this is a draft only and relevant for the initial implementation. As soon as this process is enabled an enhancement is planned which should enable to whole app provider / customer communication on the CX platform. + +
+
+ +
+
++
+ +Important flow chart details: the app subscription process does not handle the contract workflow inside the portal, instead the contract agreement is planned to take place outside the marketplace/portal + +After the successful subscription (request by customer and activation by provider) the user management will get enabled for the respective customer company. + +With that, the customer can manage user roles for their own users (pre-requisite: those users need to have an active cx account) + +
+
+ +
+
++
diff --git a/docs/04. App(s)/App-Subscription/02. Overview Company Subscription.md b/docs/04. App(s)/App-Subscription/02. Overview Company Subscription.md new file mode 100644 index 000000000..4d2e5f2b8 --- /dev/null +++ b/docs/04. App(s)/App-Subscription/02. Overview Company Subscription.md @@ -0,0 +1,5 @@ +# Summary + +Available subscriptions or outstanding/pending subscriptions are available under "My Organisation" +
+
diff --git a/docs/04. App(s)/App-Subscription/03. Subscription Overview (App provider).md b/docs/04. App(s)/App-Subscription/03. Subscription Overview (App provider).md new file mode 100644 index 000000000..e279bcc1f --- /dev/null +++ b/docs/04. App(s)/App-Subscription/03. Subscription Overview (App provider).md @@ -0,0 +1,21 @@ +## Summary + +The Page "App Subscription Management" is accessible via the top main menu for app providers. + +The main focus / scope of the page is to enable app providers to manage their app subscriptions (active as well as requests) + +The page includes following functions + +* search +* filter +* trigger subscription activation + +
+
+ + +### Management Board +
+
++
diff --git a/docs/04. App(s)/App-Subscription/04. Subscription Activation (App provider).md b/docs/04. App(s)/App-Subscription/04. Subscription Activation (App provider).md new file mode 100644 index 000000000..7ee11efc8 --- /dev/null +++ b/docs/04. App(s)/App-Subscription/04. Subscription Activation (App provider).md @@ -0,0 +1,7 @@ +## Activate Subscription Request + +...... +
+
++
diff --git a/docs/04. App(s)/App-Subscription/FAQ.md b/docs/04. App(s)/App-Subscription/06. FAQ.md similarity index 100% rename from docs/04. App(s)/App-Subscription/FAQ.md rename to docs/04. App(s)/App-Subscription/06. FAQ.md diff --git a/docs/04. App(s)/App-Subscription/Company_App_Subscription.md b/docs/04. App(s)/App-Subscription/Subscription Flow - Implementation.md similarity index 65% rename from docs/04. App(s)/App-Subscription/Company_App_Subscription.md rename to docs/04. App(s)/App-Subscription/Subscription Flow - Implementation.md index f5c12ae66..ae2ab097c 100644 --- a/docs/04. App(s)/App-Subscription/Company_App_Subscription.md +++ b/docs/04. App(s)/App-Subscription/Subscription Flow - Implementation.md @@ -1,32 +1,4 @@ -# Summary - -The app subscription process is essential for the usage of an business application, no matter if an app is right away usable or any pre-requisites are given, the app subscription process will manage the relationship between interested app user and app provider. - -In the drawing below, the initial process is drafted. Important: this is a draft only and relevant for the initial implementation. As soon as this process is enabled an enhancement is planned which should enable to whole app provider / customer communication on the CX platform. - -
-
- -
-
--
- -Important flow chart details: the app subscription process does not handle the contract workflow inside the portal, instead the contract agreement is planned to take place outside the marketplace/portal - -After the successful subscription (request by customer and activation by provider) the user management will get enabled for the respective customer company. - -With that, the customer can manage user roles for their own users (pre-requisite: those users need to have an active cx account) - -
-
- -
-
--
- -# Implementation +## Implementation ### DB implementation @@ -39,7 +11,7 @@ To support the app subscription status, the portal db model was enhanced by a ne ### #1 POST Subscribe Request -The post subscribe request is triggered by the customer / interested company via the app marketplace "Subscribe" function. +The post subscribe request is triggered by the customer / interested company via the app marketplace "Subscribe" function. The request triggers a request to the app provider (via portal notifications and email). Via the subscribe request service, the app provider gets informed about the raised customer interest and can take the following actions to activate the app usage.
@@ -121,5 +93,3 @@ text needed
- - diff --git a/docs/04. App(s)/App-Subscription/App_Subscription_Management_Board.md b/docs/04. App(s)/App-Subscription/Subscription Management - Implementation.md similarity index 64% rename from docs/04. App(s)/App-Subscription/App_Subscription_Management_Board.md rename to docs/04. App(s)/App-Subscription/Subscription Management - Implementation.md index 47a23d106..dae97b383 100644 --- a/docs/04. App(s)/App-Subscription/App_Subscription_Management_Board.md +++ b/docs/04. App(s)/App-Subscription/Subscription Management - Implementation.md @@ -1,31 +1,4 @@ -# Summary - -The Page "App Subscription Management" is accessible via the top main menu for app providers. - -The main focus / scope of the page is to enable app providers to manage their app subscriptions (active as well as requests) - -The page includes following functions - -* search -* filter -* trigger subscription activation - -
-
- -# Function - -### Management Board -
-
--
- -### Activate Subscription Request -
-
--
+## Implementation ### Function: View Subscriptions (Requests and Active) @@ -43,7 +16,7 @@ The page includes following functions
-# Implementation +## APIs ### #1 View Subscriptions The endpont shows all subscription requests and active subscriptions. @@ -77,4 +50,3 @@ By entering the tenant url, the client is getting registered inside the portal d # FAQ to be added - From 9e1e125b975ec6a2507b0a5ff68542179ff5d3a6 Mon Sep 17 00:00:00 2001 From: jjeroch <94133633+jjeroch@users.noreply.github.com> Date: Thu, 9 Feb 2023 17:13:41 +0100 Subject: [PATCH 2/2] update --- ...r_Description.md => 01. User_Description.md} | 0 docs/04. App(s)/Marketplace/02. FAQ.md | 17 +++++++++++++++++ docs/04. App(s)/Marketplace/FAQ.md | 17 ----------------- 3 files changed, 17 insertions(+), 17 deletions(-) rename docs/04. App(s)/Marketplace/{User_Description.md => 01. User_Description.md} (100%) create mode 100644 docs/04. App(s)/Marketplace/02. FAQ.md delete mode 100644 docs/04. App(s)/Marketplace/FAQ.md diff --git a/docs/04. App(s)/Marketplace/User_Description.md b/docs/04. App(s)/Marketplace/01. User_Description.md similarity index 100% rename from docs/04. App(s)/Marketplace/User_Description.md rename to docs/04. App(s)/Marketplace/01. User_Description.md diff --git a/docs/04. App(s)/Marketplace/02. FAQ.md b/docs/04. App(s)/Marketplace/02. FAQ.md new file mode 100644 index 000000000..1537d0b2a --- /dev/null +++ b/docs/04. App(s)/Marketplace/02. FAQ.md @@ -0,0 +1,17 @@ +### FAQ +
+ +#### How can I release my app on the app marketplace. +To release your app on the app marketplace, you just need to have the company role "App Provider" assigned as well as the user role "App Manager". If thats the case - just follow the description under following link [App Release Process](/docs/04.%20App(s)/Release-Process/App%20Release%20Workflow.md) +
+
+ +####
+
+ +####
+
diff --git a/docs/04. App(s)/Marketplace/FAQ.md b/docs/04. App(s)/Marketplace/FAQ.md deleted file mode 100644 index 74bb7c0be..000000000 --- a/docs/04. App(s)/Marketplace/FAQ.md +++ /dev/null @@ -1,17 +0,0 @@ -### FAQ -
- -####
-
- -####
-
- -####
-