Merge pull request #90 from bcgov/docs/devhub-documentation

Fixed pdated Traction pages, fixed wording in OrgBook page Signed-off-by: Emiliano Suñé <emiliano.sune@gmail.com>
bcgov · Aug 2, 2024 · c208020 · c208020
2 parents 53aecf3 + c7ad77a
commit c208020
Show file tree

Hide file tree

Showing 9 changed files with 83 additions and 24 deletions.
diff --git a/docs/about-us.md b/docs/about-us.md
@@ -1,7 +1,5 @@
 # About us
 
-## Suggested Content
-
 Learn more about Digital Trust initiatives in the BC provincial Government at https://digital.gov.bc.ca/digital-trust/home/
 
 For any questions or requests that are not answered in the documentation or on the Digital trust website, feel free to log an issue in this repository and/or send an email at the addresses listed [here](https://digital.gov.bc.ca/digital-trust/contact).
diff --git a/docs/images/endorser-selection.png b/docs/images/endorser-selection.png
diff --git a/docs/index.md b/docs/index.md
@@ -1,4 +1,4 @@
-# Digital identity and Trust Program Documentation
+# Digital Identity and Trust Program
 
 Technical and non-technical documentation for Digital Trust and Verifiable Credentials
 
@@ -22,4 +22,4 @@ Depending on which pattern you are looking to implement, the following solutions
 
 - [VC-AuthN and SSO](solutions/vc-authn-sso.md): a solution that allows the use of Digital Credentials in an OIDC authentication flow. As an identity Provider service integrated with the [Pathfinder SSO Service](https://developer.gov.bc.ca/docs/default/component/css-docs) it provides a lightweight, standard approach to web application authentication that does not require deep knowledge of Digital trust patterns and tools.
 - [Traction](solutions/traction-overview.md): a Software-As-A-Service Enterprise agent service based on [Aries Cloudagent Python](https://github.com/hyperledger/aries-cloudagent-python), it provides streamlined onboarding for new adopters wanting to have full control over their Digital trust processes, from receiving and presenting Digital credentials to acting as a verifier or even an issuer.
-- [OrgBook BC](https://orgbook.gov.bc.ca): a repository of credentials for publicly available information. It contains information about entities registered as businesses in BC (data from BC registries), as well as [other permit/license credentials from different organizations](https://orgbook.gov.bc.ca/about/orgbook-data).
+- [OrgBook BC](solutions/orgbook-bc.md): a repository of credentials for publicly available information. It contains information about entities registered as businesses in BC (data from BC registries), as well as [other permit/license credentials from different organizations](https://orgbook.gov.bc.ca/about/orgbook-data).
diff --git a/docs/patterns/overview.md b/docs/patterns/overview.md
@@ -0,0 +1,3 @@
+# Digital Trust Patterns
+
+## Work In Progress
diff --git a/docs/solutions/endorser-service.md b/docs/solutions/endorser-service.md
@@ -0,0 +1,3 @@
+# Endorser Service
+
+## Work In Progress
diff --git a/docs/solutions/orgbook-bc.md b/docs/solutions/orgbook-bc.md
@@ -9,14 +9,16 @@ Third party issuers can issue credentials such as licenses and permits to OrgBoo
 There are two ways of accessing data stored in OrgBook:
 
 - The user interface allows the search and discovery of credentials from a web UI. This is useful for end-users trying to gather information about a known entity.
-- The [OrgBook API](https://orgbook.gov.bc.ca/api)
+- The [OrgBook API](https://orgbook.gov.bc.ca/api/)
 
-The API is openly accessible (for reasonably/fair use) and allows systems to integrate with OrgBook to look-up company registration records and associated data.
+The API is openly accessible (for reasonable/fair use) and allows systems to integrate with OrgBook to look-up company registration records and associated data.
 
 The swagger interface provides an easy way to discover the API endpoints, and there are [API docs](https://bcgov.github.io/orgbook-bc-api-docs) with code snippets providing examples for common use cases.
 
 ## Becoming an Issuer
 
 If you have a good candidate for a credential to be publicly issued to an organization (such as a license or permit), you can become an issuer and integrate and push the information to OrgBook.
 
+These are some of the [other permit/license credentials issued by different organizations to OrgBook](https://orgbook.gov.bc.ca/about/orgbook-data).
+
 The current version of OrgBook is in evolution, the best way to get the conversation started is by [contacting us](../about-us.md).
diff --git a/docs/solutions/traction-becoming-an-issuer.md b/docs/solutions/traction-becoming-an-issuer.md
@@ -0,0 +1,19 @@
+# Becoming an Issuer
+
+Becoming an issuer in Traction will provide you with the ability of "rooting" your agent on a ledger in write mode, and start publishing schemas and credential definitions, and therefore issue your own credentials.
+
+Becoming an issuer involves accepting the Governance built around Digital credentials, and obtaining approval for publishing new schemas/credential definitions. This conversation can be initiated with the Digital trust team when requesting a new tenant or any time afterwards.
+For Governance questions, please refer to https://github.com/bcgov/bc-vcpedia .
+
+Once approval is obtained, it will be possible to select which ledger to connect to in write mode from the `Profile` section of your tenant.
+
+![Ledger Selection](../images/endorser-selection.png)
+
+## Endorsers
+
+When becoming an issuer, the agent will be connected with the role of `author` to an `endorser` who is responsible for "supporting" write transactions from authors.
+
+Endorsement requests are reviewed by the Digital Trust team and acted upon based on the published Governance. The Digital trust team may request adjustments in naming or other schema/credential definition settings in order to approve an endorsement request.
+
+!!! info "Note"
+It is generally allowed to publish new schemas and credential definitions in the development environment. Test and Production are gated behind an endorser that respects the published Governance.
diff --git a/docs/solutions/traction-overview.md b/docs/solutions/traction-overview.md
@@ -1,3 +1,36 @@
 # Traction
 
-## Work In Progress
+## What is Traction
+
+[Traction](https://github.com/bcgov/traction) is an application built on top of [Aries Cloudagent Python](https://github.com/hyperledger/aries-cloudagent-python) to facilitate the provisioning and management of tenant agents. With Traction, the DITP team does not need to prepare and deploy new agent instances for each adopter: users submit a request for a tenant and are able to self check-in and manage their settings when approved.
+
+## Tenants
+
+A tenant is a "resident" of Traction: similar to occupants of a condominium, different entities/organizations access the same resources, but remain isolated and independent.
+
+There are several instances of Traction that can be used for different purposes:
+
+- [Sandbox](https://traction-sandbox-tenant-ui.apps.silver.devops.gov.bc.ca): this instance is completely self-serve and can be used for prototyping and discovery of short-lived projects. The sandbox is reset automatically, on the 1st and 15th day of the month.
+- [Development](https://traction-tenant-ui-dev.apps.silver.devops.gov.bc.ca): this instance would be the first step after prototyping in the `sandbox` and requires a request to be created in-app and reviewed by the DITP team.
+- [Test](https://traction-tenant-ui-test.apps.silver.devops.gov.bc.ca) and [Production](https://traction-tenant-ui.apps.silver.devops.gov.bc.ca) access can be requested the same way as for `development`, once the integration is ready to move further.
+
+A Traction tenant provides full access to an Aries agent connected to pre-approved [ledgers](#ledgers), however the functionality to become `issuers` is not enabled by default: a request outlining the business case/requirement to become an issuer should be submitted to DITP when the tenant request is initially created, or any time after that when integrating with credential issuance processes becomes necessary.
+
+More information about becoming an issuer can be found [here](traction-becoming-an-issuer.md).
+
+## Ledgers
+
+The following table describes the ledgers supported for both read and write operations, for each environment.
+
+| Environment | [BCovrin Test](http://test.bcovrin.vonx.io) | [CANdy Dev](https://candyscan.idlab.org/txs/CANDY_DEV/domain) | [CANdy Test](https://candyscan.idlab.org/txs/CANDY_TEST/domain) | [CANdy Prod](https://candyscan.idlab.org/txs/CANDY_PROD/domain) | [Sovrin TestNet](https://indyscan.io/txs/SOVRIN_STAGINGNET/domain) | [Sovrin MainNet](https://indyscan.io/txs/SOVRIN_MAINNET/domain) |
+| ----------- | ------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------- |
+| Sandbox     | Write                                       | Read                                                          | Read                                                            | Read                                                            | Read                                                               | Read                                                            |
+| Development | Write                                       | Write                                                         | Read                                                            | Read                                                            | Write                                                              | Read                                                            |
+| Test        | Write                                       | N.A.                                                          | Write                                                           | Read                                                            | Write                                                              | Read                                                            |
+| Production  | N.A.                                        | N./A.                                                         | N./A.                                                           | Write                                                           | N./A.                                                              | Write                                                           |
+
+!!! info "Note"
+An issuer can only connect to ONE ledger in write mode at any given time. Moving to another ledger is generally not recommended and it is not supported at this time.
+
+!!! warning "Limitations"
+Sovrin TestNet and MainNet ledgers are connected in write mode only for special scenarios, like temporary support of legacy issuers moving to a Traction tenant.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -1,24 +1,25 @@
-site_name: "Digital Identity and Trust Program Documentation"
+site_name: "Digital Identity and Trust Program"
 site_description: "Technical and non-technical documentation for Digital Trust and Verifiable Credentials"
 docs_dir: "docs"
 repo_url: "https://github.com/bcgov/DITP"
 edit_uri: edit/main/docs
 nav:
-      - Introduction: index.md
-      - Digital Trust Patterns:
-              - Overview: pattern-overview.md
-              - Access Pattern: patterns/access.md
-              - Verifier Pattern: patterns/verifier.md
-              - Issuer Pattern: patterns/issuer.md
-      - Solutions:
-              - VC-AuthN and SSO: vc-authn-sso.md
-              - Traction:
-                      - Overview: traction-overview.md
-                      - Becoming an Issuer: traction-becoming-an-issuer.md
-              - OrgBook BC: orgbook-bc.md
-      - Need Help?: need-help.md
+        - Introduction: index.md
+        - Digital Trust Patterns:
+                  - Overview: overview.md
+                  - Access Pattern: patterns/access.md
+                  - Verifier Pattern: patterns/verifier.md
+                  - Issuer Pattern: patterns/issuer.md
+        - Solutions:
+                  - VC-AuthN and SSO: solutions/vc-authn-sso.md
+                  - Traction:
+                            - Overview: solutions/traction-overview.md
+                            - Becoming an Issuer: solutions/traction-becoming-an-issuer.md
+                  - OrgBook BC: solutions/orgbook-bc.md
+                  - Endorser Service: solutions/endorser-service.md
+        - About Us: about-us.md
 plugins:
-      - techdocs-core
-      - git-revision-date-localized
+        - techdocs-core
+        - git-revision-date-localized
 markdown_extensions:
-      - md_in_html
+        - md_in_html