Global placeholders
Rationale
The placeholder system allows you to define placeholders — e.g. {company name} or {address} — and assign values to them. The placeholder can then be used in various places, particularly in the context of Q&As. Its value will be dynamically calculated by the software and shown towards the end-user, so that the end-user would see Acme Inc. instead of {company name}.
The benefit is that you can centrally manage certain bits of information that can vary over time, so that you do not have to start hunting through potentially hundreds of individual files to change Acme Inc. to Gamma Co. when the company name would be changed.
However, Clause9 takes the idea of placeholders to a whole new level, by allowing you to assign values to placeholders on several different levels. For example, if you would automate a non-disclosure agreement for all the entities in your company group, you could use the placeholder system to assign different values to placeholders such as {company name} and {company address}. When an end-user from subsidiary A would then open the agreement, he would automatically see the name and address of his company, while an end-user from subsidiary B would see another name and address. Similar use cases can be envisaged for a law firm that reuses the same documents for different clients.
Configuring placeholders
Placeholders can currently be configured either at the level of a Q&A (through a Placeholder change), or by the administrator in the admin Placeholders admin panel. An administrator can configure placeholders both globally at the level of the entire customer, at the level of individual groups and at the level of an individual user.
Merging levels
A placeholder with the same name — e.g., {address} — can be assigned different values at different levels. However, only one of these values will finally be used, in a cascading order (where a value at an earlier mentioned level will be overruled by a later level):
The global level of the customer.
Each group of whom a particular end-user is a member.
A specific user’s account.
An individual Q&A, through a “Change placeholder” change.
Placeholders defined or changed at the Q&A level cannot be used for the purposes of creating predefined or default answers for questions, or for calculating conditions. (This may change in a future version of the software.)
Data types of placeholders
One of the essential properties of a placeholder, is its data type. While most of the data types are straightforward — true/false, number, date, duration, etc. — a few of them deserve some clarification.
Please note that, except if you control all Q&A and all configurations, you can never be sure what data type a particular placeholder will be. For example, even if placeholder {alpha} would be assigned a currency value at the customer-level, it is possible for some user to assign a duration value to that same placeholder {alpha} in some Q&A.
The various text types
Clause9 offers three data types that can hold text.
Regular Text placeholders can hold a single line of text.
As implied by their name, Multi-line text placeholders can hold multiple lines of text, e.g. an address spanning several lines.
Formatted text placeholders can also hold multiple lines of text, but can additionally be formatted (bold, italic, centered or right aligned, bulleted, etc.). Typically you will want to use this data type for documentation purposes or disclaimers.
The “nothing” placeholder
You can use this placeholder to un-set any value assigned to the placeholder at some higher level.
For example, assume your company policy requests you to impose a system-wide disclaimer on all users (split into 14 different groups), except the 15th group of managers. While you could separately assign the same disclaimer to each of the 14 different groups, it is probably more efficient to assign the disclaimer at a level higher than the group (i.e., at the level of the customer), and then assign the “nothing” placeholder with the same name to the group of managers.
Note that it is perfectly possible to then assign a new placeholder with the same name at some lower level. To continue the example: it would be perfectly possible to assign a disclaimer to a few specific managers, because in the merging cascade the personal level is taken into account after the customer level and the group level. Similarly, a disclaimer assigned to a specific Q&A would also be shown to everybody — including end-users from the group of managers.
Table placeholders
Table placeholders are primarily useful to create default values for table-based answers. They are also used to store settings for certain integrations, such as electronic signatures.
Table placeholders can contain one or more rows, each hosting one or more columns. Those columns need to be predefined before you can actually store any rows.
Configuring the merging process
Ordinary placeholders (e.g., a duration or a text placeholder) get replaced when they occur at multiple levels. Conversely, with table-based placeholders, you also have to option to partially merge the rows, by clicking on the “…” button next to the placeholder’s name:
This may sound complex, but is actually very useful in practice. For example, let’s assume there is a four-eyes principle in your company, so that both the CEO and the relevant division’s general manager need to sign high-value contracts. If you were to electronically sign such contracts (for which the signature data of each signatory must be provided in a table-based global placeholder), you could envision putting the CEO’s signature data at the global level of the Clause9 customer account, and the relevant general manager’s signature data at the Clause9-group level.
If you would leave the placeholder’s merging mode to the default Replace all existing rows, then the CEO’s signature data would get replaced by each general manager’s data, because identically-named placeholders at the group level take precedence over those at the customer-level. However, when you would instead choose Append rows to existing rows, then the rows at subsequent levels get appended to the existing rows. In other words, the general managers’ signature data will get appended to those of the CEO.
Within a Q&A, you could even envisage to have multiple or conditional appends. For example, if for some contracts with an extremely high value two general managers must co-sign with the CEO, but it depends on the product line which general managers are eligible to sign, you could create several Change Sets, attach a relevant condition, and insert a Change placeholder change. If the Append rows to existing rows are then set for each placeholder, you will end up with an exhaustive list of signature data.
As explained above, modifications to global placeholders effectuated by a Change placeholder change, will be ignored when calculating a question’s default answer or predefined answers, or when calculating conditions.
Similarly, there is also the option to replace existing rows. This will remove all rows from a previous level that match a row of a subsequent level. This would, for example, allow you to configure a Q&A so that the CEO’s signature data gets removed in those exceptional situations where the CEO does not necessarily need to sign.
To find out which rows are truly identical, the software looks at the data in the first column of the table. (For example, in a table with rows party-name, party-address and party-city, the party-name would be used. So if the table at a previous level contains entries for Manchester, New York and Amsterdam, while a table at a subsequent level contains entries for New York and Chicago, then only the Chicago would get appended.)
Instead of using the default first column, you can also specify one or more other columns (separated by commas) in the “…” popup. For example, in a table that contains contact details (first-name, last-name, address, city), you could specify “first-name, last-name” as the column names to match, to ensure that the matching happens on the combination of both columns. If you would rely on the default setting, only the first-name would be taken into account, so that if a table on a previous level contains John Smith, while a table on a subsequent level would contain John Peeters, then John Peeters would not get appended because of the matching on the first-name John.
Placeholder lists
For several data types (number, currency, text, date, duration), you can also use a placeholder that can hold multiple values at once. This can be particularly useful for Q&A questions where end-users should be offered different choices (i.e., predefined answers).
A list-place holder {signing manager} could for example be used to allow end-users to choose between several managers whose name should be printed as the signatory of a certain document. Through the merging system, you could even assign different managers to different entities within the same group of companies.
Similar to table-based placeholders, you can specify how lists at subsequent levels should be merged by clicking on the “…” button next to the placeholder’s name:
Instead of the default mode Replace all existing elements — which causes a list at a subsequent level (e.g., a specific Q&A) to replace all the elements of a previous level (e.g., at the customer account level) — you can opt to Append or Remove existing elements.
This can be very useful in many different situations. For example, let’s assume that in a group of companies with subsidiaries in multiple European countries, each subsidiary is allowed to sell both EU-branded books and the local books for its own country. You could then put the EU-branded books in a placeholder list at the global level of the Clause9 customer, and put the local books in a list with the same name at the level of each subsidiary (Clause9 group). When you would configure the list at the group level to Append, each end-user will see both the EU-branded books and the local books of her own country.
System placeholders
The software defines a few special placeholders. A few of them deserve special attention:
Four such placeholders are used to define disclaimers (and captions on the dismiss-buttons) shown when anonymous users login.
The e-signature related placeholders are described in greater detail in a separate help article.
The category of Builtin MS Word properties is described below, in the section on custom DOCX properties.
The category of Send by email placeholders can be used to specify the default values (from name, from email address, to email address, subject, body) for an email that gets directly sent by the software to some recipient, with the current DOCX/PDF in attachment.
The category Export buttons can be used to “promote” certain secondary export options to the top-level, so that they get shown in the toolbar itself. For example — assuming that all conditions are met to electronically sign a document — the Promote e-sign export Button will put the e-sign button within the toolbar of the Q&A, right next to the DOCX/PDF option.
Working with identifiers
Instead of hard-coding values in a placeholder, you can also opt to have values dynamically calculated on the basis of a question’s identifier, by clicking on the “…” next to a placeholder’s name.
For a table-based placeholder, you can choose to either replace the table in its entirety (through the “…” popup-menu next to the placeholder’s name), or to instead dynamically calculate the value of a specific cell of the table:
The identifier-based replacement will only work inside Q&As. For example, if you specify that a certain text-based placeholder needs to take its value from identifier product-name, then the software will search for a question that is associated with that identifier product-name. The first question it finds that has such identifier, will then have its answer inserted into the global placeholder.
Such dynamic identifier-replacements are particularly useful, within table-based placeholders and list-based placeholders, because they allow you to create a combination of hard-coded elements and elements that get their value from another question.
For example, for electronic signatures (for which table-based global placeholders must be used to specify the signature data), you could opt to hard-code the CEO’s signature data at the customer account level (because the CEO’s signature must always be included), and combine that base signature data with the names of two managers at the department level (group level) that were adhoc selected by the end-user. Obviously, you cannot hard-code the signature data of those managers, because you do not know upfront which of the managers will actually get selected by the end-user. Instead, you can refer to the relevant questions through an identifier.
Make sure that a question’s answer is “compatible” with the data-type of the placeholder. For example, if you specify that a text-based placeholder needs to fetch its value from a question with identifier “alpha”, but the number-based question is associated with that identifier, then the placeholder will not get its value filled.
Labels
Except for the table and nothing data types, every placeholder can be assigned a label in addition to a value. When available, the label will be shown on the screen instead of the value; the value will instead be used in calculations, conditions and clause text.
For example, instead of using the full text of a country, it is probably a better idea to use a two-letter abbreviation for the value (“de”, “mk”) and a separate label with the full text (“Germany”, “The Former Yugoslav Republic of Macedonia”). This not only helps to avoid errors due to typos, but also allows to reuse the same condition across different languages — otherwise each condition would have to somehow check on the country’s translation.
This is similar to how labels and values function in a concept’s datafields.
Differences with spreadbases
Both spreadbases and (particularly list-based) placeholders can be used to define predefined values from which an end-user can choose. While spreadbases and placeholders partially overlap, they are nevertheless quite different.
In general, you should use spreadbases when the number of different values is relatively high — e.g., to allow a user to select any of the 200 signatories in the company.
Spreadbases can be used to fill in multiple datafields at the same time (when selected by the end-user from a dropdown list), while placeholders are limited to a single value.
Use placeholders when you desire the following functionality:
Unlike placeholders, spreadbases cannot be used to define the default value of a question.
Unlike placeholders, spreadbases cannot contain table values.
Differences with predefined values
The placeholder system also overlaps with the regular predefined answers that you can define for most types of questions.
Administrators can define, on the level of a customer, group and/or user, whether or not a certain placeholder should apply; no other type of “condition” can be imposed on a placeholder. Conversely, predefined answers can be subjected to any Q&A conditions you can think of.
Predefined answers cannot be used inside Q&A conditions, while the (value of) placeholders can be used inside a Q&A condition — e.g., to determine whether or not a certain change-set should apply.
Placeholders can refer to the answers of another question.
Predefined answers are “static”, in the sense that they will be the same for all users of a Q&A (although you can remove some predefined answers for some users, through a condition). Conversely, placeholders can be modulated on a per customer/group/user basis.
Predefined answers must be changed by the Q&A author (by opening the Q&A); the placeholder system allows for central management by the administrator, without having to open any Q&A.
Predefined answers cannot be directly shared between different Q&As (indirectly you can, by importing a card as a proxy into another Q&A). Conversely, placeholders are intended to be used across different Q&As.
Using placeholders instead of predefined answers
Benefits
Clause9's standard system of predefined answers allows you to specify one or more predefined options, that can optionally be subjected to conditions. This works well for most Q&As, but can become difficult to manage when the list of predefined answers should be dynamically determined on the basis of the type of end-user.
For example, assume you are responsible for creating a standard employment agreement for a group of companies with 20 different entities; each of those entities has employees that can be part of different labour unions and/or subject to different collective bargaining agreements. You are now faced with the task of allowing the end-user of the employment agreement to select the relevant bargaining agreement.
Theoretically you could create a question with 50 or 60 predefined answers, and subject each of those predefined answers to relevant conditions. However, this would be very cumbersome to do.
With the placeholders system, you would instead assign the same placeholder to different groups and/or users in Clause9, and insert a reference within the right question.
Usage
In order to use placeholders as predefined answers, you have to click on the + Placeholders icon of a question.
You will then get two extra boxes in which you can enter information:
In the input box for the Values, you can insert one or more placeholders or question-identifiers.
Placeholders should always be wrapped inside curly braces — e.g.
{address}. They refer to the centrally managed placeholders, available in the Placeholders section of the administrator panel. If a match is found between a curly-braces-wrapped-placeholder you enter here, and some placeholder that applies to a certain end-user, then the value (or, in the case of a list-based placeholder, multiple values) of that placeholder will be used as predefined answers.Question-identifiers allow you to refer to the answers of another question, on the basis of their identifier (as entered in the question’s integration options). Question-identifiers should not be wrapped inside curly braces. If a match is found between a question-identifier and a certain question, then that question’s answer(s) will be made available as predefined answers.
The software will then compile a list of all placeholders and all question-answers it can find, and dynamically present that list towards the user.
For example, assume you have defined:
A text list placeholder named entities–eu, and assigned the values “Alpha France”, “Beta Germany” and “Gamma Spain” to it in the Placeholders section of the administration module.
Another text list placeholder named entities–us, and assigned the values “Delta Florida” and “Epsilon NY” to it.
A question named “Relevant affiliates” (allowing for multiple text values), and assigned it the identifier “affiliates”.
Now insert another question with placeholders {entities-eu} and {entities-us}, as well as question-identifier affiliates:
When you first open/simulate this Q&A, the following will be shown:
However, notice what happens to the answers list of the second question when you add one or more affiliates to the first question: (Clause9 shows more than 5 items in a dropdown list)
If the administrator would change the values assigned to the placeholders, then the Q&A will be automatically updated. Even more interesting is when the user would assign different values for different types of users or groups — as could for example be the case for a law firm that would use the same type of legal agreement for different clients, with entirely different company entities.
For questions where you want to offer multiple choices to your end-user, you may be tempted to create a few ordinary predefines and also insert a {placeholder} value for some other predefines of the same question. Don’t do this — the placeholder will get filled in at the left side of the screen, but will not get filled in in the contract text at the right side of the screen.
The technical reason is that when no separate label exists for a predefine’s value, the software will also use the text of the value as the label. So the very same text of the value will be filled in when it is wearing its hat of label, but will not get filled in when it is wearing its hat of value.
Bottom line: if a question with multiple choices should be offered to the end-user, then you should be using either a list of different predefines, or a lists of placeholders — but not a mix of the two, like you are currently doing.
Using placeholders as default values
The placeholder system allows you to define the default value that should be selected. This allows you to, for example, automatically choose the address of a French entity when a French user opens a Q&A, while instead the German entity would be chosen when a German user would open the same Q&A.
In order to use placeholders as default answers, you have to click on the + Placeholders icon of a question.
Next, you should enter one or more placeholders (wrapped in curly braces) into the Default value input box.
The software will run sequentially through each of the {placeholders} you inserted into the box, and use the following rules to determine which item becomes the default value:
For a list-based placeholder, it will choose the item that is marked as the default value. For example, in the text list-based placeholder below, “Beta Germany” would be selected as the default value if
{entities-eu}would be inserted into the Default value box.
Any singular placeholder (e.g., a single text or a single date, but also a table) will be selected as soon as it is encountered.
For example, if you would insert both {special-entity} and {entities-eu} (with the items in the screenshot above, i.e. Beta Germany as the default), then:
If some value would be assigned to
{special-entity}, then that value will always become the default value, taking precedence over Beta Germany, because{special-entity}is listed earlier.If no value would be assigned to
{special-entity}, then Beta Germany will get selected as the default value.
Be aware that — unlike many other features in Clause9 — the placeholder-based default values are static (“sticky”) instead of dynamic, in the sense that, once assigned to a Q&A answer, they will not automatically update afterwards.
If, for example, you set placeholder A to take value X for users of a certain group, and afterwards you change the value of placeholder A to Y (or reassign the user to a different group), then any saved Q&A answers previously saved will remain the same. Similarly, if a completely different user would open that same answer set, the default values will not be updated, even when that other user would trigger completely different default values if he would have created a new Q&A.
Do not use placeholders defined or changed through a Change placeholder change as a default answer (or predefined answer, or for calculating a condition). The software will disregard any modifications made by the Change placeholder for such scenarios.
Using placeholders for titles and labels
You can insert a placeholder wrapped in curly braces — e.g. {address} — in a card’s title, a question’s title, help text, as well as the labels of each predefine. The software will then replace those curly braces with the values assigned to them:
In the placeholders defined by the administrator.
In the placeholders assigned by a “Change placeholder” change in the Q&A (assuming it did not get disabled through some condition). Any value assigned to a placeholder at this level of the Q&A, will automatically take precedence over any value assigned at a customer/group/user level by the administrator.
If no replacement value is found, then the curly braces will simply be dropped — e.g. {address} will then be shown as simply address.
For example, let’s assume that a legal counsel is responsible for drafting engagement letters for four different entities in his group: Alpha Inc., Beta Co., Gamma SA and Delta BV. By creating a placeholder with the name {entity-name} and assigning to that placeholder the name of the relevant entity (e.g., assigning “Alpha” to anonymous user “Anonymous Alpha User”; “Beta” to anonymous user “Anonymous Beta User”, etc.), you can automatically show the relevant entity’s name inside the Q&A.
For example, a card with the following question:
Would then be shown as follows for someone logged in with an anonymous link associated with Anonymous Beta User:
Note that you could even translate those labels, if multiple languages happen to apply.
Now let’s assume that occasionally the engagement letter should also be usable for an entity name that can be freely chosen by the end-user:
When you then creat an associated change:
… the value assigned to placeholder {entity-name} will be automatically changed if the deviating entity is filled in:
You can assign any relevant question’s answer as the value assigned to a placeholder. For example, if the user answers “16th January 2020” as the commencement date question, and you have created a change-placeholder {commencement-date} referring to that question, then you can use {commencement-date} anywhere in the Q&A — it will be automatically replaced by 16th January 2020.
Using placeholders inside Q&A conditions
You can use all placeholders (except tables) inside conditions, allowing for interesting use cases.
For example, assume you are responsible for creating a standard distribution agreement for a list of entities of a global group of companies. Unfortunately, according to the group’s rule book, the standard exclusivity term is 5 years, but every entity is free to deviate with a different term.
With the placeholder system, you could manage this as follows:
Create a duration-based placeholder
{exclusivity-duration}, and assign a standard term of 5 years at the customer level. This value will act as the fallback for all entities.Create a true/false placeholder
{own-exclusivity?}, and assign a fallback valuefalseto it at the level of the customer.Create a question in which you allow the end-user to deviate from the standard 5 years, assuming this is allowed by his/her entity.
Now the only task left to do, is to assign different values to the placeholders at the level of the groups or users.
Note that the condition requires you to specify the datatype of the placeholder. This is necessary because placeholders can have any datatype. If there is a mismatch between the applicable placeholder’s datatype and the datatype specified in the condition, then the condition will automatically fail.
Do not use placeholders defined or changed through a Change placeholder change inside conditions. The software will disregard any modifications made by the Change placeholder when calculating the conditions.
Using placeholders to set MS Word document properties
Through a set of special system-defined placeholders, you can define the “document properties” of an MS Word file:
You can either set one of the MS Word built-in properties shown in the following screenshot of MS Word…
… or define a custom property (of type true/false, number or text) that will then be shown in the Custom property part of the MS Word sheet:
The following built-in properties are available (submenu System-defined / Builtin MS Word properties): author, category, comments, company, contentstatus, manager, subject and title. All are of type text.
To define a custom property, choose one of the values in the System-defined / Custom MS Word properties: docprops-yesno-xxx, docprops-number-xxx or docprops-text-xxx. You will then get a new placeholder of the appropriate type (true / false, number or text), and you should replace the “xxx” with the name of your choice. The value that gets filled in through the placeholders system, will then automatically show up in the custom file properties of MS Word.
Using placeholders for electronic signing
See our separate article about e-signing.
Using placeholders for setting default values
Some default values can be easily set using the global placeholders system. For example, if you always want to show the Send by email button in a Q&A’s toolbar, you can do so through the System-defined placeholders > Export buttons > Promote email export button. (Similarly, you can set the default from/to/subject/body using global placeholders in the System-defined > Send by email category).
Last updated
