Mark Attachments and Attach

This article is about the "Mark Attachments" and "Attach" activities in Grooper. It explains the purpose, setup and relationship between these two activates. Mark Attachments and Attach help resolve common issues that occur during document separation (executed by the Separate activity in Grooper). These activities are essential for intelligently grouping and nesting related documents—such as addenda, supporting documents, or attachments—within a Batch Folder structure.

What are Mark Attachments and Attach?

Mark Attachments

Grooper.GPT.MarkAttachments

attach_file_add Mark Attachments is an Activity that analyzes documents (folder Batch Folders) to determine attachment relationships using configurable rules ("Attachment Rules"). It sets attachment markers on documents—indicating whether they should be attached to neighboring Batch Folders. These markers are then used by the Attach activity to group and nest related documents.

The Mark Attachments activity analyzes each document in a Batch Folder to determine if it should be attached to a neighboring document (such as a host or supporting document). This is accomplished by evaluating a set of configurable Attachment Rules, which compare the current document to its immediate siblings (the previous and next documents).

Key points:

• Operates at the Batch Folder scope, processing each document individually.
• Uses Attachment Rules to determine if a document should be attached to a "host" document and if it should be attached to its previous or next sibling Batch Folder.
• If a rule matches, a direction marker value is set and saved on the Batch Folder. The marker can be:
  • 1 = Attaches to the next sibling folder
  • -1 = Attaches to the previous sibling folder
  • No marker = No attachment
• Use the "Attach Children" property to determine if the entire document is attached as a nested child of the host document or if simply the pages are appended/prepended to the host document's pages. See below for more information on Attach Children.
• Mark Attachments does not modify the document structure; it only sets markers for use by the Attach activity.

Attach

file_present Attach is an Activity that physically moves and nests documents within a folder Batch Folder based on attachment markers set by the attach_file_add Mark Attachments activity. It consolidates related documents—such as addenda or supporting documents—under their host documents, updating the inventory_2 Batch hierarchy for downstream processing.

The Attach activity finalizes the attachment logic by physically moving and nesting documents within a Batch or Batch Folder, based on the attachment direction markers set by Mark Attachments.

Key points:

• Operates at the document's parent level, processing each child document in sequence.
  • In most scenarios, the "parent level" will be the Batch.
  • In scenarios with a more nested Batch hierarchy, the "parent level" will be the document's parent Batch Folder.
• Reads the direction marker value set by the Mark Attachments activity on each child to determine attachment behavior.
  • If the marker is 1, the document is moved as a child of the next sibling.
  • If the marker is -1, the document is moved as a child of the previous sibling.
  • If no marker is set, the document remains in place.
• Updates the Batch hierarchy. This enables better downstream extraction, review, and export, treating the attached documents as part of their host.
• Attach will do nothing if Mark Attachments does not run before it.

How are Mark Attachments and Attach related?

These two activities are designed to work together in sequence:

1. Mark Attachments analyzes and marks documents for attachment, but does not change the Batch structure.
2. Attach reads the markers and physically nests either the whole documents or their pages according to the specified attachment directions.

This two-step process allows for flexible, rule-based, and even AI-enhanced logic to determine document relationships before any structural changes are made.

How do Mark Attachments and Attach work?

Mark Attachments: How it works

• For each document in a Batch Folder, the activity evaluates the configured Attachment Rules.
• Each rule can use Document Type, position, and optionally AI-driven content analysis to determine if the document should be attached to its previous or next sibling.
• The first rule to match sets the attachment direction marker ("Attach.AttachmentDirection") on the document.
• No changes are made to the batch structure at this stage.

Example:

Before running Mark Attachments:

Batch
 ├─📁 Main Document
 ├─📁 Addendum
 ├─📁 Supporting Doc
 └─📁 Other Document

After running Mark Attachments (markers set):

Batch
 ├─📁 Main Document
 ├─📁 Addendum (Attach.AttachmentDirection = -1)
 ├─📁 Supporting Doc (Attach.AttachmentDirection = -1)
 └─📁 Other Document

