Document

Document Object

Field	Type	Description
id	snowflake	the document's id
number	integer	the sequential number for the document within an organisation
type	snowflake	the type of document
organisation_id	snowflake	the id of the organisation
title	string	the title of the document (2-200 characters)
created_by	user object	the creator of the document
created_at	ISO8601 timestamp	when the document was created
release_revision_hash	hash	the crytographic hash corresponding to current released revision
last_number	integer	the largest number currently issued to a clause, ensures no conflicts
forked_from	snowflake	the forked document's id
forked_revision	hash	the forked document revision's hash

Document Branch Object

There is always a release branch and a draft branch. Initially only the draft branch will contain a document revision object.

Field	Type	Description
id	snowflake	the document revision's id
name	string	the branch name (2-50 characters)
created_by	user object	the creator of the document branch
created_at	ISO8601 timestamp	when the document branch was created

Document Revision Object

Field	Type	Description
id	snowflake	the document revision's id (do we even need this?)
hash	hash	the crytographic hash of the revision contents
branch	document branch	the revision's branch
revision	string	the revison for the document within an organisation (1-10 characters) or null
title	string	the title of the document revision (2-200 characters)
created_by	user object	the creator of the document revision
created_at	ISO8601 timestamp	when the document revision was created
previous_revision_hash	hash	the crytographic hash corresponding to the previous revision

Document Type Object

Field	Type	Description
id	snowflake	the document type's id
organisation_id	snowflake	the id of the organisation
name	string	the type's name (2-20 characters)
description	string	a description of the type
last_number	integer	the largest number currently issued to a document
number_format	string	a string formatter
revision_format	integer	revision format

Document Sheet Object

Field	Type	Description
id	snowflake	the document sheet's id
document_id	snowflake	the id of the document

Document Revision Sheet Object

Implements Orderable

Field	Type	Description
revision_id	snowflake	the document revision's id
sheet_id	snowflake	the document sheet's id
name	string	the document sheet's name (2-20 characters)
order	integer	the order of the sheet within the document

Document Column Object

Field	Type	Description
id	snowflake	the document columns's id
document_sheet_id	snowflake	the id of the document sheet

Document Revision Column Object

Implements Orderable

Field	Type	Description
revision_id	snowflake	the document revision's id
column_id	snowflake	the document sheet's id
name	string	the document column's name (2-20 characters)
description	string	a description of the document column
type		the document column's data type
conditional_formatting	string	the conditional formatting condition

Document Clause Object

Field	Type	Description
id	snowflake	the document clause's id
document_sheet_id	snowflake	the id of the document sheet
number	integer	clause number

Document Revision Clause Object

Implements Orderable

Field	Type	Description
revision_id	snowflake	the document revision's id
clause_id	snowflake	the document clause's id
text	string	the clause text (maximum 16 MiB including base 64 encoded image data)
fields	list of document fields	the document field values

Document Field Object

Field	Type	Description
column_id	snowflake	the document column's id
clause_id	snowflake	the document clause's id
value	string	the document field value
background_colour	string	hex colour value

Document Data Types

Document Data Units

Document Data Formats

Value	Name	Description
0	String	String
1	Decimal	Decimal number format 0.0000
2	Scientific	Scientific notation 0.0000x10^0
3	Engineering	Scientific notation where the exponent is a multiple of 3 [..., -6, -3, 0, 3, 6, ...]
4	Time	Instead of second, expressed in dd:hh:mm:ss
5	Unixtime	Number of seconds or milliseconds since the unix epoch expressed in ISO date format

Document Revision Field Object

Field	Type	Description
revision_id	snowflake	the document revision's id
field_id	snowflake	the document field's id

Document View Object

The document view object describes which columns to show and in which order. Views can be inherited from forked documents.

Field	Type	Description
id	snowflake	the document view's id

Document View Column Object

Field	Type	Description
view_id	snowflake	the document view's id
column_id	snowflake	the document column's id
order	integer	the order to display the columns in

Document Merge Request Object

Field	Type	Description
organisation_id	snowflake	the organisation the merge request belongs to
number	integer	a sequential number for the merge request
from_branch_id	snowflake	the branch to merge
to_branch_id	snowflake	the branch to be merged to
workflow_id	snowflake	the workflow that will trigger the merge
user	user object	the creator of the document merge request
created_at	ISO8601 timestamp	when the document merge request was created

Revision Format

