contract-generator

Automatic contract generation based on templates.

Templates are stored in a separate Github repository.

Usage

Accessing a URL of the form

https://[host]/contract/[name]/[date]?arg1=val1&arg2=val2&...

creates a contract based on AsciiDoc template [name].adoc and variables generated by [name].js using EMS data as of [date] in the format YYYY-MM-DD. For example,

https://contract.vacuumlabs.com/contract/IT_SZCO_Combi/2020-07-01?id=miroslav.mrozek&signing_date=31.08.2020

creates a contract based on IT_SZCO_Combi.adoc and IT_SZCO_Combi.js for Jira ID miroslav.mrozek using EMS data as of July 1, 2020. Every query has 2 required arguments:

id: Jira ID or a list of comma separated Jira IDs. Single ID returns a PDF, list of IDs returns a ZIP containing all contracts in PDF
signing_date: signing date can be in any format, this is exactly how it is formatted in the output contract

These can be followed by any number of optional arguments, which are then passed as arguments to the template function.

Pandadoc

Replace contract with contractPandadoc to automatically email the generated contracts to the management to sign it via Pandadoc:

https://[host]/contractPandadoc/[name]/[date]?arg1=val1&arg2=val2&...

Contribute

At the moment, it is not possible to run the project locally. Instead, create preview deployments on Vercel to see any changes.

Ask project owner to get credentials to Vercel and go to Vercel project overview.
Run yarn global add vercel from command line to install Vercel CLI. Have a look at Vercel CLI reference.
Run vercel login and use the same credentials as for the web app to login to Vercel CLI.
Run vercel switch vacuumlabs to switch your team to Vacuumlabs.

Run vercel from project directory to create a preview deployment. After the build is ready, access the latest preview deployment using contract-generator-vlnow.vacuumlabs1.vercel.app as a host. Inspect the deployment and view console logs using the link returned by Vercel CLI. Additionally, any change to (any branch of) contract-generator deploys automatically to Vercel - either as a production (master branch) or a preview (any other) deployment. Note that any deployment takes template functions from the master branch of contracts repo.

Under the Hood

The JavaScript file [name].js contains a single function with the signature

function(query, person) => ({
    'asciidoc-var1': value1,
    'asciidoc-var2': value2,
    ...
})

where query is an object containing arguments passed in the request, i.e., at least id and signing_date. This lambda function is evaluated in evalFunction.jsand its output -- a map from Asciidoc variables to values -- is passed to Asciidoctor in utils/createHtmlContracts.js, which translates the [name].adoc template into a contract in HTML, and utils/createPdfContracts.js styles into a PDF. Requests are handled and contracts/ZIP archives/emails are generated in contract.js or contractPandadoc.js.

Google Sheets Integration

Some templates use data from one or more Google Sheets. Spreadsheet, sheet ID and range are specified in the template function. The first row of the range is a compulsory header, where column names are used to index the object returned from loadSheetData and to join on EMS data.

The template function in [name].js then has the signature

function({loadSheetData}, person) => ({
    'asciidoc-var1': value1,
    'asciidoc-var2': value2,
    ...
})

where loadSheetData(person, sheet) is a callback defined in utils/sheets.js, person is EMS data of the person with a given Jira ID and sheet is an object with the following properties:

spreadsheetId: extract it from the spreadsheet URL https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=0
sheetId: extract it from the spreadsheet URL https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=sheetId
range: empty range returns the non-empty part of the sheet, otherwise use A1 notation to specify a subset of the sheet
idSheetsColumn: name of the column in the spreadsheet used to join EMS data
idEMSField: name of the EMS field used to join spreadsheet data

The object sheet is defined in a contract template. See more detailed definitions of Spreadsheet ID, Sheet ID and A1 notation here.

Authorization

The project uses JWT authorization to access Google Sheets. If adding a new sheet, define it in the contract template and share the sheet with the service account contract-generator@contracttest-1597670081537.iam.gserviceaccount.com (by clicking Share button in the Google Sheet).

If you want to set authorization for the first time or change the service account:

Create a project in Google Console.
In the project, allow access to Google Sheets API.
Create a service account and generate an API key.
Share all Google Sheets with the service account (by clicking Share button in the Google Sheet).
Convert the private API key into base64 (make sure that newlines are in the correct format).
Set environment variables GOOGLE_EMAIL to the service account email and GOOGLE_KEY to the API key in base64.