Creating User Defined Fields

User Defined Fields are a powerful tool that allows you to customize documents in unique ways. There are two main uses for these fields: to input a custom field into a document or to determine what appears conditionally in a document.

You can find User Defined Fields under the Governance section of the settings menu.

On this screen: The User Defined Fields index page under Settings. A table lists all configured fields with columns for Label, Name, Type, Context, and Required. A delete button appears on each row. An + Add User Defined Field link appears in the table footer to create a new field. Rows can be reordered by dragging the handle icon on the left.

The simplest use case is a User Defined Field to add a field into a project. The field can be a text field, a number field, or a date field. Once on the User Defined Fields configuration page, you would create a new Field by giving it a description, a field name, and a type. You can also specify if you want that field required for all projects and if it should have a minimum or maximum length.

On this screen: The new User Defined Field form. The top row has a Description field (the display label, e.g., “Custom Project Code”) and a Where will it be used? dropdown (context: Project, Service, etc.). The second row has a Field Name field (the internal identifier used in merge tags, e.g., custom_project_code), a Type dropdown (Text, Number, Date), and a Required checkbox. Below those, Minimum Value/Length and Maximum Value/Length number fields allow optional constraints. A Submit button and a Back link appear at the bottom.

In the above example, you would be allowing the user to type in a value for Custom Project Code. After you click submit, you can go to a project and see the field in the Project Overview screen.

Use can use merge data to insert add this value into your document template.

Conditionally Showing Sections of a Document

Instead of inputting data, you wanted users to select a flavor from a list of options. Depending on which option is selected, you can insert different things into your document.

First, you would create your list of options.

On this screen: The User Defined Field form configured for a select-options field. The form shows the same Description, Field Name, Type, Required, and length constraint fields as above. Below those, a Select Options section lists the predefined choices, each with a key (display label) and a value (stored value). An + Add Select Option link adds another row. This is how you define the list of options users will see in the single-select dropdown on the project.

Note that the type of field doesn’t matter as it will display the predefined list in a single-select fashion. Now in the Project Overview, you will see your listed options.

On this screen: The Project Overview page showing the User Defined Fields section. The select-type field appears as a labeled dropdown showing the predefined options. Text fields appear as text inputs, number fields as number inputs, and date fields as date pickers. Required fields are marked with an asterisk (*).

After you submit, you can now generate a document that can show different things depending on how you have laid out your document.

Here is an example of merge fields in a Word document that would export based on this Field. Note: The following describes creating mail merge fields in a v1 merge data-based template.

You can see it laid out here in the Word document, along with the output.

On this screen: A Word document open in Microsoft Word showing v1 mail merge field syntax for a conditional User Defined Field. The document contains an IF merge field that tests the value of the User Defined Field (e.g., «IF flavor = "chocolate"») followed by the content to include when the condition is true and «ENDIF» to close the block. Beside it (or below) is the rendered output document showing the selected flavor’s content inserted in place of the conditional block.

You can put any text between the if-endIf pair of the selected Field, including tables, other User Defined Fields, payment terms, and even other nested if-endIf User Defined Field sets.

You can use User Defined Fields to drive lots of flexibility into your documents!

Default values are display-only until saved

When you configure a select-options User Defined Field, each option can carry a default value. It is easy to assume that default is stored on every project automatically. It is not — the default is a display convenience, not stored data, until a project is opened and saved.

How the default actually behaves

The default value lives on the field’s option list, in the field’s configuration — not on any individual project. When you open a project’s Overview screen and the project has no stored value for that field, ScopeStack substitutes the default into the field so you see something sensible instead of a blank. But at that point the default is only being shown; nothing has been written to the project.

The value is not persisted to the project until the project is opened and Saved. Opening the Overview screen and saving it commits the displayed default (or whatever value is shown) as the project’s stored value. Until that save happens, the project genuinely has no value for the field — the default you see on screen is cosmetic.

Why an API-created project can generate a document with the field blank

This is the practical consequence that trips people up. A project created through the ScopeStack API never goes through the “open the Overview screen and save” step, so the display-only substitution never runs and no value is ever persisted. The project is created with a truly empty value for the field.

When you then generate a document for that project, the merge data has nothing to insert, so the field comes out blank — even though the field is configured with a default value, and even though the Overview screen would show that default if someone opened it.

What to do

If you need the default value to appear in a generated document for an API-created project (or any project that has never been opened and saved), open the project’s Overview screen and save it before generating. That save writes the default into the project’s stored data, and the field will then populate in the document.

If you need the value present without a manual save — for example, in a fully automated pipeline — set the field’s value explicitly when you create the project through the API, rather than relying on the configured default to fill it in.