Template Generator

Now that you have executed an existing template, let's create a new template from scratch. To facilitate the creation of new templates, Cicero comes with a template generator.

The template generator

Install the generator

If you haven't already done so, first install the template generator::

npm install -g yo
npm install -g yo @accordproject/generator-cicero-template

Run the generator:

You can now try the template generator by running the following command in a terminal window:

yo @accordproject/cicero-template

This will ask you a series of questions. Give your generator a name (no spaces) and then supply a namespace for your template model (again,no spaces). The generator will then create the files and directories required for a basic template (similar to the helloworld template).

Here is an example of how it should look like in your terminal window:

bash-3.2$ yo @accordproject/cicero-template 

     _-----_     ╭──────────────────────────╮
    |       |    │      Welcome to the      │
    |--(o)--|    │ generator-cicero-template │
   `---------´   │       e generator!       │
    ( _´U`_ )    ╰──────────────────────────╯
    /___A___\   /
     |  ~  |     
   __'.___.'__   
 ´   `  |° ´ Y ` 

? What is the name of your template? mylease
? Who is the author? me
? What is the namespace for your model? org.acme.lease
   create mylease/README.md
   create mylease/logo.png
   create mylease/package.json
   create mylease/request.json
   create mylease/logic/logic.ts
   create mylease/model/model.cto
   create mylease/test/logic_default.feature
   create mylease/text/grammar.tem.md
   create mylease/text/sample.md
   create mylease/.cucumber.js
   create mylease/.npmignore
bash-3.2$ 

tip

You may find it easier to edit the grammar, model and logic for your template in [VSCode Extension]VSCode Extension: an Accord Project extension (Concerto) to the popular Visual Studio Code Editor

For more information on how to use VS Code with the Accord Project extension, please consult the Using the VS Code extension tutorial.

Test your template

If you have Cicero installed on your machine, you can go into the newly created mylease directory and try it with cicero, to make sure the contract text parses:

bash-3.2$ cicero parse
11:51:40 AM - info: Using current directory as template folder
11:51:40 AM - info: Loading a default text/sample.md file.
11:51:41 AM - info:
{
  "$class": "org.acme.lease.MyContract",
  "name": "Dan",
  "contractId": "4a7d5b59-0377-42d3-aa41-15062398d25d",
  "$identifier": "4a7d5b59-0377-42d3-aa41-15062398d25d"
}

And that you can trigger the contract:

bash-3.2$ cicero trigger 
11:58:22 AM - info: Using current directory as template folder
11:58:22 AM - info: Loading a default text/sample.md file.
11:58:22 AM - info: Loading a default request.json file.
11:58:23 AM - warn: A state file was not provided, initializing state. Try the --state flag or create a state.json in the root folder of your template.
11:58:23 AM - info:
{
  "clause": "mylease@0.0.0-d186ab29c448b0058e4465a54d8376c3817dddb6fda8dc0ca29a88151b3dbecc",
  "request": {
    "$class": "org.acme.lease.MyRequest",
    "input": "World"
  },
  "response": {
    "$class": "org.acme.lease.MyResponse",
    "output": "Hello Dan World",
    "$timestamp": "2021-06-16T12:29:50.317-04:00"
  },
  "state": {
    "$class": "org.accordproject.runtime.State",
    "$identifier": "03515461-7ee7-4c81-a8f0-d4c667db5f4c"
  },
  "emit": []
}

The template also comes with a few simple tests which you can run by first doing an npm install in the template directory, then by running npm run test:

bash-3.2$ npm install 
bash-3.2$ npm run test 

> mylease@0.0.0 test /Users/jeromesimeon/tmp/mylease
> vitest run

 ✓ logic.test.ts (1 test)

 Test Files 1 passed (1)
      Tests 1 passed (1)
   Start at 12:01:05
   Duration 1.25s
bash-3.2$ 

Edit your template

Update Sample.md

First, replace the contents of ./text/sample.md with the legal text for the contract or clause that you would like to digitize.

Check that when you run cicero parse that the new ./text/sample.md is now invalid with respect to the grammar.

Edit the Template Grammar

Now update the grammar in ./text/grammar.tem.md. Start by replacing the existing grammar, making it identical to the contents of your updated ./text/sample.md.

Now introduce variables into your template grammar as required. The variables are marked-up using {{ and }} with what is between the braces being the name of your variable.

Edit the Template Model

All of the variables referenced in your template grammar must exist in your template model. Edit the file model/model.cto to include all your variables, making sure the name of the model property matches the name of the variable in the ./text/grammar.tem.md file.

Note that the Concerto Modeling Language primitive data types are:

String: for character strings
Long or Integer: for integer values
DateTime: for dates and times
Double: for floating points numbers
Boolean: for values that are either true or false

tip

Note that you can import common types (address, monetary amount, country code, etc.) from the Accord Project Model Repository: https://models.accordproject.org.

Edit the Transaction Types

Your template expects to receive data as input and will produce data as output. The structure of this request/response data is captured in the MyRequest and MyResponse transaction types in your model namespace. Open up the file model/model.cto and edit the definition of the MyRequest type to include all the data you expect to receive from the outside world and that will be used by the business logic of your template. Similarly edit the definition of the MyResponse type to include all the data that the business logic for your template will compute and would like to return to the caller.

Edit the Template Logic

Now edit the business logic of the template itself. Template logic is written in TypeScript using a class-based pattern. Open the file logic/logic.ts and edit the trigger method to perform the calculations your logic requires.

For example, a basic TypeScript logic class looks like this:

import { MyContract, MyRequest, MyResponse } from './model/model';
import { TemplateLogic } from '@accordproject/cicero-core';

class MyLogic extends TemplateLogic<MyContract> {
  async trigger(data: MyContract, request: MyRequest): Promise<{ response: MyResponse }> {
    const response: MyResponse = {
      $class: 'org.acme.lease.MyResponse',
      output: `Hello ${data.name} ${request.input}`,
    };
    return { response };
  }
}

Looking at the TypeScript logic for other example templates in the cicero-template-library will help you understand the syntax and capabilities.

Publishing your template

If you would like to publish your new template in the Accord Project Template Library, please consult the Template Library Section of this documentation.

The template generator​

Install the generator​

Run the generator:​

Test your template​

Edit your template​

Update Sample.md​

Edit the Template Grammar​

Edit the Template Model​

Edit the Transaction Types​

Edit the Template Logic​

Publishing your template​