ClauseBase provides facilities for the semi-automtic upload and dissection of existing text documents. While this facility will not automagically insert complex legal logic, it does allow you to skip tedious copy-paste operations.

User interface overview

You start the upload process by clicking on  in the top menu bar. (Only advanced users will see this button.)

  1. Multiple upload environments can be simultaneously opened. Click this button to create a new upload environment.
  2. Switch between opened upload environments by clicking on the relevant tab.
  3. You can simultaneously show one, two or three editor panes. Each pane can host a different editor, which can be changed through the blue button in the upper left corner of each pane. (Note that you can even show the same editor in multiple panes, which can allow you to avoid excessive scrolling in a long list.)
  4. General undo/redo buttons per environment
  5. First editor pane
  6. Second editor pane (if at least two panes are made visible)
  7. Third editor pane (if three panes are made visible)

General workflow overview

The general workflow for uploading documents is as follows:

  1. Upload an existing document from your hard drive or server.
  2. Review the proposed structure of the clauses.
  3. Review and apply defined terms.
  4. Insert datafields.
  5. Review cross-references between clauses.
  6. Assign clauses to folders.
  7. Convert the clauses to ClauseBase grammar.
  8. Export the clauses to a chosen location.

Uploading clauses

After you have created a new upload environment by clicking the icon at the right, the only action you can take is to effectively upload an existing text document. You do so by clicking on the upload button (upper left corner of the document editor) and navigating to the right file on your hard disk or file server:

ClauseBase not only accepts .DOC and .DOCX files, but also commonly used other text file formats, such as .TXT and .RTF.

After a few seconds, you will see the result of the uploading process in the document editor.

Reviewing the clause structure

At document upload, the software will perform an automatic analysis of the structure of the clauses contained in the document.

Depending on the contents of the document, the layout that was applied to it and the correct use of the MS Word document structure functionality, the analysis can be perfect or require some alteration.

Clause hierarchies expressed through indentation, bold fonts and MS Word styles will generally lead to better results.

For each block of text, you will have to take a decision on the following elements:

  • Which paragraphs should be put together into a single file?

Generally speaking, splitting clauses into many different files (e.g., one file per paragraph) will take a bit more time, and increase complexity somewhat, but will also allow for higher flexibility because you can easily swap individual paragraphs. If, however, paragraphs will always be printed together, paragraph swaps are irrelevant, and reuse of individual paragraphs is also irrelevant, then it is probably a better idea to keep paragraphs of one or more clauses together into a single file.

  • How should paragraphs and blocks hierarchically relate to each other?

Altering the clause structure is a quick and painless process, through the use of interactive buttons that appear when you hover the mouse above a clause. The following options are available (although not all at the same time):





change the block into a sub-block of its predecessor


convert a sub-block into a "sibling" of its parent block

hold down Shift when clicking this button to unindent all siblings at the same level


merge a block with its preceding sibling block


skip the contents of this paragraph — upon conversion, this paragraph will be ignored


re-enable this paragraph, so that its contents will once again be included upon conversion

treat as title

treat this paragraph as the title of a clause

treat as regular paragraph

convert the title paragraph into a regular paragraph

force new file

force this block (and all the sibling blocks below it) to be put into separate files

don't force new file

unapply the "force new file" setting, so that the block will be put into the same file as its parent block

ClauseBase will visually show the relationship between blocks and paragraphs:

  • title paragraphs are shown with a light purple background
  • disabled paragraphs are shown with a light orange background and strikethrough text
  • blocks of text are shown with a grey border. All text within the grey border that is not surrounded itself by a dotted border, will be put into the same file. For example, in the screenshot above, the paragraphs "ClauseBase - Terms & Conditions" and "These Terms and Conditions apply ..." will become part of the same file, while all the other text ("1. Definitions", "Account ..." and "ClauseBase ...") will be put in a second file.
  • a block with a dotted purple upper border will be put in a separate file
  • blocks can contain one or more paragraphs of text, which can be independently moved
  • blocks and paragraphs can be merged, split up, indented and outdented

Defined terms

If you want to make of ClauseBase's grammatical features, it is important to correctly identify defined terms in the uploaded document. Each instance of a defined term will eventually be converted into a Concept, represented with a #hashtag in the ClauseBase grammar of a clause.

For example, a fragment such as "The Customer shall be responsible for ..." will get converted into "#Customer shall be responsible for ...". As explained elsewhere in this documentation, using this #hashtag allows for facilities such as automated replacement of terms, automatical insertion or deletion of articles, capitalisation styling, and so on.

List of defined terms

Upon import, ClauseBase will automatically compile a list of frequently encountered, capitalized words that may be eligible to become defined terms. This list is shown in the terms editor.

