Digital certificates - VR Integration

Overview

The purpose of this document is provide a high level guidance to integrating digital certificates into the Vessel Registry Application to meet the following business goal:

• Users receive digital certificates once an application is approved by the vessel registry

Open

The previous diagram presents a high level overview of the process, where steps 1 are 2 are considered to be pre-configuration or an onboarding step. To complete those steps, you would need to reach out to Team Poseidon and submit a request to add a signer and to be added as developer/admin to access the DocuSign platform administrative panel for template modification if you are following in with Step 3.

Post steps 1 and 2, depending on the approach suggested by the UX team the developers can option to use:

• Pdf Templates as outlined in Step 3, in which the template(pdf) would have to be uploaded to the DocuSign platform and modified. You can visit the DocuSign documentation for an in-depth overview of how to interact with the platform.

• Html templates - Reference the Digital Signature API Open API Specification for model details.

  • Endpoint: api/v1/Signing/HTMLCeremonyUrl

Leading into step 4, this where the registrar interacts with the Vessel Registry Management system to initiate the process of issuing a certificate. We will delve deeper in a later section about the specifics of this interaction, but for now the Vessel Registry Application will make a request to the Digital Signature API as shown in step 5, passing along the certificate data and a return URL, which will then proxy our call over to the DocuSign API to initiate the signing ceremony. After the signing ceremony is complete, the digital signature api would redirect the user to the specified return URL as shown in step 7, passing along the Envelope Id, and Event Status (signing_complete, denied, cancelled).

In step 8 the vessel registry management application sends the certificate data to the Eve API (POST/PUT: /EVE/Documents), passing along the searchable fields associated with the generated certificate.

Following that, step 9 has two possible routes that can be taken, with preference given to the in application route:

1. Post the signing ceremony step 6 the registrar will receive an email of the recently generated certificate. The registrar can then send the email to the client(s) through their preferred email client.

2. An alternative to the previous step is to allow the vessel registry management application to automate the sending of the email through the GC Notify service

Finally in step 10, the registrar can verify the certificate data either through the Vessel Registry application (GET: /EVE/Documents) or through the Eve Website.

Implementation

Given the dependency on multiple external applications, we would need to modify our approach to how requests are completed within the Vessel Registry Management application. The following sections will break down how the functionality can be segregated.

Completing a request

Open

When completing a request, the process will be the same, the only difference is we are doing a lift and shift of the logic related to registering or updating a vessel to the BFF(VRG) as needed, and introducing SignalR for push notification when the request is completed.

Steps 1, 2, 3 is the process of initiating the request completion, in our current process that is click the “Issue Certificate button“. This would need to change, and we would need to separate the Generation of the Certificate from the Completion of the Request.

The Issue Certificate button would only generate the certificate after the request is in a completed state. It could be hidden when the request is not complete. We will talk about the process of issuing a certificate in the next section.

When the user initiates the process of completing a request, the application will validate the fields, and send the data to the VRG which will return a 200 ok to the application indicating acceptance of the request as indicated in step 5. The status component could then indicate an interim state prior to completion, that the request is being processed. It could also indicate errors.

After the successful processing of creating the request, the Vessel Registry Gateway would then send a push notification to the UI to inform the users that the request processing was completed successfully as indicated in step 9. No need to persist the messages unless required, as the user can revisit the request at a later time to check on the status.

Issuing a certificate

The following two subsections will present a recommended implementation approach, and an interim implementation. The reason I am separating the two is related to the current capabilities of the external Digital Signature API. The system in it’s current state does not support event based communication, which is what the recommended approach entails.

In the following diagrams, I will include some interim states for when the signing ceremony is in progress from initiation till completion. These are non-binding and were used for illustration and are subject to change based on the business requirements.

Recommended implementation

As previously indicated in the completing a request section, we separated the process of registering or amending data to a vessel from the issuing of a certificate. The following section outlines the important sections of the previous diagram:

1. A lift and shift of the certificate issuing logic is moved to the Vessel Registry Gateway(BFF). When an issue certificate request is made, the request id is passed along with the request to the VRG so the data can be retrieved from the Vessel History Service.

2. Certificate data is then sent to the Digital Signature API.

   1. The digital signature API returns a Signing Ceremony URL linked to the DocuSign platform.

   2. The VRM will redirect the Vessel Registrar to that URL, so the Vessel Registrar can complete the signing ceremony

3. The DocuSign platform will inform the Digital Signature API the signing ceremony is completed.

   1. Which will then emit a Signing Complete Event (The dispatching of an event behavior does not currently exist in the Digital Signature API. A request will be submitted to Team Poseidon to see if they can accommodate this type of service to service communication).

   2. The VRG will receive the event from the ASB

4. The VRG will get the signed document from the Digital Signature API (/api/v{version}/Documents/Document)

   1. Upload the document to the DMS

   2. Link the document to the service request in WMS

5. VRG will then publish the certificate data to EVE (/EVE/Documents)

6. If the registrar indicated that the request should be emailed to client(s), the VRG will publish an event to the JSS.

   1. JSS will sent the email using the GC Notify service (retry pattern should be applied here)

7. Wait for the confirmation to be received from GC Notify

8. Emit an event indicating the status of emailing the digital certificate to clients.

9. Status update

   1. Workload Management Service Status is updated

   2. A push notification is sent through the SignalR service to all connected VRM instances through VRG about the completion of the signing ceremony process

Interim implementation

In app notifications

Delivery

Introducing digital certificates into the vessel registration system should be done incrementally through feature flags and by properly utilizing vertical slicing of PBIs. For example instead of trying to apply digital certificates to all request types at the same time, you would take a single request i.e. a First Registry and introduce digital certificates to it. This will then allow you to:

• Incrementally reach the overarching goal of Digital Certificates and Notifications instead of one big bang release

• Prevent any disruption of work within the VR application, by maintaining the old functionality as a fallback implementation

• Isolate the feature to a group of key stakeholders/end-users to get proper and continuous feedback and make the necessary adjustments before final adoption

• Assess performance and implementation approach

• Identify any missing features related to Digital Certificates

Add QR code into certificate

• Compose URL for getting information e.g https://ncdsafsecsurapp-eve-external.azurewebsites.net/?SearchType=OfficialNumber&SearchValue=C26154NS&ServiceName=VR

• Call EVE end points to get QR Code image for given URL

• Insert QR code image into Html certificate/transcript

• Call HtmlCeremonyUrl for singing certificate/transcript

Resources

• Swagger UI (tc-digital-signature.azurewebsites.net)

• Swagger UI (tc-electronic-document-verification-service.azurewebsites.net)

• Vessel Registration - Repos (azure.com) [Updated - Implementation is now primarily in the VR project]

Terms and definitions