Skip to content

Latest commit

 

History

History
638 lines (480 loc) · 23.9 KB

03. Registration Approval Process.md

File metadata and controls

638 lines (480 loc) · 23.9 KB
Raw

Summary

The registration approval board is created for the CX Admin to manage registration applications to the Catena-X network.
Acting user: CX Admin (Operator)

image

By clicking on one of the process steps, the overlay wth process step details gets displayed. Depending on the status, the user can execute a number of action / next steps. In general 3 action states are possible and defined below

image



Approval Overlay/Status

Via an overlay, which is getting displayed as soon as the user clicks on any of the confirmation steps in the approval board, the detailed steps and status of the different application validation steps can get viewed.

! GET /api/administration/registration/application/{applicationId}/checklistDetails

Response Body

    applicationChecklist: [
           {
             "type": "e.g. Registration_Verification",
             "value": "e.g. DONE",
             "details": "string - can be empty",
             "retriggerable": "process_step"
             },
           {
             "type": "e.g. Business_Partner_Number",
             "value": "e.g. IN_PROGRESS",
             "details": "string - can be empty",
             "retriggerable": "process_step"
           }
         ]

IMPORTANT: the "retriggerable" attribute is relevant / important for the FE business logic to decide; if the retrigger button is getting displayed or not.

#1 Registration Validation

image


#2 BPN Creation

image


#3 Managed Identity Wallet

image


#4 Clearinghouse

image


#5 Self Description LP

image



Approval Flow

The company registration approval flow is covering the manual and automatic checks of the company application including the setup of the company to participate inside the data space.
The list below shows an overview of all application approval steps:



image

As the highlevel displayed above; the registration approval flow consists of 6 steps. These can be partially executed in parallel, but always run in a predefined sequence. The 6 steps shown above are mapped as a checklist. To ensure that the operator knows the status of the company registration, each step can have one of the following statuses:

  • Open
  • In Progress
  • Done
  • Failed

The checklist is processed as far as possible automatically by a worker process. Therefore, a checklist item has at least one corresponding process step, these are created for processing in the worker. The distribution of the process steps to the checklist steps is listed in the respective checklist step.

In case of a failed process step, the error code (if any) is recorded for the checklist step of the registration application and can be viewed by the operator.



Details "Manual Validation"


Associated Process Steps: VERIFY_REGISTRATION
The "manual validation" checklist item is covering the company application validation by the operator. In this step, the application gets manually checked and 'approved' or 'declined'. Depending on the decision the checklist item "Registration_Verification" is set to DONE or FAILED.

In the scenario of FAILED, a comment/message must be submitted by the operator.

Scenario: Approve

The endpoint "approve" sets the "Registration_Verification" checklist item to "DONE". The endpoint can only get triggered/executed if the application is in the status "submitted" and the "Registration_Verification" in the Status "TO_DO". 

! PUT /api/administration/registration/application/{applicationId}/approve

Scenario: Decline

image


The endpoint "decline" sets the "Registration_Verification" checklist item to "FAILED" incl. a time stamp, as well as the decline message added by the operator. The endpoint can only get triggered/executed if the application is in status "submitted" and the "Registration_Verification" in the Status "TO_DO". Additionally the endpoint sets the Application Status to "DECLINED" and the status of the company to "REJECTED". The users of the applying company will get an email after the process informing about the rejection including the decline message of the operator. 

! PUT /api/administration/registration/application/{applicationId}/decline

Request Body:

{
  "comment": "string"
}


Details "Create Business Partner Number (if necessary)"

The status "Business_Partner_Number" is getting updated based on the application registration content.
Scenario 1 - Registration with BPN

If the registration application is getting submitted by the registration party for approval with a BPN, the checklist item "Business Partner Number" is getting set to "DONE". In this case; nothing is needed anymore regarding the business partner number checklist item.

Scenario 2 - Registration without BPN

Associated Process Steps: CREATE_BUSINESS_PARTNER_NUMBER_PUSH, CREATE_BUSINESS_PARTNER_NUMBER_PULL
If the registration application is getting submitted by the registration party for approval without a BPN, the checklist item "Business Partner Number" is kept in status "TO_DO"

This process will be executed automatically by the worker. While processing the "CREATE_BUSINESS_PARTNER_NUMBER_PUSH" process step for the "Business Partner Number" checklist item, the worker will fetch all company data of the registration company and submit them to the business partner golden record gateway to validate the record and generate a business partner number. For the submission of the data to the business partner golden record gateway - the following endpoint is used:


