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, ClauseBase 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. (However, placeholders defined or changed at the Q&A level can only be used in question/card/predefine titles and labels, as well as disclaimers; the software will ignore such placeholders for the purposes of creating predefined or default values).

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

ClauseBase 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.

Note that in multi-lingual ClauseBase environments, for each of these text data types, the value can be optionally translated by hitting the button and assigning separate values to separate languages.

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 currently only useful to create default values for table-based answers.

The structure of the table in the placeholder (i.e., the datatype of each column, as well as the ordering of the columns) must be identical to the question for which it will become the default answer, otherwise the table placeholder will be ignored.

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.

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.

System placeholders

The software defines a few special placeholders. Four such placeholders are used to define disclaimers (and captions on the dismiss-buttons) shown when anonymous users login.

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

ClauseBase’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 ClauseBase, 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 entitieseu, 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 entitiesus, 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:

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 ClauseBase — 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 value. The software will disregard any modifications made by the Change placeholder when calculating the default values; the Change placeholder is merely intended for changing labels.

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 value false to 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; the Change placeholder is merely intended for changing labels.

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 followin 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.

Was this article helpful?
Dislike
Usage page
Custom homepage