Document Creator
You can use the document creator to create and issue your document.
To use this functionality, you will need a configuration file(.json file) and some pre-requisite informations.
What is document creator about?#
It's to provide a UI to the staffs that are involved with the daily operations who do not need to know anything about blockchain.
Why do we do this?#
Mainly because we want to cater to small firms or companies that doesn't really have the capabilities to build deep integration with their existing softwares or workflows.
How is this document creator helping small firms and companies?#
One way is for the IT department or someone who is tech savvy enough, can set up the configuration file and clerks or staffs can use this document creator to create the documents.
Pre-requisite#
Before you construct your configuration file(.json file), please ensure you have these:
- Wallet (
.jsonfile) - Document Store (for verifiable document)
- Token Registry (for transferable document)
- Configured DNS
- Decentralized Renderer
- Document Storage
Please refer to the approprate links to prepare them.
Configuration file#
The configuration file is a JSON file that contains information to configure the application to suit your business needs.
Config file structure#
Below is an example of the configuration file.
Let's break down the required fields for this config file.
We will need:
Network field#
The "network" field is a string that refers to the network in which the document is created in.
As of now, we only cater to 3 networks.
- Mainnet :
"homestead" - Ropsten testnet :
"ropsten" - Rinkeby testnet :
"rinkeby"
Wallet field#
The "wallet" field is a string that refers to your ethereum wallet. You can derive it from either one of these methods:
If you don't have a wallet, you can refer to Open Attestation's documentation to create a wallet. Note: you will need to have Open Attestation Cli installed. After running OA CLI
wallet createcommand, this will give you a wallet.json.Alternatively, you can also generate a wallet.json from an existing account created in Metamask using the OpenAttestation Cli. Note: you will need to have Open Attestation Cli installed. You will have to input your wallet's private key which can be found when you go to your account in Metamask, click on the menu icon, go to "Account Details" and click "Export Private Key". You can refer to the Metamask Support Page for a guided walkthrough. You will be prompted to input your Metamask password. Once you have your private key, you can key in the following command to generate a wallet.json:
You will then be prompted to set your wallet password. Once entered, you will see a success message with the path to your wallet.json:
Once you have an existing wallet.json, enter the following command to serialise it into a string:
The wallet string should be displayed on your terminal and you can enter it into the "wallet" field in the config file.
If you have an existing Metamask account but don't want to use the Open Attestation Cli, you can still get your wallet string doing this:
- Get your private key from Metamask (See option 2 if unsure)
- Open your terminal
- Navigate to a repository that has
ether.js - Type these commands line by line in the terminal:
(Note: you can watch a tutorial on this here at 7:29 onwards)
This result can now be entered into the "wallet" field in the config file.
Forms field#
The "forms" field is an array of form object which expect name, type, defaults and schema. attachments can also be added.
"name" field#
The "name" field is a string that refers to the name of the form that will display when creating the document, as shown in the image below.
"type" field#
The "type" field is a string that reters to the type of the document, either "TRANSFERABLE_RECORD" or "VERIFIABLE_DOCUMENT".
"defaults" field#
The "defaults" field is an object that contains the settings that you have that are constant among the different documents of the same kind of file.
Usually the document store address, token registry address, template, issuers, company logo, signatures, etc. are stored here, since they are a constant in the different documents of the same kind.
Default value of the form should also be stored here.
For example, you can store a default value for a "title" field here, this value will be used in the form shema as the value for the "title" field.
Below is an example of the "defaults" field:
"$template" field#
The "$template" field is an object that refers to the custom renderer, please refer to creating document renderer.
"issuers" field#
The "issuers" is an array of the issuer object. The required fields for each issuer are name, identityProof and one of documentStore OR tokenRegistry.
Transferrable document requires a tokenRegistry, whereas, a verifiable document requires a documentStore.
The "name" field in the "issuers" section is a string, which refers to the name of the token registry or the name of the document store.
Please refer to token registry for transferable document or deploying document store for verifiable document, for more information.
The "tokenRegistry" field is a string that is the address for the token registry, please refer to token registry for more information.
The "documentStore" field is a string that is the address for the document store, please refer to deploying document store for more information.
The "identityProof" field is an object that refers to the issuer identity, please refer to identity Proof for more information.
Note: any UI schema should be included under defaults as "uiSchema" field
"schema" field#
The "schema" field is an object used to generate a form. It follows JSON schema format.
The structure of the schema will derived from the structure of the document you expect to build and will be inline with the custom renderer that you have built for this document.
It will probably be a subset of an already existing schema without the data that you expect to be constants across your document.
An example of the "schema" field:
"Attachments" field#
The "attachments" field contains the information about the required attachments for this document.
If there are no attachment for the particular form that you are creating, please set "allow" field to false.
An example of the "attachments" field:
The "allow" accepts a boolean value(true or false) and it will display the attachment section based on this value.
The "accept" accepts an array of string, that are file types, which will set the accepted file types for the attachments.
If you want to accept all file types, remove the entire "accept" line from "attachments" object.
Document Storage field#
Note: This document storage field is optional. Only add this section in if you want to generate a QRcode for easy sharing.
If you do not want to upload your documents to a document storage endpoint you can omit this in the config file.#
To use a document storage endpoint, you will have to have the endpoint infrastructure already set up and configured.
You can refer to infra template's storage section for more information.
The "documentStorage" field is an object which expects an "url" field. "apiKey" can also be added.
"apikey" field#
The "apikey" field is optional, it accepts a string as the API key.
If your document storage endpoint does not requires an API key, you should omit this field.
"url" field#
The "url" field accepts a string which will be the endpoint of the document storage.
Note: please ensure that this document storage endpoint has a path "/storage/queue" that will return the queue number for storing your document in the document storage endpoint.
For the convenience of developers, we provide the below document storage endpoints for the Ropsten and Rinkeby testnets.
Ropsten document storage endpoint#
Rinkeby document storage endpoint#
These endpoints may only be used for valid and issued documents on the respective test networks, and may not be mixed.
For example, a valid Ropsten document will fail validation and fail to be uploaded if the Rinkeby endpoint is specified.
An API key is not required to be provided for these endpoints as they will accept unauthenticated requests.
Note: The testnet endpoints do not retain documents permanently and any stored documents will be removed after a period of time.
Generic Template (Cover Letter)#
We have designed and created a simple generic template (cover letter) config file for you to use.
Click here to download a config file.
Above is an example of how the generic cover letter will look like.
To make full use of this generic template (cover letter), please update the config file as following.
Fields to update#
Note: Please replace all the placeholder "<...>" with your values.
"network"- Update with the desired network. For more information, click here."wallet"- Update with your wallet string. For more infomation, click here.
"documentStore"- Update with your document store. For more infomation, click here."location"- Update with the Issuer's domain. For more information, click here."logo"- Update with the Logo's URL, to be displayed accordingly as the image above."backgroundColor"- Update with the desired background color. The default color(#ffffff) will be used if color is not stated here. i.e. values for this field "#000000", "black""titleColor"- Update with the desired title text color. The default color(#4e4e50) will be used if color is not stated here. i.e. values for this field "#ffffff", "white""descriptionColor"- Update with the desired description text color. The default color(#4e4e50) will be used if color is not stated here. i.e. values for this field "#ffffff", "white""title"- Update with the default title for the document."remarks"- Update with the default remarks for the document.
"apiKey"- Update with the document storage API key. For more infomation, click here."url"- Update with the document storage URL. For more infomation, click here.
Note: The "documentStorage" field is optional, if you do not have any document storage endpoint setup, you can omit this entire section..
Generic Template (Transferable Record)#
We have designed and created a simple generic template (bill of lading) config file for you to use.
Click here to download a config file.
Above is an example of how the generic bill of lading will look like.
To make full use of this generic template (bill of lading), please update the config file as following.
Fields to update#
Note: Please replace all the placeholder "<...>" with your values.
"network"- Update with the desired network. For more information, click here."wallet"- Update with your wallet string. For more infomation, click here.
"tokenRegistry"- Update with your token registry. For more infomation, click here."location"- Update with the Issuer's domain. For more information, click here."blNumber"- Update with the BL Number, to be displayed accordingly as the image above."companyName"- Update with the Company Name, to be displayed accordingly as the image above."field#"- Update with the Field content, to be displayed accordingly as the image above.