Document Viewer

Overview

The Document View field displays a PDF as navigable pages inside a record. Users can move between pages and zoom in to inspect the document.

With optional image tagging configured, users can place markers on PDF pages. Each marker links a position in the document to a child record containing relevant details, such as a description, owner, priority, evidence or review status. Clicking an existing marker opens its linked record.

Document View can be used with any PDF, including floor plans, contracts and policies. Markers appear over the PDF; they do not change the PDF file itself.

Example used in this guide: The screenshots show a project floor plan with snag records. This is one application of Document View. The names Site Map PDF, Site Map View and Snagging List belong to that example. Choose names and child-record fields appropriate to your own process.

Example of Document View in Workspace: a floor plan with clickable snag markers and a separate embedded child report beneath it.

Use Document View with different documents

For each use case, a Document field stores the PDF and Document View displays it. An optional child app stores the records linked to markers.

The page, position and document-version mappings work in the same way across these examples. Your choice of child fields, marker images and templates determines what each marker means and what users can do with it.

Choose the capabilities your app needs

• Display a PDF: Follow Section 2 to add the Document and Document View fields, place them on a template and publish the parent app. A child app is not required for viewing alone.
• Add interactive markers: Follow Sections 1 and 3 to integrate a child app and configure marker fields and templates. Section 6 covers marker images, filtering and tooltips. Section 9 explains PDF replacement behaviour.
• Extend the solution: Sections 4, 5, 7 and 8 demonstrate the floor-plan example, its separate embedded report, and optional completion and archive workflows.

The list beneath the viewer is a separate Embedded Report field. The completion and archive behaviours demonstrated here are configured through child-app workflows.

Contents

1. Prepare the parent and child apps
2. Configure the PDF and Document View fields
3. Configure marker fields and templates
4. Worked example: follow one snag through its lifecycle
5. Optional: add an embedded child report
6. Configure marker images, filtering and tooltips
7. Optional: show and hide markers using a completion workflow
8. Optional: add an archive action and restore child records
9. Replace the PDF and handle stale markers
10. Publish the solution

1. Prepare the parent and child apps

This section is needed when you want markers linked to child records. For PDF viewing alone, go directly to Section 2.

The app that owns the PDF is the parent app. The app that stores one record for each marker is the child app.

1. In the parent app, open Advanced > Integrate.
2. Add the child app under Child App Integrations and save the integration.
3. In the child app, create the fields needed for each marker record.
4. Create a template for new records and a template for opening existing records.

In this example, Project App is the parent and Snagging List is the child app.

Integrate Snagging List as a child of Project App before selecting it in the viewer.

The example’s Create Snag Item template captures:

• Snag
• Priority
• Location
• Assigned To
• Observation Evidence

The create template captures the details needed for a new snag.

The View Snag Item template contains those fields plus Complete? and Remove?, allowing users to update or archive an existing item.

The open template adds completion and removal controls for existing records.

Leave marker-position fields and workflow backup fields off normal user templates. Only place the fields users need on those templates.

The Exclude Backing Fields? control filters the template designer’s field picker. To keep internal fields out of the Workspace form, leave them off the template.

Fields used by the floor-plan example

Use these identifiers if you are reproducing the example so the expressions and workflow mappings below match your fields.

For contracts, policies or other documents, use appropriate business fields and names while retaining the four marker mappings described in Section 3.

The viewer generates its four marker fields separately. The optional completion workflow requires four additional backup fields, listed in Section 7.

2. Configure the PDF and Document View fields

Add the Document field that holds the PDF

1. Open the parent app in App Studio.
2. Go to Input & Layout > Fields.
3. Add a field with type Document.
4. For this example, enter Site Map PDF as the label and SiteMapPDF as the identifier.
5. To restrict uploads to PDFs, expand File Types (Preview), enable Specific Types, and select PDF under Accept File Types.
6. Save the field.

Configure the Document field that stores the PDF. Enable Specific Types if uploads should be restricted to PDF files.

Add the Document View field

1. In the parent app, open Input & Layout > Fields.
2. Open the field-type selector at the top right and type document.
3. Select Document View, then click Add at the bottom of the Fields screen.

Find Document View in the field-type selector, select it and use Add to create the viewer field.

4. Enter Site Map View as the Label and SiteMapView as the Identifier.
5. Under Setup, set Parent PDF Document field to Site Map PDF [SiteMapPDF].
6. Save the field.

The label is the name users see above the viewer in Workspace. The source-field selection connects the viewer to the PDF stored on the same parent record.

Name the viewer and select Site Map PDF as its Parent PDF Document field.

Leave Image Tagging (Optional) unconfigured if you only need PDF viewing. Continue with Section 3 to enable child-record markers.

Put the fields on the form and display a PDF