! PUT /api/catena/input/legal-entities

API Body

    [
      {
        "legalNameParts": [
          "string"
        ],
        "identifiers": [
          {
           "value": "company_identifiers.value",
           "type": "bpdm_identifiers.labels"
          }
        ],
        "legalShortName": "companies.shortname",
        "legalForm": null,
        "states": [
        ],
        "classifications": [
        ],
        "roles": [
        ],
        "legalAddress": {
          "nameParts": [
          ],
          "states": [
          ],
          "identifiers": [
          ],
          "physicalPostalAddress": {
            "geographicCoordinates": {
            },
            "country": "addresses.AlphaCode2",
            "postalCode": "addresses.zipcode",
            "city": "addresses.city",
            "street": {
              "namePrefix": null,
              "additionalNamePrefix": null,
              "name": "addresses.streetname",
              "nameSuffix": null,
              "additionalNameSuffix": null,
              "houseNumber": "addresses.streetnumber",
              "milestone": null,
              "direction": null
            },
            "administrativeAreaLevel1": "addresses.region",
            "administrativeAreaLevel2": null,
            "administrativeAreaLevel3": null,
            "district": null,
            "companyPostalCode": null,
            "industrialZone": null,
            "building": null,
            "floor": null,
            "door": null
          },
          "alternativePostalAddress": {
            "geographicCoordinates": {
            },
            "country": null,
            "postalCode": null,
            "city": null,
            "administrativeAreaLevel1": null,
            "deliveryServiceNumber": null,
            "deliveryServiceType": null,
            "deliveryServiceQualifier": null
          },
          "roles": [
          ]
        },
        "externalId": "company_applications.id"
      }
    ]

There are two possible outcomes to the external push.

  1. The call to the external system was successful. Then the process step "CREATE_BUSINESS_PARTNER_NUMBER_PUSH" is set to "DONE" and the checklist item "Business Partner Number" is set to "IN_PROGRESS". After that the process item "CREATE_BUSINESS_PARTNER_NUMBER_PULL" is created. Currently there is not implementation to push the data back to the portal. Therefore as soon as the process item "CREATE_BUSINESS_PARTNER_NUMBER_PULL" is created the portal will try to pull a response from the bpdm to get the bpn for the company. When receiving the valid bpn the checklist item "Business Partner Number" is set to "DONE", if the "VERIFY REGISTRATION" is already in state "DONE", the process item "CREATE_IDENTITY_WALLET" is created.

  2. The call to the external system failed. The checklist item "BUSINESS_PARTNER_NUMBER" is set to "FAILED". A process item "RETRIGGER_BUSINESS_PARTNER_NUMBER_PUSH" is created afterwards to enable the restart a failed BPN process.



With executing the endpoint below, a failed bpn process can be retriggered to be executed again.


! POST /api/administration/registration/application/{applicationId}/trigger-bpn


With the successful response (200) of the push business partner data call, the process checklist worker is now execution the PULL call against the business-partners endpoint to retrieve the newly created bpn or the company address validation error for the respective application id of the registration company (applications.id is used as external_id)


! GET /api/catena/sharing-state?externalIds={applications.id}

