Click on Images to Expand Them

The contents of the Docupace Start wizard pages is created by placing fields of different types on each page. Term “field” in this case refers to any type of element placed on a page. To the end-user it may look like a text field, a check box, a drop-down list, a button, an image, a section, a group of fields, or any of a number of elements. Currently Docupace Start supports 20 types of fields, as described in Field Types reference section.

Each field has settings that control its contents, its functionality and its visualization. Some of these settings are common to almost all field types. These are addressed in this description and also in the Field Settings (common) reference section. For settings specific to each Field Type, see respective chapters of this guide.

In some instances (for fields labels and for rich-text fields) you can edit text directly in the Designer panel. When using this method, any text pasted will retain its original formatting.

To place a new field on a page proceed as follows:

Step 1: Add a Single Text Field.

1.1. Click on the page in the page tree pane on the left side of the Docupace Start screen. It is opened for editing in the Designer panel.

^{New empty page of the wizard}

1.2. Open Add Field panel.

1.3. Click the Single Text button to add it as the first field for this page.

^{Adding a Single Text field}

1.4. Select the Single Text field and open Field Settings.

1.5. Enter the following values for this field:

Field Settings for a Single Text field

Field Values

Field	Value
Field Label	Owner Last Name This is the name of the field that is visible to the user and is displayed above or next to the field, or on top of an Action button.
Use label as placeholder	Deselected
Placeholder	Type the owner's last name. Text that will be visible to the user inside the field as a tip.
Meta Field Name	`Owner1.LastName` This is the unique name for the data held within the field as it is referenced by code and in the database. It will be mapped to a specific field in a PDF form. Notation for Meta Field Names is described in How to Choose a Meta Field Name. Warning! This is a mandatory setting. If left empty for any of the fields, the wizard will not function properly. Warning! Meta Field Name must start with a letter. It may contain letters, numbers and underscores ("_"). Other characters are not permitted and will prevent the wizard from functioning properly.
On value change	JS code that will be performed, when the value in this field has been changed.
Initial value	A JavaScript expression that provides a specific value that is used as default value for this field. It is shown and selected as the first value for this field, when the user opens the page. E.g., a choice in a drop-down, that is initially selected, or a sting in a text field that is already filled in. To enter a string or a value from choices, use quotes, e.g. "Yes" The JS expression's execution context has only 2 variables: field - field configuration application - same as `$scope.widgetApp`
Validations	Validations are described in-depth in a separate chapter of this guide. Validations that will be performed for this field. This setting overrides the default validations defined in the Wizard settings. To create several blocks of validations, click +Add in the bottom of this section.
Column Span	`1` The page of the wizard is divided into two invisible columns. Column span 1 means that the field uses space of one column on the page (or less, if the Size by content option is selected).
Enabled condition	`startingPointData['Owner1.Type'] == 'Person'` If the result of this expression evaluates to TRUE or if this setting is left empty, the field will be available for editing to the user, visible and enabled.
Visibility Condition	`startingPointData['Owner1.Type'] != 'Entity'` If the result of this expression evaluates to TRUE or if this setting is left empty, the field will be visible to the user.
Read-Only Condition	`scope.api.getCurrentWorkItemId() != null` If the result of this expression evaluates to TRUE, the field will be visible to the user, but as a read-only value. The condition can be used, for example, to lock the form after a Work item is created and the user just wants to review the data on the page.
Default Value	Leave this field empty. This setting provides a "hard-coded" value for this field. It will be used as the value for this field even if the user tries to change it.
Required	Selected If selected, the user will be required to fill in this field. This is a built-in validation. An asterisk will be displayed next to the field label.
New Line	Deselected If selected, the field will start on a new line on the page.
Size by content	Selected If the option is selected, the size of the field will change (stretch) to match the content in it. The Column Span setting will be ignored.
CSS class names	Leave empty, to keep the default styling. The field allows to enter several space-separated CSS class names defined in CSS/LESS or Global CSS/LESS tab, to override the default Docupace styling.

Step 2: Apply the Changes.

2.1. Click Apply button in the bottom of the screen to close the Widget Design Screen and apply changes.

2.2. Click Save button in the top of the Widget Details Screen to save these changes. Click on the Widget configuration cogwheel icon to open Docupace Start and proceed adding fields to pages.

Note: Repeat these two steps, when you have made several changes to the wizard and need to save them. If you leave your work for a time and your session times out, changes will not be saved.

How to Choose a Meta Field Name