In this table, the following columns are shown:

  • the first column shows the defined terms themselves as included in the uploaded document
  • the second column shows the Concept that is currently mapped to the defined term
  • the third column show the code that will be used inside the ClauseBase grammar for this Concept
  • the fourth column contains an icon that allows you to delete a defined term

Each defined term should eventually get mapped to a Concept. Upon import, ClauseBase will check its database to see whether certain defined terms were previously mapped to certain Concepts — if so, that mapping will be automatically established for you. Defined terms for which no previously used Concept could be found in the database will be shown as unspecified. However, with the icon at the right side of the second column, you can always map a defined term to another Concept, or even create a new Concept on the fly.

Visually editing defined terms in the uploaded document

The defined terms will also be visualized in the editor when you click on the subpane. Each defined term will be shown with a light blue background, while associated articles are shown with a yellow background. To help you identify relevant candidates for defined terms (which typically consist of nouns), nouns are shown in a black font, while other word types are shown in grey.

Removing instances of a defined term

It will sometimes happen that a specific instance of a defined term should not be treated as a defined term after all.

For example, even if in a certain contract the word "Party" is a defined term (referring to either the supplier or the customer), some instances of this word should not be treated as a defined term — e.g., in the phrase "if any third party would be providing access...".

In the the subpane of the editor, you can quickly remove individual instances of a highlighted defined term by holding down Shift and clicking on the incorrectly applied defined term with the blue background.

Adding new instances of a defined term

When you add a defined term, all words in the document that match that defined term, will be automatically associated with that defined term. If you deleted an individual instance of a defined term, and later on would like to re-establish that instance, you can simply click and drag over the words of the defined term with your mouse. When your mouse is released, the words that together make up the defined term, will be highlighted in light blue.

Establishing and removing associated articles

ClauseBase will try to automatically associate articles with the nouns of a defined term. By hovering over a defined term, the associated article will light up (and vice versa). If an article was invalidly associated with a defined term, you can hold down Shift and click on the article to break the association.

If a certain article is not yet associated with a defined term, but should be associated with it, you can simply drag from the article to the defined term (i.e., release the mouse when hovering over the defined term).

Articles do not need to be immediately followed by the defined terms they should be associated with. It is perfectly OK if some words are positioned in between.
Forcing articles into defined articles

As explained below, associated articles will get removed upon conversion. The default option is to convert a fragment such as "... the customer shall ..." into "... #customer shall ...". While undefined articles and "this-articles" will get a special modifier inside the converted hashtag (e.g. "... this customers shall ..." will get converted into "... #°customer shall ... ", while " ... a customer shall" will get converted into "... #?customer shall ..."), defined articles will not.

In most contracts, this is exactly what you want, because this will allow you to dynamically define in the converted contract whether you want a certain defined term to (always or never) be accompanied by an associated article. However, there are occasions when you want to force the use of a defined article, i.e. to convert "... the customer shall ... " into "... #+customer shall ...".

To do so, you have to alt-click on the article. You will notice that the article will then receive a pink background. Alt-click again on the article to remove the forced conversion into a defined article.


ClauseBase allows you to immediately apply (new or existing) datafields during the import process.

Editing available datafields

You can inspect the available datafields through the  editor.

Each Concept that is loaded into the current upload environment, will be shown in the list, together with their #hashcode for the ClauseBase grammar, and all of the datafields.

For Concepts that can be edited by the current user, new datafields can be added through the button. The other properties of the Concept can be edited though the  button.

Concepts can be un-loaded by clicking on the  button at the right. Note that this does not physically delete an existing Concept from the database — it only removes the Concept from the current upload environment.

It is not possible to remove Concepts that are currently in use by the upload environment — e.g., because a defined term is associated with this Concept, or because some term is associated with a datafield of this Concept. You will get a warning when trying to remove such Concept.
Assigning datafields

You can assign datafields through the subpane of the editor.

In this subpane, you can simply drag over a text fragment that should be replaced by a specific datafield. Once the mouse is released, a pop-up menu with all available Concepts and their datafields.

The most recently used datafields are listed at the top of this pop-up menu.