API Body

    {
      "totalElements": 0,
      "totalPages": 0,
      "page": 0,
      "contentSize": 0,
      "content": [
        {
          "businessPartnerType": "LEGAL_ENTITY",
          "externalId": "string",
          "sharingStateType": "Pending",
          "sharingErrorCode": "SharingProcessError",
          "sharingErrorMessage": "string",
          "bpn": "string",
          "sharingProcessStarted": "2023-08-17T20:06:28.909Z"
        }
      ]

Scenario 3 - manually add BPN as an operator (interim supported workflow)

For the interim process of the need to add the BPN of the new CX participant manually, the operator can use the endpoint to add the business partner number to the application. This endpoint is interim only and supposed to get disabled; as soon as the BPN Gateway is providing stable feedback on provided company data. 

! POST /api/administration/registration/application/{applicationId}/{bpn}/bpn

Standard validations apply:

  • bpn has to be 16 digits long
  • bpn must start with "bpnl" / "BPNL"
  • company status inside portal db needs to be in "pending"
  • input value for the bpn is expected alphanumeric


image



Details "Create Managed Identity Wallet"

Associated Process Steps: CREATE_IDENTITY_WALLET

The IF to the identity wallet is getting automatically triggered to create the company identity wallet when the following pre-requisites are fulfilled:
  • application checklist status "Business_Partner_Number" = "DONE"
  • application checklist status "Registration_Verification" = "DONE"
  • application is in status "submitted"
    Details of the company identity wallet can get found inside the identity wallet product description.

With triggering the registration; the company name as well as the bpn are getting submitted and stored inside the company wallet.

Depending on the API response, the system will behave in the following way:

  • Response "Fail" => store the error message in the checklist table under checklist.comment and set the status to "FAILED"
  • Response "Success" => set status to "DONE" and store the did provided by the response body inside the comment attribute inside the table checklist.comment

If for some reason the call to the identity wallet fails, a new process item "RETRIGGER_IDENTITY_WALLET" is created. This process item allows the operator to manually retrigger the process with the following endpoint:

! POST /api/administration/registration/application/{applicationId}/trigger-identity-wallet
Please note: the scenario of "bring your own company wallet" is currently not supported and will get rechecked in H2 2023.


Details "Clearinghouse Check"


Associated Process Steps: START_CLEARING_HOUSE, END_CLEARING_HOUSE

The "Clearinghouse Check" is getting automatically triggered when the following pre-requisites are fulfilled:
  • application checklist status "Business_Partner_Number" = "DONE"
  • application checklist status "Registration_Verification" = "DONE"
  • application checklist status "Identity_Wallet" = "DONE"
  • application is in status "submitted"

image


The interface is an asynchronous interface - due to this the application checklist item associates with two process steps; the interface is explained below in two steps

Step 1 - Send company data to clearinghouse

The checklist worker checks for the existence of the "START_CLEARING_HOUSE" process item in state "TODO", when existing the process will automatically get the DID from the Identity Wallet for the company and send the company data displayed below to the clearinghouse endpoint. A new process item "END_CLEARING_HOUSE" is created. And the status of the "CLEARING_HOUSE" checklist item is set to "IN_PROGRESS"

    {
       "participantDetails": {
            "name": "string",
            "city": "string",
            "street": "string",
            "bpn": "string",
            "region": "string",
            "zipCode": "string",
            "country": "string",
            "countryAlpha2Code": "string"
           },
       "identityDetails": {
            "did": "string",
            "uniqueIds": [
                    {
                       "type": "string",
                       "value": "string"
                     }
                   ]
           }
      }

If for some reason the call to the clearinghouse fails, a new process item "RETRIGGER_CLEARING_HOUSE" is created, to allow the manual retriggering of the process with the endpoint:

! POST /api/administration/registration/application/{applicationId}/retrigger-clearinghouse


Step 2 - Clearinghouse response

In the asynchronous call of the clearinghouse check; the portal provides a POST endpoint, which can get triggered by the clearinghouse to update the checklist status.

the clearinghouse needs to be able to store a fail/success message. the message is supposed to get stored inside the checklist comment of the record attribute "clearing_house" 

! POST /api/administration/registration/application/clearinghouse
    {
      "bpn": "string",
      "status": "string",
      "message": "string"
    }

The bpn inside the request body is used to fetch the correct application Id. (application in status "submitted") The status can only get changed/updated; if the status of the application checklist item "CLEARING_HOUSE" is "IN_PROGRESS".

If the clearinghouse service response contains the status CONFIRM the "CLEARING_HOUSE" checklist item is set to status DONE, if the response status is DECLINE a new process item "TRIGGER_OVERRIDE_CLEARING_HOUSE" is created.

The new process item provides the possibility to override the clearinghouse state by calling the following endpoint:

! POST /api/administration/registration/application/{applicationId}/override-clearinghouse


Details "Self-Description Creation LegalParticipant"

Associated Process Steps: START_SELF_DESCRIPTION_LP, FINISH_SELF_DESCRIPTION_LP


image



The "Self_Description_Legal_Participant" is getting automatically triggered when the following pre-requisites are fulfilled:
  • application checklist status "Business_Partner_Number" = "DONE"
  • application checklist status "Registration_Verification" = "DONE"
  • application checklist status "Identity_Wallet" = "DONE"
  • application checklist status "Clearinghouse_Check" = "DONE"
  • application checklist status "Self_Description_LP" = "TO_DO"
  • application is in status "submitted"

The interface is an asynchronous interface - due to this the application checklist item associates with two process steps; the interface is explained below in two steps

Step 1 - Create SelfDescription - send company data to SD Factory

The checklist worker checks for the existence of the "START_SELF_DESCRIPTION_LP" process item in state "TODO", when existing the process will automatically post the necessary data to the SD-Factory to register the self description. A new process item "FINISH_SELF_DESCRIPTION_LP" is created. And the status of the "SELF_DESCRIPTION_LP" checklist item is set to "IN_PROGRESS".

Request Body for SD-Factory call

{
  "type": "LegalParticipant",
  "externalId": "{applicationId}",
  "registrationNumber": [
    {
      "type":"string",
      "value": "string"
    }
  ],
  "headquarterAddress.country": "alpha2code of the registration company country",
  "legalAddress.country": "alpha2code of the registration company country",
  "bpn": "company bpn of the application company",
  "issuer": "Catena-X bpn of the portal operator",
  "holder": "company bpn of the application company"
}
Step 2 - Save self description document

To receive the asynchronous call from the SD-Factory the portal provides a POST endpoint, which can get triggered by the SD-Factory to pass the self description document and or a failed status with a explaining message. 

! POST /api/administration/registration/application/clearinghouse/selfDescription
    {
      "externalId": "Guid",
      "status": "string",
      "message": "string"
      "selfDescriptionDocument": "string"
    }

with calling the endpoint; the SD Factory submits a self-description of the legal person. The portal backend is storing the self-description inside the portal db linked to the company.
With triggering the endpoint and submitting a document, the status of the checklist item "Self_Description_LP" is set to "DONE".

Response "Error" => store the error message in the checklist table under checklist.comment and set the status to "FAILED"
Response "Success" => set status to "DONE"

    "registratioNumber": [

         {
           "type": "technicalKey",
           "value": "value from db"
         }
       ]
DB Table Content
ID Portal DB Key Interface Key for SD
1 COMMERCIAL_REG_NUMBER local
2 VAT_ID vatID
3 LEI_CODE leiCode
4 VIES EUID
5 EORI EORI


Details "Activation"

image


The complete company account activation (as a result of the successful application checklist finalization) is automatically executed when the following pre-requisites are fulfilled:
  • application checklist status "Business_Partner_Number" = "DONE"
  • application checklist status "Registration_Verification" = "DONE"
  • application checklist status "Identity_Wallet" = "DONE"
  • application checklist status "Clearinghouse_Check" = "DONE"
  • application checklist status "Self_Description_LP" = "DONE"
  • application is in status "submitted"

With the execution of the application activation, the system will:

  • call POST /api/credentials/issuer/membership to create membership credential for the registration party
  • set company status inside portal.companies to "ACTIVE"
  • set application status inside portal.company_application to"CONFIRMED"
  • set company_application time stamp
  • set invitation of all users to "CLOSED"
  • set invitation time stamp
  • update user roles (portal db and Keycloak)
  • add bpn to user(s)
  • send a welcome email

NOTE:

  • if the activation is not successful (due to any reason) the membership credential should not get set/send
  • if the membership credential call is unsuccessful, the "registration activation" should not take place. (rare scenario - since this would only happen if the wallet is down or the wallet has a major internal service error)


Add/Update BPN for the registration company


The bpn can get manually added (as a workaround) if the registration company request doesn't have a business partner number added and the registration request is in the status "submitted".

image


BPNs can only get added by CX Admins. As mentioned above, the implementation is a workaround only and will get replaced by the actual bpn connection as soon as the reference implementation is available.

Status endpoint - Checklist Details

To fetch the specific details of the checklist items; status; possible available comment as well as the re-triggerable status, the following endpoint needs to get called 

! GET api/administration/registration/application/{applicationId}/checklistDetails

Response Body

{
  "type": "e.g. REGISTRATION_VERIFICATION",
  "status": "e.g. TO_DO",
  "details": "string",
  "retriggerableProcessSteps": [
    "e.g. VERIFY_REGISTRATION"
  ]
}


Details for retrigger process

retriggering any process manually always deletes the current saved comment inside application_checklist.comment to ensure that the reason for the earlier failed execution is not getting displayed to the user anymore.

NOTICE

This work is licensed under the Apache-2.0.