Valcu
Valcu logo inverted no drop shadow
Loading...
Loading indicator
Beta

  Valcu Document Scripting Overview

DIY Document Automation - Last Updated October 10, 2016   



Hello! Here's a quick overview on automating your documents. The easiest way to get going is just to try the sample document.

Feel free to make some changes to see how it works.


Basic Pattern

When you want to add an automated field into a document, just name it whatever you like using only letters or numbers (but don't have a number as the first part after "v_field_"), replace all spaces with underscores ("_") and then add v_field_ to the beginning of the name.

Example. Change this:

This Consulting Agreement betweeen [Company Name] and [Consultant Name] is entered into ...

To this:

This Consulting Agreement betweeen v_field_company_name and v_field_consultant_name is entered into ...

Optional Language

When you want to add language that you can turn on or off, simply name it using the basic pattern, and then end it with _applicability. At the end of the language you want to make optional, type v_field_end.

Example. Change this:

The parties will submit to binding arbitration.

To this:

v_field_arbitration_applicability The parties will submit to binding arbitration. v_field_end

Default Alternative Language

Or to make the language optional with a default alternative, separate the alternatives with v_field_else.

Example:

v_field_arbitration_applicability The parties will submit to binding arbitration. v_field_else The parties agree that the exclusive jurisdiction for all disputes shall be the federal courts located in the Southern District of New York. v_field_end

Series of Alternatives

Or to make a series of language sections, only one of which can be used, separate the alternatives (starting with the second) with _else_applicability.

Example:

v_field_arbitration_applicability The parties will submit to binding arbitration. v_field_mediation_else_applicability The parties agree to mediate before litigating. v_field_else The parties agree that the exclusive jurisdiction for all disputes shall be the federal courts located in the Southern District of New York. v_field_end

All in Own Paragraphs, or All Within One Paragraph

Note: when using optional tags, all of the tags in the group must each be in their own paragraphs, or all of the tags in the group must be part of one paragraph.

Example of incorrect pattern (as v_field_arbitration_applicability is in its own paragraph, while v_field_else and v_field_end are part of a separate paragraph):

v_field_arbitration_applicability
The parties will submit to binding arbitration. v_field_else The parties agree that the exclusive jurisdiction for all disputes shall be the federal courts located in the Southern District of New York. v_field_end

Example of correct pattern (as each of v_field_arbitration_applicability, v_field_else and v_field_end is in its own paragraph):

v_field_arbitration_applicability
The parties will submit to binding arbitration.
v_field_else
The parties agree that the exclusive jurisdiction for all disputes shall be the federal courts located in the Southern District of New York.
v_field_end

Repeated Items

When you want to repeat items for a list, simply name it using the basic pattern, and then end it with _hashes_each. At the end of the language you want to make optional, type v_field_end. Between the starting and ending fields, items in the list should have the same field name, but changing _hashes_each to _hashed and whatever you would like to name the item.

Example. Change this:

The Purchasers of Series Seed Preferred Stock and respective amounts are as follows:
[Name] [Shares]
[Name] [Shares]

To this:

The Purchasers of Series Seed Preferred Stock and respective number of shares are as follows:
v_field_purchaser_hashes_each
v_field_purchaser_hashed_name v_field_purchaser_hashed_shares
v_field_end

List with Commas, Semi-Colons, "And", and "Or"

To create a readable list with commas, semi-colons and an and or an or, create a repeated list as above and insert v_field_comma_conjunctive, v_field_semicolon_conjunctive, v_field_comma_disjunctive, v_field_serial_comma_ambigjunctive or similarly patterned field before the v_field_end tag.

Example. Change this:

The Company has authorized [XXX] shares of Common Stock, [XXX] shares of Series Seed Preferred Stock and [XXX] shares of Series [X] Preferred Stock.

To this:

The Company has authorized v_field_authorized_share_hashes_each v_field_authorized_share_hashed_shares shares of v_field_authorized_share_hashed_security_name v_field_comma_conjunctive v_field_end.

List Numbering

To add numbering to list items, create a repeated list as above and insert v_field_ordinal_index, v_field_ordinal_roman, v_field_ordinal_romanette or v_field_ordinal_alpha somewhere before the v_field_end tag.

Example. Change this:

This Agreement shall not be amended or waived without the written consent of (i) holders of a majority of the outstanding shares of [Common Stock], [(ii) holders of a majority of the outstanding shares of [Series Seed Preferred Stock]] and (iii) holders of a majority of the outstanding shares of [Series A Preferred Stock].

To this:

This Agreement shall not be amended or waived without the written consent of v_field_agreement_amendment_hashes_each (v_field_ordinal_romanette) holders of a majority of the outstanding shares of v_field_agreement_amendment_hashed_security_name v_field_comma_conjunctive v_field_end.

When you want to repeat table rows for a list, use a start tag (e.g., v_field_purchaser_hashes_each) at the beginning of the first cell in the row, and end the repeated section in a row following with v_field_table_row_end.

Example. Change this:

Name Shares
[Name] [Shares]
[Name] [Shares]

To this:

Name Shares
v_field_purchaser_hashes_each v_field_purchaser_hashed_name v_field_purchaser_hashed_shares
v_field_table_row_end

Determine If List Has More Than One Item

To create optional logic that depends on whether a _hashes list has more than one item, use v_field_my_special_field_hashes_plurality_applicability and end the logic with a v_field_end tag.

Example. Change this:

This Agreement shall not be amended or waived without the written consent of (i) holders of a majority of the outstanding shares of [Common Stock], [(ii) holders of a majority of the outstanding shares of [Series Seed Preferred Stock]] and (iii) holders of a majority of the outstanding shares of [Series A Preferred Stock].

To this:

This Agreement shall not be amended or waived without the written consent of v_field_agreement_amendment_hashes_each v_field_agreement_amendment_hashes_plurality_applicability (v_field_ordinal_romanette) v_field_end holders of a majority of the outstanding shares of v_field_agreement_amendment_hashed_security_name v_field_comma_conjunctive v_field_end.

Get Sum of Item in List

To create a field that is the sum of an item within the list, use _hashes_summed followed by the name of the item.

Example. Change this:

Total: [Total Number of Shares].

To this:

Total: v_field_authorized_share_hashes_summed_shares.

All in Own Paragraphs, or All Within One Paragraph

Note: similar to Optional Tags, when using repeated tags, the start tags (e.g., v_field_purchaser_hashes_each) and the end tags (v_field_end) in the group must each be in their own paragraphs, or all of the tags in the group must be part of one paragraph. One exception, however, is if a table row is started with a repeated start tag (see above).

Magic Words

Certain words used in a field name will create some special behavior.

Ending a field with "_date" (e.g., v_field_agreement_date) will be interpreted as a date and the corresponding input generated to complete the field will be a datepicker.

Ending a field with "_upcase" (e.g., v_field_company_name_upcase) will be interpreted as the field without the ending (v_field_company_name), but will cause the value of the field to be ALL CAPS.

Ending a field with "_words" (e.g., v_field_shares_words) will be interpreted as a number field without the ending (v_field_shares), but will cause the value of the field to be converted to words.

Ending a field with "_titleized" (e.g., v_field_shares_words_titleized) will be interpreted as the field without the ending (v_field_shares), but will cause each word in the field value to be capitalized.

Ending a field with "_ambipluralize" (e.g., v_field_period_type_ambipluralize) will be interpreted as the field without the ending (v_field_period_type), but will cause the value of the field to end with (s) or (es).

Ending a field with "_no_period" (e.g., v_field_company_name_no_period) will be interpreted as the field without the ending (v_field_company_name), but will be interpreted to remove any period from the end of the value.

Ending a field with "_verbosedate" (e.g., v_field_agreement_date_verbosedate) will be interpreted as a date and the value will formatted like 15th day of September, 2015 and the corresponding input generated to complete the field will be a datepicker.

Ending a field with "_percent_threshold" or "_perc_threshold" (e.g., v_field_waiver_perc_threshold) will be interpreted as a voting threshold, the corresponding input generated to complete the field will ask for a percentage and the value will be formatted as follows: 50% as a majority, 66.66% or 66.67% as two-thirds and 60% (or the like) as at least 60%.

Ending a field with "_threshold_perc", "_percent" or "_perc" (e.g., v_field_minimum_shares_threshold_perc) will be interpreted as a percentage, the corresponding input generated to complete the field will ask for a percentage and the value will be formatted as follows: 50% as 50%, etc.

Ending a field with "_salary", "_fee_cap", "_valuation_cap", "_flat_fee", "_proceeds_threshold", "_proceeds", "_dollar", "_bonus", "_cash" or "_cash_amount" (e.g., v_field_employee_salary) will be interpreted as a dollar amount, the corresponding input generated to complete the field will ask for a dollar integer and the value will be formatted as follows: 1 as $1, etc.

Ending a field with "_wage", "_fee", "_fmv", "_per_share", "_per_sh", "_p_sh", "_check_consideration", "_precise_dollar",, "_dollar_precise", "_precise_cash", "_cash_precise", "_precise_bonus" or "_bonus_precise" (e.g., v_field_common_stock_par_value_per_share) will be interpreted as a dollar amount, the corresponding input generated to complete the field will ask for a dollar decimal and the value will be formatted as follows: 1.00001 as $1.00001, etc.

Ending a field with "precise_number", "_vesting_total_years", "_vesting_years" or "_multiple" (e.g., v_field_vesting_years) will be interpreted as a decimal, the corresponding input generated to complete the field will ask for a decimal and the value will be formatted as follows: 1.00001 as 1.00001, etc.

Ending a field with "number", "_num_seats", "_number_seats", "_total_directors", "_min_options", "_max_options", "_maximum_installments", "_cap", "_months", "_shares", "_meetings" or the like (e.g., v_field_severance_num_installments) will be interpreted as an integer, the corresponding input generated to complete the field will ask for a positive integer and the value will be formatted as follows: 1 as 1, etc.

Ending a field with "_org_state" (e.g., v_field_org_state) will be interpreted as a state drop-down.

Ending a field with "_governing_law_state", "_headquarters_state", "_governing_law_state_fallback", "_arbitration_place" or "_submission_federal_district" (e.g., v_field_governing_law_state) will be interpreted as a state auto-complete.

Ending a field with "_org_type", "_organization_type", "_organizational_type", "_entity_type" (e.g., v_field_org_type) will be interpreted as a legal entity-type auto-complete.

Other magic words explained earlier are:

  • ending a field with _applicability or _else_applicability
  • v_field_else
  • v_field_end
  • _hashes_each
  • _hashes_summed
  • _hashed_
  • v_field_comma_conjunctive, v_field_semicolon_conjunctive, v_field_comma_disjunctive and v_field_serial_comma_ambigjunctive
  • v_field_ordinal_index, v_field_ordinal_roman, v_field_ordinal_romanette and v_field_ordinal_alpha

Other reserved words:

  • ending a field with _conjunctive_list, disjunctive_list or ambigjunctive_list
  • ending a field with _list

Form Copy

You may want to automate the generation of a form copy of the document in addition to the automation of an executable version. Use v_field_form_copy in same way as _applicability to indicate language to be used if a form is being generated.

Example. Change this in an employee offer letter:

We are delighted to offer you a position with [Company]. Your title will be [Employee Title], and you will report to the Company's [Supervisor Title].

To this:

We are delighted to offer you a position with v_field_company_name_no_period. Your title will be v_field_form_copy [Employee Title], and you will report to the Company's [Supervisor Title] v_field_else v_field_employee_title, and you will report to the Company's v_field_supervisor_title v_field_end.

Annotations and Annotated Copy

You may want to include comments in the document that would need to be removed when a document is generated. Use v_field_annotated_copy in same way as _applicability to indicate language to be used if an annotated copy is being generated and would otherwise be removed from generated documents.

To include a comment for a specific field in the document, which will be included as part of the input seen when later filling out a template, but is otherwise removed from the document when an execution version is being generated, use v_field_my_special_field_annotation in same way as _applicability or v_field_annotated_copy.

Text after v_field_annotated_copy and _annotation ending with the first v_field_end is included as part of the comment. Accordingly, the comment should not contain any other fields.

Example. Change this in an employee offer letter:

We are delighted to offer you a position with [Company]. Your title will be [Employee Title], and you will report to the Company's [Supervisor Title]. [COMMENT: It is common to report to the Chief Executive Officer or other member of management. In the case of the CEO, you can use the Board of Directors.]

To this:

We are delighted to offer you a position with v_field_company_name_no_period. Your title will be v_field_form_copy [Employee Title], and you will report to the Company's [Supervisor Title] v_field_else v_field_employee_title, and you will report to the Company's v_field_supervisor_title v_field_annotated_copy [COMMENT: It is common to report to the Chief Executive Officer or other member of management. In the case of the CEO, you can use the Board of Directors.] v_field_end v_field_end.

Or to this:

We are delighted to offer you a position with v_field_company_name_no_period. Your title will be v_field_form_copy [Employee Title], and you will report to the Company's [Supervisor Title] v_field_else v_field_employee_title, and you will report to the Company's v_field_supervisor_title v_field_supervisor_title_annotation [COMMENT: It is common to report to the Chief Executive Officer or other member of management. In the case of the CEO, you can use the Board of Directors.] v_field_end v_field_end.

Or to this:

We are delighted to offer you a position with v_field_company_name_no_period. Your title will be v_field_form_copy [Employee Title], and you will report to the Company's [Supervisor Title] v_field_else v_field_employee_title, and you will report to the Company's v_field_supervisor_title v_field_end.
v_field_supervisor_title_annotation
[COMMENT: It is common to report to the Chief Executive Officer or other member of management. In the case of the CEO, you can use the Board of Directors.]
v_field_end

Tagging and Captures

You may want to tag and extract data out of a document when it is generated. Simply name it using the basic pattern but v_capture_ instead of v_field_. At the end of the language you want to tag or capture, type v_capture_end. Captures can also be deeply nested, but each must end with v_capture_end.

Example. Change this in an employee offer letter:

We are delighted to offer you a position with [Company]. Your title will be [Employee Title], and you will report to the Company's Chief Executive Officer.

To this:

We are delighted to offer you a position with [Company]. Your title will be [Employee Title], and you will report to the Company's v_capture_supervisor_title Chief Executive Officer v_capture_end.

Cross Platform Compatability

Some of the features used in Word don't have good alternatives in other platforms or with some conversion tools. To increase the consistency of formatting among platforms, here are a few tips:

  • Change non-breaking spaces to regular spaces. Search ^s in Word to find all non-breaking spaces.
  • Change non-breaking hyphens to regular hyphens. Search ^~ in Word to find all non-breaking hyphens.
  • Change soft returns (returns created by typing Shift+Enter) to hard returns. Search ^l in Word to find all soft returns.
  • Use hard-coded paragraph and section numbering rather than auto-numbering. This is not essential, but auto-numbering tends to result in errors in documents for paragraph/section cross-referencing. For the technically inclined, auto-numbering can be converted to hard-coded numbers all at once in Word by opening the Immediate Window (Alt+F11 and then Control+G on Micrsoft Word 2010; on Microsoft Word 2011 Tools>Macros>Visual Basic Editor) and typing ActiveDocument.Range.ListFormat.ConvertNumbersToText and hitting enter. If you use auto-numbering in paragraphs, be sure that references to section numbers use the same logic to result in the correct section or paragraph number.
  • Paragraphs beginning with a heading with a hidden section break separating the heading and the text following should be flattened. That is the heading should be in it's own paragraph styled as such, or the heading should be the same style as the rest of the paragraph, and the hidden section break should be removed.
  • Highlight all text and then check "Don't Hyphenate" under paragraph settings.

Other Tips

Some other tips to follow:

  • Accept all changes in document, remove comments, and turn off track changes.
  • Ignore (or fix) all spelling and grammer changes resulting from the use of v_field_ tags.
  • Don't use spaces for styling as the parser removes extra spaces. Search ^$ ^$ (with two spaces in the middle, or alternatively three spaces) in Word to find extra spaces between words.
  • Remove hyperlinks from website/email links.
  • Delete all spaces at the ends of paragraphs and any extra (i.e., more than two) spaces between sentences to minimize (less substantive) redline changes. The parser will remove these spaces anyways, but the change will show up in the redline. Search ^p in Word to find spaces at the ends of paragraphs.
  • Remove optional hyphens. Search ^- in Word to find optional hyphens.
  • Make sure all scripted fields are separated from other words by a space and not a tab.
  • Remove Word merge fields from document.
  • If sections of the document disappear or show as tiny vertical lines in the PDF once the document is uploaded, edit the original document in your Word editor. Select the offending sections (or all of the text in the document), go to the font settings, click on advanced, and then set the Scale option to 100%.
  • Not all fonts are available when documents are converted to PDF. Consider an alternative if the font does not appear correctly. "Times New Roman" is generally okay, while "Times New Roman Bold" is not.

Signature Scripting

To add a signer and signature to a document, use v_sig_person_label followed by a v_field_end tag.

To add a list of signers and signatures all playing the same role to a document, use the plural v_sigs_person_labels, with the individual signature block in between (v_sig_person_label and v_field_end), and then ended with a v_sigs_end tag.

One or more of the following magic words can be appended to the v_sig_ tag: _chained (allows the signer to include a chain of authority in the signature block), _named (appends the signer's name after the signature), _titled (appends the signer's name and title, if available, after signature block, _addressed (appends the signer's notice address after the signature block( and _dated (includes a date stamp of the date the document was actually signed with the signature).

Each signature tag is block-level and should be in its own paragraph.

v_field_else can be used after a v_sig_ tag to include an alterative signature block used in a non-electronically signed version of the document.

Examples:

v_field_consultant_name_upcase

v_sig_consultant
v_field_end
v_field_consultant_name_upcase

v_sig_consultant
v_field_else
By:___________________________
Name:
Title:
v_field_end
v_field_consultant_name_upcase

v_sig_consultant_chained_titled_dated_addressed
v_field_else
By:___________________________ Date:___________________________
Name:
Title:

Address: ___________________________
____________________________________
v_field_end
v_sigs_consultants

v_sigs_consultants_hashed_name_upcase

v_sig_consultant_chained_titled_dated_addressed
v_field_else
By:___________________________ Date:___________________________
Name:
Title:

Address: ___________________________
____________________________________
v_field_end
v_sigs_end

To be further documented.

Transaction API

When building a document template, the document template can be set to automatically fill out fields in the document with data available in a data room or from the transaction. This is done in the document templating wizard tool by dragging an api handle to a particular field, with matching data type and color.

To be further documented.