1. Open Input & Layout > Templates in the parent app.
2. Edit the template used by the form.
3. Add Site Map PDF so users can upload the document.
4. Add Site Map View where the PDF should appear.
5. Save the template and publish the parent app.
6. In Workspace, open a parent record and upload a PDF using Site Map PDF.

Site Map View displays that record’s PDF. Users can move between pages and use the zoom controls to inspect the document.

3. Configure marker fields and templates

Edit the Document View field and find Image Tagging (Optional).

1. Select the integrated child app.
2. Use Generate missing fields to add the four fields used to locate a marker.
3. Select the Child create template and Child open template.
4. Map the marker fields.

The generator creates missing fields in the child app and identifies existing fields that are ready to use.

Select the child app and generate any missing marker fields. Publish the child app to make those fields live.

The page and normalised coordinates let the marker return to the same location when the page is displayed at a different zoom.

The document asset/version value lets the viewer distinguish markers created against different PDF versions.

Configure the child templates, marker mappings, marker Image List and tooltip fields.

How marker creation works

When a user clicks a point on a PDF page, the viewer:

• Opens the selected child create template.
• Supplies the marker’s page, X, Y and document-version values.
• Links the new child record to the parent record from which it was added.

Users do not need to enter coordinates or select the parent manually.

Clicking an existing marker opens its child record using the configured Child open template.

There is currently no control for repositioning an existing marker. To replace a marker at another location, archive the unwanted record and create a new marker at the intended point.

4. Worked example: follow one snag through its lifecycle

This walkthrough demonstrates the configured templates, marker artwork and optional report and workflows.

In a document-review app, the equivalent journey could be to mark a clause, assign its review and update its status.

Create a snag from the PDF

Open the project record in Workspace. Use the viewer’s page controls to display the ground floor, then click the position of the window-sill defect.

The configured Create Snag Item template opens over the plan. The viewer supplies the marker position and parent link automatically.

Clicking the PDF opens the create template for a new linked snag.

Enter:

• Snag: Small paint mark on the window sill. Touch up the finish.
• Priority: Red
• Location: Lounge
• Assigned To: Andy Bruce

Use Observation Evidence to attach a photograph. Complete the required fields; this example does not use a separate Save button to create the snag.

The record includes its description, priority, location, assignee and photographic evidence.

Open and update the snag

Close the pop-up to return to the plan. The red “1” image marks the saved position, and the separate report below contains the same snag under Lounge.

The number is part of the selected Priority image. It is not a unique record number, so several snags can use the same marker image.

The active snag appears on the plan and in the report beneath it.

Click the marker to open the configured View Snag Item template. This template includes Complete? and Remove?.

When the completion workflow described in Section 7 runs, the marker disappears while the report row remains with a green completion image.

After completion, the marker is hidden while the child record and its evidence remain available in the report.

To reopen completed work, open the child record from the report and change Complete? back to Not Ticked. The workflow restores its saved marker values. The marker can appear again when its page and document-version conditions match.

Remove? is a separate action that archives the record. Section 8 explains how to restore archived work.

5. Optional: add an embedded child report

The list beneath the PDF is a separate Embedded Report field.

1. Configure a report in the child app.
2. Add an Embedded Report field to the parent app.
3. Select the child app and the report to display.
4. Set the height.
5. Place the field beneath Document View on the parent template.

In the example, the report is grouped by Location and displays:

• Snag
• Location
• Assigned To
• Priority
• Complete?
• Observation Evidence
• Remove?

Select the child app and report to display beneath the PDF.

The embedded report follows the parent-child hierarchy, so it displays records belonging to the current parent. Any base filter configured on the selected child report also applies. The example uses no base filter.

This report provides a way to open records even when their markers have been hidden by a completion workflow or document-version setting.

6. Configure marker images, filtering and tooltips

Marker appearance and filtering

Select an Image List field under Marker Image List field.

The selected option supplies the entire marker image, including its colour, icon and any text or number within the image.

In this example, Priority uses an Image List containing:

• TBA
• Red
• Yellow
• Orange
• Green
• Blue

The images in the Priority list become the marker artwork.

The viewer’s Type selector filters markers using the options from this Image List.

Workspace users can focus on markers belonging to a selected category.

For a contract or policy, the Image List could distinguish categories such as obligations, questions and actions instead of snag priorities.

Tooltip fields

Choose the child fields that should appear when a user hovers over a marker.

Tooltip values can come from ordinary fields or Text fields populated by expressions. Prepared text values can make the meaning clearer.

For example, “Assignee: Andy Bruce” explains that Andy is responsible for the action. Displaying only “Andy Bruce” could leave the reader unsure whether Andy is the assignee or the person who raised the item.

For the example’s Complete Text field, use:

if([Complete] <> 'Ticked', '❌ Not Complete', '✅ Complete')