In this example, "Addendum" and "Supporting Doc" are marked for attachment to the previous document ("Main Document").

Attach: How it works

• The activity processes each child Batch Folder in the parent folder.
• For each child, it reads the "Attach.AttachmentDirection" marker:
  • If the marker is 1 and the next sibling is a valid host Content Type, the document is attached to the next sibling (or if Attach Children is False, it will prepend the document's pages).
  • If the marker is -1 and the next sibling is a valid host Content Type, the document is attached to the previous sibling (or if Attach Children is False, it will append the document's pages).
  • If no marker is set, the document remains in place.
• The Batch hierarchy is updated, nesting supporting documents under their host.

Example:

After running Attach:

Batch
 ├─📁 Main Document
 │   ├─📁 Addendum
 │   └─📁 Supporting Doc
 └─📁 Other Document

Attach Children

The Attach Children property in Mark Attachments controls whether the entire attachment document (including is child pages/subfolders) are moved under the host document or only its children are moved.

• When Attach Children = True:
  • All children (pages and subfolders) of the attachment are moved directly under the host document, and the original attachment folder is removed.
  • This helps resolve common document separation problems where pages were unnecessarily separated as a whole document of a particular Document Type. If the pages simply needed to be prepended/appended to a host document, setting Attach Children to "True" will do and remove the unnecessary folder.
  • TLDR; Do this if you want to attach pages only.
• When Attach Children = False (default):
  • The entire attachment folder (including its children pages and subfolders) is nested under the host document.
  • This is useful for scenarios where the attachment needs to be part of a host document's internal structure, but still treated as a document in Grooper for subsequent activities, such as Extract.
  • TLDR; Do this if you want to attach the whole document.

Example:

Before running Attach (Attach Children = True):

Batch
 ├─📁 Main Document
 │   │ 📄 Main Document Page 1
 │   └─📄 Main Document Page 2
 ├─📁 Addendum (Attach.AttachmentDirection = -1)
 │   │ 📄 Addendum Page 1
 │   └─📄 Addendum Page 2
 ├─📁 Supporting Doc (Attach.AttachmentDirection = -1)
 │   │ 📄 Supporting Doc Page 1
 │   └─📄 Supporting Doc Page 2
 └─📁 Other Document
     └─📄 Other Document Page 2

After running Attach (Attach Children = True):

Batch
 ├─📁 Main Document
 │   │ 📄 Main Document Page 1
 │   │ 📄 Main Document Page 2
 │   │ 📄 Addendum Page 1
 │   │ 📄 Addendum Page 2
 │   │ 📄 Supporting Doc Page 1
 │   └─📄 Supporting Doc Page 2
 └─📁 Other Document
     └─📄 Other Document Page 2

How to set up Mark Attachments and Attach

Setting up Mark Attachments

1. Add the Mark Attachments activity to your Batch Process.
2. Configure step's Scope to the appropriate folder level (typically at the lowest Batch Folder level in the Batch hierarchy).
3. Configure the Attachment Rules property:
   • Add one or more rules to define when a document should be attached to its neighbor.
   • Rules can be based on Document Type, position (before/after), or AI-driven content analysis.
   • Arrange rules from most specific to most general for best results.
   • If using AI-based rules, ensure the model, instructions, and quoting settings are properly configured.
4. Ensure Mark Attachments runs before Attach.

Setting up Attach

1. Add the Attach activity to your Batch Process immediately after Mark Attachments.
2. Configure the step's Scope to the parent level (one level above the documents to be attached).
3. No additional configuration is required, as the activity reads the markers set by Mark Attachments.
4. Ensure Attach runs after Mark Attachments.
5. After running Attach' attachments will be consolidated under their host documents.

Best practices

• Always run Mark Attachments before Attach in your workflow.
• Carefully design your Attachment Rules to match your Document Types and attachment scenarios.
• Use AI-enhanced rules for complex or unstructured documents where simple rules are insufficient.
• Test your configuration on sample Batches to ensure correct grouping and nesting.