Once some text fragment has been replaced with a datafield, that datafield will be shown in green (as is the case with #contract^duration in the screenshot above).

To delete an existing datafield, hold down Shift and click on the green text. The original text will then re-appear.

To add a new datafield, open the concepts editor, scroll through the relevant Concept, and click on the button. (You will, obviously, need to have editing rights for that Concept). Once the new datafield is added there, it will also appear in the pop-up menu of the  subpane.


In ClauseBase, cross-references between clauses are subject-based instead of number-based. Accordingly, cross-references should point to certain subject matters, instead of specific article numbers. MS Word files, however, use number-based cross-references. The  editor is intended to cross that bridge.

The cross-reference editor shows each paragraph that is the target of at least one cross-reference, along with the Concept (and its code) that it is said to implement.

For example, in the screenshot above, paragraph 2.1 is target reference of a cross-reference elsewhere in the text of the MS Word document — e.g., a paragraph 9.8 that would state "... as set forth in clause 2.1". Paragraph 2.1 is currently specified to implement Concept "license", by using code #license in the ClauseBase grammar. Upon conversion:

  • paragraph 2.1 will have an implementation link towards the license Concept.
  • paragraph 9.8 will state in the ClauseBase grammar "... as set forth in §license"

In the cross-references table, you can change the implementation Concept by clicking on the  button. You can then either choose an already loaded Concept from the list, or choose to load another Concept, or create a new Concept.

Changing the #code of the Concept, will also change this code for defined terms and datafields.

Assigning folders

In any document with more than a few clauses, you will probably want to store clauses into different folders.

To specify in which (sub)folder certain clauses must be stored, you use the  editor.

All those folders become (sub-sub-sub...) folders of the folder in which the exported clauses will end up being stored.

The  editor lets you create an unlimited number of folders and sub-folders, any level deep you desire.

  • In many cases, you will want to quickly create folders for all the clauses at the highest level, i.e. those clauses that have no "parent" clause themselves, and will typically be numbered 1., 2., 3. etc. To do so, click on the  button (Note that this button will disappear as soon as any other folder exists.) ClauseBase will then create folder-labels by taking up to 70 characters from each top-level clause.
  • To create a new top-level folder, click the button at the top right of the  editor.
  • To create a new sub-folder, click the  button at the right of the relevant "parent" folder.
  • To reorder or delete a folder, click any of the  buttons.
It is not necessary to create a folder for Concepts and definition clauses. Those will be stored in automatically generated subfolders.

Converting the clauses to ClauseBase grammar

Once you have altered the structure of the clauses, and optionally assigned defined terms, datafields and subfolders, you are ready to actually convert clauses into the ClauseBase grammar.

In order to convert an individual block, you first have to select it, by clicking on the grey dot that appears at its left side when you hover over a block.

The  will now show a green button that invites you to convert the selected block:

You can only select blocks that are specified to be converted into a separate file (as visually indicated by a dotted top border. If you cannot select a certain block, then this block will get converted as part of a (grand)parent block.

When you click this button, ClauseBase will perform the conversion and show the familiar content editor inside the :

Instead of clicking on a clause to select it, and then clicking the button inside the , you can also double-click on the grey dot that appears when you hover over a block. If you hold down Shift when double-clicking, all sibling blocks will be converted as well. Accordingly, if you hold down Shift and double-click on any top-level block, all those top-level blocks will be converted at once.
Choosing the folder where to store the converted clause

You will probably want to specify the subfolder in which this clause will get stored, by choosing the relevant folder from the popup-list. If you do not choose a subfolder, then the clause will get stored in the top-level folder.

"Child" clauses will automatically end up in the same subfolder as their "parent" clause, unless you choose a(nother) subfolder for the child clause.

Other points of attention during conversion
  • Defined terms are converted into #hashtags, with their associated article removed. Those #hashtags get an initial capital when necessary.
  • Associated articles are removed, but may get integrated into the defined terms, in different ways:
    • "this" (French: "ce / cette / ces", Dutch: "dit / deze") will get converted into #°hashtag
    • Undefined articles (English: "a / an", French": "un / une / des", Dutch: "een") will get converted into #?hashtag.
    • Defined articles (English: "the", French: "le / la / les", Dutch: "het / de") will get converted into #hashtag, unless those articles were forced to get converted into a defined article, because the user alt-clicked on the article. In such case, the article will get converted into #+hashtag.
  • The original clause numbers are replaced by 1., 2., or sub-articles thereof (1.1, 1.2, etc.).
  • The filename of a clause will be generated on the basis of the first 10 words of the contents. The filename of a definition will be the name of its Concept.
  • When the converted clause is the target of a cross-reference, and a Concept is associated with that clause, then an implementation link will be included in the links section.
Errors during conversion

When errors occur, you will get an error message at the bottom of the screen.


Description & solution

Missing Concept for a defined term

Go to the editor, and choose a Concept for the defined term (or create a new one, or load a Concept from the database).

Missing cross-reference

When your original MS Word document refers to a certain clause (e.g., clause 2.1), but you did not associate that target clause with a certain implementation Concept, the cross-reference will be converted into §#xxx-undefined-term-xxx.

To resolve this error, you can either add an implementation Concept to the target clause (through the editor), or manually edit the §#xxx-undefined-term-xxx in the ClauseBase grammar (e.g., refer to some other Concept, or remove it).

Grammatical errors

If your source document contains characters that have a special meaning in the ClauseBase grammar — e.g., [square brackets] or {curly parentheses} — then these characters may cause errors. You will have to manually resolve these errors by editing the text.

Removing and re-applying conversions

If you are no longer interested in converting a block to ClauseBase grammar, you can click on the  button. The block when then no longer be included in the list of exported clauses.

You may instead also be interested in re-applying the conversion. This can be useful when you received errors during your first conversion attempt. The re-applying can however also be useful when you converted the clause at a certain stage, but then later on made a few more modifications in the other editors — e.g., you may have changed the #hashtag of a certain Concept, or assigned a different Concept to a defined term or cross-reference. If you want to apply those modifications to existing conversions, you can either remove the conversion and re-perform the conversion, or perform both actions at once by clicking on the button in the top right corner of the , and choosing the "re-perform conversion" option from the pop-up menu that appears.

If your modifications were limited to loading certain Concepts, then you can instead choose the "reload Concepts" option in the pop-up menu. This will leave the converted text intact, and will only reload the list of Concepts within the

Color codes for converted clauses

To easily see how blocks are converted, ClauseBase uses different color codes for their left border in the editor:

  • blocks that have not yet been converted, have a thick grey left border — see clauses 3. and 3.1 in the screenshot above
  • blocks that will not get converted into a separate file (and will thus end up within the same file as their parent), will have a thin grey left border — see clause 3.1.1 in the screenshot above
  • blocks that are successfully converted, and have been assigned to a specific subfolder, will get a green left border
  • blocks that are successfully converted, but have not been assigned a specific subfolder (so that they will end in their parent clause's subfolder, or in the top-most folder), will get a blue border
  • blocks that have been unsuccessfully converted due to errors, will have a red left border

Dealing with definitions

You can change any converted block from a clause to a definition, by clicking on the button in the top right corner of the , and choosing the "switch between definition & clause" option. You will then have to manually choose the Concept for the definition.

However, it can become tedious to perform this conversion manually for an entire list of definitions. ClauseBase therefore provides special facilities for the bulk conversion of definitions contained in a definitions list of a contract:

  1. Find the clause that is the "parent" clause of all definitions. (Typically, this parent clause is either a just a title such as "Definitions", or some subclause with introductory wording such as "In this clause, the following terms will have the meaning as set forth below.")
  2. Make sure that all the actual definitions are "children" of that parent clause. If necessary, perform some restructuring through the structure subpanel of the editor.
  3. Make sure that each of the definitions will get its own file, by clicking on of the first definition while in the structure subpanel of the document editor. (Subsequently, all definitions will get a purple dotted top border.)
  4. Convert the parent clause (e.g., by double-clicking on the small grey dot at the left of it.)
  5. Click on the button in the top right corner of the clause editor for this parent clause, and choose "definitions list clause".
  6. Convert all the individual definitions (e.g., by double-clicking on the small grey dot at the left of the first definition, while holding Shift.)

During the automatic conversion to a definition, ClauseBase will try to:

  • find the Concept to which the definition refers, by looking for a defined term in bold, between quotes, or with initial capitals;
  • set the filename of the definition file to the name of the Concept; and
  • remove unnecessary initial wording in the clause — e.g., a clause that states "The term "Account" shall mean the combination of username and password" will be truncated to "the combination of username and password". (When this definition is later on used in a ClauseBase definition list, the name of the Concept and the truncated bridge wording may get reinserted, depending on the styling setttings defined by the user of the definition.)

Export the clauses

Once you have successfully converted all the clauses you are interested in, you can export the clauses, i.e. save them to the database, so you can use them later on.

To do so, you have to go to the  editor, and navigate to a folder where you have permission to create new files.

This editor presents just one option, which determines whether (in addition to exporting all clauses individually) you also want to create a document by stacking together all those exported clauses.

When you click on the button, ClauseBase will create a new subfolder in the specified location (containing the name of the original MS Word file). This subfolder will itself contain all the subfolders created through the  editor.

If you specified to also create a document, a document file will be included as well. ClauseBase allows you to navigate to this document, or open it right away in document assembly mode.

Tips, tricks and limitations

  • MS Word documents with sub-documents (e.g., annexes / schedules) should be manually split in MS Word before uploading. You can then upload each subdocument sequentially.
  • Tables and images are not imported by the current version of ClauseBase. If you want to import the text of a table, it is probably easiest to convert the table to text.
  • Manual cross-references (i.e., cross-references that are simply typed in by the user, instead of being generated through MS Word's cross-references functionality) are currently imported as regular text.
  • Translations of documents cannot current be uploaded in one session. Instead, you will have to start with one language, and then copy-paste the translations into the various clause files.