Select this Text field in the viewer’s tooltip configuration to show a readable status.

An expression turns the stored completion value into readable tooltip text.

7. Optional: show and hide markers using a completion workflow

This behaviour is configured through a child-app workflow. You can use the same pattern for resolved document-review comments or completed policy actions.

The workflow:

• Copies live marker values into backup fields when the record is completed, then clears the live values.
• Restores the live values when the record is reopened, then clears the backups.

The child record remains available in the report throughout.

The upper branch backs up and clears live marker values. The lower branch restores them and clears the backups.

Configure the completion field

Create an Image List field with:

• Label: Complete?
• Identifier: Complete
• Image List: Ticked

The list contains two options:

• Grey image: title and stored value Not Ticked
• Green image: title and stored value Ticked

For this build, use Not Ticked as the initial value.

Complete? is an Image List field with identifier Complete and source list Ticked.

The workflow and tooltip expression use the stored values Not Ticked and Ticked.

Preserve these values or update the workflow expressions to match your chosen values.

Add the backup fields

Create four additional child fields. These are part of the optional workflow and are separate from the four fields generated by the viewer.

Configure the completed branch

Add a Field updated trigger and a Filter with:

[Complete] = 'Ticked'

With this trigger-and-filter pattern, the field referenced by the filter must have changed and the condition must be met.

Add an Update field value node that copies each live value into its backup:

Follow it with another Update field value node:

The original marker position is retained in the backups, while clearing the live fields hides the marker.

Configure the reopened branch

Add a second filter branch:

[Complete] <> 'Ticked'

First restore each live field:

Then clear the backup fields:

Configure the update-node options

The example enables:

• Use rolling updates
• Pass updated values to following workflow actions

Its parameter conflict behaviour uses the value at the time of the workflow trigger. Its target conflict behaviour overwrites the target field.

Clearing the backups after restoration matters. An update node that makes no value changes does not continue to subsequent actions. If old backup values remain, a later completion cycle could reach a backup node that has nothing to change and stop before clearing the live marker values.

Publish the child app after configuring the workflow.

See the values move in Workspace

The following screenshots expose internal fields to explain the workflow to App Builders. Leave these fields off normal user templates.

Before completion, the live fields hold the position and version. The backups are empty or zero.

Builder diagnostic view: the active marker values are held in the live fields.

After completion, the live values are cleared and the backups hold the original values.

The original position and document version are retained while the marker is hidden.

After reopening, the original values return to the live fields and the backups are cleared.

Restored live values allow the marker to appear again, subject to the PDF-version setting.

8. Optional: add an archive action and restore child records

Create an Action field called Remove?, with identifier Remove.

Configure a child-app workflow with:

1. A Button clicked trigger for the Remove? field.
2. An Update record action set to Archive.

Place Remove? on the child open template and in the child report.

The Remove? action triggers a workflow that archives the child record.

Archiving removes the record from the active embedded report and removes its active marker from the PDF. The record remains available for restoration.

Restore an archived record

1. Open the child app’s report.
2. Choose Show Archived.
3. Select the record or records to restore.
4. Choose Unarchive.

You can also open an archived child record and use Unarchive from its record menu.

Select archived records and use Unarchive to restore them.

A restored record can display its marker again when it has valid marker values and the document-version setting allows it.

9. Replace the PDF and handle stale markers

Use Hide stale markers when the backing PDF changes to control what happens to markers created against an earlier PDF.

Option disabled: retain existing positions

Existing markers continue to use their stored page and coordinates on the replacement PDF.

This is useful when the document changes but the marked positions still make sense. If the page layout or content moves, existing markers may no longer point to the intended feature.

The Willowbrook V2 plan changes the lounge furniture while preserving the meaning of the existing marker positions.

With stale-marker hiding disabled, markers from the earlier plan remain visible on V2.

Option enabled: hide markers from earlier versions

The viewer compares each marker’s stored document asset/version with the PDF currently displayed. Markers with a different version are hidden.

The linked child records are retained.

Turning this option on after uploading a replacement PDF also hides markers created against the earlier version.

With stale-marker hiding enabled, markers associated with the earlier PDF are hidden.

Choose the required behaviour in the Document View configuration.

10. Publish the solution

App Studio changes are staged until published.

Publish the child app after generating marker fields or changing its fields, templates, reports and workflows. Publish the parent app after changing its Document View field, templates, child integration or embedded report.

For the complete example, publish both apps.

Once published, work through the configured journey in Workspace:

• Display the PDF and move between pages.
• Place a marker and enter the child-record details.
• Open an existing marker.
• Use the Type filter and hover tooltip.
• Complete and reopen a record.
• Archive and restore a record.
• Replace the PDF using the selected stale-marker behaviour.

Floor-plan example configuration at a glance