Document Phase

Built to support HTML5, a Document Phase supports form elements such as check boxes and entry fields as well as media.

Content can be driven by Ignition tag values and other phases.

Document Phase Change Propagation

Included in 3.81.11 SP9 and later.

The Document Phase Change Propagation feature is a core mechanism for managing and distributing updated documents from a central 'document phase' to all associated recipes and templates where it is utilized. Its strategic purpose is to ensure that revisions made to a source document can be systematically and intentionally pushed downstream, maintaining consistency across multiple dependent items.

This guide details the propagation mechanism, the user controls that govern it, the expected outcomes of your actions, and known operational limitations of the feature. To use this feature effectively, it is important to first understand its fundamental concepts and workflow.

The Propagation Mechanism: How it Works

Understanding the step-by-step process of document propagation is key to leveraging this feature correctly. The mechanism is not automatic; it is a deliberate action controlled by the user during the phase update process, designed to give you explicit control over how and when document changes are distributed.

Change Detection and Versioning

The propagation process is initiated when a document linked to a document phase is modified.

• The "Changed" Status Trigger When a document attached to a document phase is changed, its status is recorded as "Changed."
• Automatic Phase Versioning This change automatically triggers an increment of the phase version number, creating a new version of the phase that contains the updated document.

The User Control for Propagation

The decision to propagate the document change is managed by a single, critical user control element.

• The Propagation Checkbox A checkbox is located within the phase update dialog.
• Explicit User Permission Checking this box explicitly grants permission for the document changes to be pushed from the updated phase to all dependent recipes and templates.

The Forceful Overwrite Behavior

Enabling propagation has a significant and immediate impact on the recipes where the document phase is used. The new version of the document from the phase forcefully overwrites whatever document was previously attached to the recipe.

Warning: This overwrite occurs even if the recipe's document had been modified from the original phase document. As a result, any local changes made to the document at the recipe level will be permanently lost once propagation is enabled.

This concludes the mechanics of how the propagation is triggered and executed. The following section details the specific outcomes based on your choice to enable this feature.

Expected Outcomes Based on User Action

The update status of all associated recipes and templates is determined entirely by the user's decision to "push" the document edits during the update process. The outcome varies depending on whether you check the propagation box and which assets you target for the update.

Scenario 1: Propagating Document Edits (Checkbox is CHECKED)

When the checkbox is checked, the updated document is successfully pushed from the phase to the targets you select.

• When only updating recipe: Recipes that use the document phase will be updated with the new document.

• When only updating templates: Templates that use the document phase will be updated with the new document.

• When updating recipes and templates: Both recipes and templates that use the document phase will be updated.

Scenario 2: Not Propagating Document Edits (Checkbox is UNCHECKED)

If you choose not to check the propagation box, the document changes remain isolated within the document phase. No downstream assets will be updated.

• When only updating recipe: Recipes will not be updated with the document phase change.

• When only updating templates: Templates will not be updated with the document phase change.

• When updating recipes and templates: Neither recipes nor templates will be updated.

While these scenarios describe the intended behavior, it is important to be aware of certain limitations observed during testing, which are detailed below.

Known Limitations and Important Notes

This section contains critical information for the successful use of the Document Phase Change Propagation feature. While the functionality is robust for updating recipes, testing has revealed specific limitations regarding template updates that users must be aware of to avoid unexpected results.

Observed Behavior in Template Updates

Recent testing has identified inconsistencies when attempting to propagate document changes to templates. The following outcomes were observed:

• If the user selects to update only the recipe, recipes will update correctly.

• If the user selects to update only templates, templates do not update.

• If the user selects to update both recipes and templates, recipes are updated, but templates are not updated.

Users should factor this observed behavior into their workflow, particularly when managing documents intended for use in templates.

Note on Non-Document Phases

Please note that the behaviors and limitations described in this guide apply exclusively to the propagation of documents within document phases. Standard propagation for phases that do not contain documents operates under a separate mechanism and is expected to function as intended.

Extract HTML Documents from Document Phases

To extract HTML documents from document phases, use the scripting function: batch.queue.getStepDocument(batchID, Document Phase Reference).

See  Properties Common to All Phase Parameters

Exposed Set to True

When true, recipe parameters are available to reference in the form fields.

Only parameters that match the field data type are displayed.  For example, Checkbox only work for "Boolean" type parameters, Input fields of a "number" type only work for Integer/Short/Long type parameters, 

Editing a Document in a Document Phases

In Phase Manager, edit the Document Phase and then click the edit document in the Base Phase field.

In Recipe Editor, click the pencil icon to edit the document.

The document opens where you can add media and form fields.

Input Fields and Referencing Parameters

Version Specific 3.81.10 SP When adding new input fields to a document in Batch Phase Manager or Batch Recipe Editor, new fields are highlighted with a warning until the field is attached to a Batch Parameter. This indicates that the field is not correctly attached to a parameter.

Edit Menu

Referencing Phase Parameters in Form Fields

The default phase parameters and user-defined phase parameters can be tied to form fields. 

• Right click a form field in the Document Editor and select Form Field Properties.
• Each form field has its own set of properties. Each has the option: Attach to Batch Parameter. Enable Attach to Batch Parameter.

See below for each form fields unique properties.

Checkbox Form Field Properties

Radio button Form Field Properties

Dropdown List Form Field Properties

Text Area Form Field Properties

Text Form Field Properties

Batch Procedure Phases