Skip to content

README.md

Latest commit

 

History

History
133 lines (84 loc) · 5.26 KB

README.md

File metadata and controls

133 lines (84 loc) · 5.26 KB

Round Review - Extensive Documentation

Warning

The documentation is under creation and it will be subject to frequent changes

APIs

Environment Variables

Checkout the environment variables for the app and the plugin in this page.

Webhook Notification for Document Status Updates

A webhook is a notification that is triggered inside the system when a document status is updated.

Notification Details

The notification includes the following details:

  • Event type: "object.updated"
  • Object ID: The ID of the object that has been updated
  • Project ID: The ID of the project associated with the object
  • Updated fields: A dictionary containing the updated status
  • Updated timestamp: The current timestamp in ISO 8601 format

Each webhook notification is scheduled to be sent with a slight delay, increasing by 2 seconds for each subsequent user to avoid overwhelming the server with simultaneous requests.

Example JSON Payload

Here is an example of the JSON payload that would be sent in a POST request after triggering a webhook:

POST https://mywebsite.tld/webhook-handler
{
  "event": "object.updated",
  "object_id": "98eb135f-c083-435a-9929-e6f9ad3810fd",
  "project_id": 1,
  "updated_fields": {
    "status": "Pending Review"
  },
  "updated_at": "2025-10-12T17:50:16.917017Z"
}

Possible values

  • Event can be: object.updated
  • Status can be: No Review, Pending Review, Under Review, Require Changes, Approved

Development Notes

Logs and Auditing

All the logs are collected inside a log table. Every System Operation (e.g. db update, first admin creation) is logged for the System User.

All the API KEYs created by the user are available to admins for security reasons.

Database

For portability reasons, the database is a SQLite that lives within the main container. All files are saved as blobs for performance reasons.

The database has a table called rr_db_version which contains the current db schema and the info of when the db has been updated.

In future releases, it will be possible to choose between SQLite or MySQL to gain more reading performance.

Github integration

The Github Integration works as follows:

  1. First, create a new OAuth Apps in Github > Settings > Developer Settings
  2. Copy the client ID (e.g. Ov2xxxxxx) and client Secret (e.g. xxxxxxxxxxdf21c24f) from the OAuth Apps.
  3. Add the information in your .env config file and enable GITHUB_OAUTH_ENABLED=True
  4. Restart the container (docker compose up -d) and login into your app as admin
  5. Add (or update) a user and insert its Github Username (e.g. Maxelweb)
  • The username is case folded, no worries about UPPER / lower cases.
  • If the user change its username in Github it needs to be updated.
  1. Done!

Permissions

  • A member of a project can write/read resources, edit documents (name, description, path, version), remove the documents if is the author and view comments / reviews on documents.
  • A reviwer of a project can do everything as the member, and can also add / check / delete comments. It can also remove reviews.
  • A owner of a project can do everything as the reviewer, and can also manage users.

At the moment, projects cannot be deleted.

In future release, there might be possible to make in-depth permissions per-user or per-group according to project owner.

PDF Notary Bot

The PDF Notary Bot is a plugin that interacts with the Round Review Integrations APIs to add automatic reviews based on an event-driven system.

The flow is the following:

  1. A reviewer / project owner updates the status of a document.
  2. If a webhook is set, the application executes a POST call to the PDF Notary Bot to the /webhook endpoint.
  3. The POST call is processed:
  4. A signed PDF is generated and saved into a folder.
  5. The Round Review Integration APIs are called to add the new review with a link to download the PDF.

Configuration

Before starting the bot, you need to generate a self-signed SSL certificate.

By default, the notary bot will use:

PLUGIN_KEY_PASSPHRASE=<empty>
PLUGIN_KEY_PATH=/certs/key.pem
PLUGIN_CERT_PATH=/certs/cert.pem
PLUGIN_SIGNED_PDFS_FOLDER=/signed_pdfs

You can override those settings, by adding them into the docker compose file.

Signed PDF Link security

The link generated by the Notary Bot contains the information regarding the Object ID and parts of the HASH of the new signed PDF (to which the notary bot is creator). The link can be considered unique to retrieve that specific PDF. However, anyone with that link can download the signed PDF without authentication.

Certificates for PDF signing

For the scope of this bot, the certificate of the PDF will be always considered self-signed. Hence, the output PDF will show a warning, if open with Acrobat Reader or similar tools.

If a validation is required, you can check it manually with PyHanko by trusting your self-signed CA.

In addition to the certificate, the PDF contains a BOX in the first page of the PDF (bottom-left corner) that can be populated with an image representing a signature or similar.