Meta Field Name is the unique name for the data held within the field as it is referenced by code and in the database.

The Meta Field Name is a mandatory setting for all field types that may carry data to the system. If left empty for any of the fields, the wizard will not function properly. This issue is logged in the console. When a wizard doesn't load (a blank screen appears to the user), please check the console for this type of configuration error.

There are predefined field names in the PDF forms (client documents). Within the Docupace system most of these PDF names are mapped (cross-referenced) to a Meta Field Name in the BASE namespace.

If the data from your wizard must be mapped to a specific field in a PDF form, use the predefined values from the Quick Field Names Table. You may use either the name from the BASE namespace or the name used directly in the PDF form. If the mapping is working correctly, both cases should work.

^{A PDF form with field names visible}

One way to find out what meta field names and corresponding values to use, so that they map correctly to a PDF form, is to open a relevant document from a Client subfolder. Turn on Admin Mode, by clicking the cogwheel icon . Meta field names and their values can be seen by floating the mouse cursor over a field. They can be copied by right-clicking on the field.

The usual notation is objectName.propertyName.

Most of the objects and their properties are self-explanatory.

Examples:

Applicant1.IncomeRange
Guardian1.FirstName
Guardian1.LastName
Dependent1.Age
Spouse1.PrimaryPhoneType
Beneficiary1.PictureID
Rep1.RIANumber
Rep1.BranchPhone1

^{Meta Field Names and Values on a PDF form in Admin Mode}

If the data is only used for the purposes of this wizard, e.g. as a selector for further transitions, then you may create any name for it. It can be a stand-alone field name, or it can be a property of an object defined within the wizard (e.g. defined in the onLoad actions in Wizard Settings).

Warning! Unless the name comes from the Quick field list, the Meta Field Name must start with a letter. It may contain letters, numbers and underscores ("_"). Other characters are not permitted and will prevent the wizard from functioning properly.

Examples:

WizardChoice.MoreFilesAttached

myField1

nextPageNumber.

How to Access Meta Field Values

Most of the Docupace wizard flexibility and functionality relies on getting current values from the Meta Fields. Meta Field values are used in a number of settings: enabled condition, visibility condition, read-only condition, on value change actions, custom validations, transition actions, for displaying dynamic text in Rich Text fields, for setting initial value, and many more.

When writing JS expressions or code, you can access Meta Field values in several ways.

Syntax	Description	Example
`startingPointData['Meta Field Name']`	The recommended way how to access Meta Fields values. Prefix with `$scope`, when using in onEnter JavaScript code.	In visibility conditions, transition conditions, and similar, use this format: startingPointData['Owner1.FirstName'] In onEnter JavaScript use this format: $scope.startingPointData['Owner1.FirstName'] = 'John'
`model.parent.value["Local Meta Field Name"]`	Use this syntax if you need to read the value of a field in a repeating group. Used in visibility, read-only and required conditions. Note: Currently this syntax does not work for Rich Text Fields. It is not possible to set a visibility condition based on a value of a field in a repeating group.	For example, if you have a repeating group of phone numbers, which has a Phone Type, a Phone Number and an Extension, and you need to accommodate a business rule which says that Extension must be shown only if Phone Type is Business. In this case, the current number’s Type be accessed, which may be Phone1.Type, Phone2.Type, Phone3.Type, etc., depending on how many phones the repeating group has. The startingPointData object will not provide the correct Type. Use the following format: model.parent.value["Type"]
`widgetApp.wizard.getCurrentPageName()`	Get the current page name, in which this Java Script function is run.	widgetApp.wizard.getCurrentPageName()
`$scope.wizardState`	Another way how to access Meta Fields values. Note: Don't use $scope prefix in Visibility Conditions, leave only `wizardState` .	$scope.wizardState.Owner4 == true

How to Track Changes to Meta Fields

To configure actions within a wizard that are based on changes made to a Meta Field, use these methods.

Description

Example

Use $watch method of the $scope object to observe changes to any Meta Field values.

$scope.$watch('startingPointData["Owner1.FirstName"]', 
  function (newName) {
  console.log(newName)
})

To track changes made to any field in an object, pass 'true' as a third parameter into the $watch method.

$scope.$watch('startingPointData', 
  function (updatedStartingPointData) {
  console.log(updatedStartingPointData)
  }, 
  true))

Adding a New Field to a Page

Step 1: Add a Single Text Field.

Step 2: Apply the Changes.

How to Choose a Meta Field Name

How to Access Meta Field Values

How to Track Changes to Meta Fields