Name	Value	Description
none	0	No numbering scheme, use this if you issue numbers from another system. This will allow the user to manually assign both the document number and the revision.
zero	1	This scheme uses the integer numbers starting at 0.
one	2	This scheme uses the integer numbers starting at 1.
major_minor	3	This scheme uses a version number of the scheme Major.Minor allowing either the Major or the Minor component to be incremented.
major_minor_revision	4	This scheme uses a version number of the scheme Major.Minor.Revision allowing either the Major or the Minor component to be incremented. The Revision component is always incremented.
alphabet	5	This is the default scheme and uses the letters A-Z skipping "I", "O", "Q", "S", "X", "Z". The initial revision is denoted by a dash "-".
alphabet_all	6	This scheme uses the letters A-Z with the initial revision denoted by a dash "-".

Clause Number Format

Name	Value	Description
number	0	Document number
number_revision	1	Document number plus revision

Create Document

POST /documents

Parameters

Field	Type	Description
title	string	the document's title (2 - 200 characters)

Fork Document

POST /documents/{document.id}

This operation will create a fork of the document. The new document will be returned.

Create Document Branch

POST /documents/{document.id}/branches

Parameters

Field	Type	Description
name	string	the document branch's name (2 - 50 characters)

Create Document Sheet

POST /documents/{document.id}/revisions/{revision.hash}/sheets

This operation will create a new revision on the branch. The new revision will be returned. If the change cannot be merged then an error code will return.

{
    "id": 123456,
    "hash": abdf12,
    "branch": {
        "id": 5678,
        "name": "draft",
        "user": { },
        "created_at": "2019-07-01T00:00:00+00:00",
    }
}

Parameters

Field	Type	Description
name	string	the document sheet's name (2 - 20 characters)

List Document Columns

GET /documents/{document.id}/revisions/{revision.hash}/columns

Get a list of columns for this revision of the document. Returns an array of document revision column objects.

Create Document Column

POST /documents/{document.id}/revisions/{revision.hash}/columns

This operation will create a new revision on the branch. The new revision will be returned. If the change cannot be merged then an error code will return.

{
    "id": 123456,
    "hash": abdf12,
    "branch": {
        "id": 5678,
        "name": "draft",
        "user": { },
        "created_at": "2019-07-01T00:00:00+00:00"
    }
}

Modify Document Column

PATCH /documents/{document.id}/revisions/{revision.hash}/columns/{column.id}

Parameters

Field	Type	Description
name	?string	the document column's name (2-20 characters)
description	?string	a description of the document column
type	?	the document column's data type
conditional_formatting	?string	the conditional formatting condition

Delete Document Column

DELETE /documents/{document.id}/revisions/{revision.hash}/columns/{column.id}

This operation will delete a column from a revision on the branch and create a new revision on the branch. The new revision will be returned. If the change cannot be merged then an error code will return.

Create Document Clause

POST /documents/{document.id}/revisions/{revision.hash}/clauses

This operation will create a new revision on the branch. The new revision will be returned. If the change cannot be merged then an error code will return.

Parameters

Field	Type	Description
after	?snowflake	the clause to insert the new clause after
before	?snowflake	the clause to insert the new clause before

Modify Document Clause

PATCH /documents/{document.id}/revisions/{revision.hash}/clauses/{clause.id}

Parameters

Field	Type	Description
after	?snowflake	the clause to move the clause after
below	?snowflake	the clause to move the clause below

Delete Document Clause

DELETE /documents/{document.id}/revisions/{revision.hash}/clauses/{clause.id}

This operation will delete a clause from a revision on the branch and create a new revision on the branch. The new revision will be returned. If the change cannot be merged then an error code will return.

Update Document Field

PATCH /documents/{document.id}/revisions/{revision.hash}/fields

This operation will create a new revision on the branch. The new revision will be returned. If the change cannot be merged then an error code will return.

This operation will cause all calculations to re-calculate.

Parameters

Field	Type	Description
clause_id	snowflake	the clause the updated field belongs to
column_id	snowflake	the column the updated field belongs to
value	string	the new value of the field

{
    "id": 123450,
    "hash": abdf12,
    "user": {},
    "created_at": "2019-07-01T00:00:00+00:00",
    "fields": [
        {
            "column_id": 123453,
            "clause_id": 123454,
            "value": "field value",
            "background_colour": ""
        } 
    ]
}

Get Document Revision

GET /documents/{document.id}/revisions/{revision.hash}

GET /documents/{document.id}/branches/{branch.name}

A document revision can be retrieved either by specifying a specific branch by name to get the latest revison, or by a specific revision's hash.

{
    "id": 123450,
    "hash" abdf12,
    "user" { },
    "created_at": "2019-07-01T00:00:00+00:00"
}