Merge (Activity)

⚠	This article was migrated from an older version and has not been updated for the current version of Grooper. This tag will be removed upon article review and update.

This article is about the current version of Grooper.

Note that some content may still need to be updated.

2025

2023.1

file_save Merge is an Activity that creates a PDF, TIF, XML or ZIP file from the page and data content of a Batch Folder and saves it to that Batch Folder.

You may download the ZIP(s) below and upload it into your own Grooper environment (version 2023.1). The first contains one or more Batches of sample documents. The second contains one or more Projects with resources used in examples throughout this article.

About

So, you've gone through the first 4 phases of Grooper: Aquire, Condition, Organize, and Collect.

You have extracted data from your documents and you want to now build a document. The Export activity can build the document and export it outside of grooper all in one step. However, you might have a desire to build the document before executing the Export step in your Batch Process. You can do this with the Merge activity.

The Merge activity builds a document from the Pages in a Batch and saves that document to the Batch Folder. You can choose to build your document in a specific format such as a PDF or TIFF file. You can also automatically rename the documents as they're built.

Three Ways to Name

There are three different ways to name the final Merged file: Use the Custom Filename property, use the Attachment Name property, or use the default naming settings.

The most important difference among these methods is whether or not Grooper creates a new file and attaches that new file to the Batch Folder leaving the original content intact, or whether it overwrites the main content of the Batch Folder.

Which method is best depends on your specific company needs, so choose the option that best applies to your use case. We will go over how to set all of this up in the How To section of this article.

How To

The Merge activity is applied to a Batch via a Batch Process Step. The following tutorial will show you how to add the Batch Process Step and how to configure the Merge activity.

Creating the Batch Process Step

The first thing we need to do is add a Merge Batch Process Step to our Batch Process and set the Scope at which the step will run.

Right-click on the Batch Process.
Hover over "Add Activity", then hover over "Transform". Finally, Click on "Merge..."
When the "Add Activity" window pops up, feel free to change the name of the step in the Step Name property. For this tutorial we will be using the default of "Merge".
Click "EXECUTE" located in the top right hand corner of the pop up window.

Now you should have a Merge step in your Batch Process.
Your scope should be set to the Folder Level containing the pages that will be combined into a document. In our case that is Folder Level 1, so we have set the Scope property to Folder and the Folder Level property to 1.

Configuring the Merge Activity

Now that we have our Batch Process Step in our Batch Process we need to configure the Step to tell Grooper how to Merge the pages.

Click the hamburger icon to the right of the Merge Format property in the rightmost property grid and select the desired file type from the drop down list. For this tutorial, we will select PDF.

You can set a name for the resulting merged document using either the Custom Filename or Attachment Name property. Ignore the Save As property as it is currently broken in 2023 and 2023.1.

The Custom Filename Property

The first of the two naming properties is the Custom Filename property. When using this to name your merged file, the file will be named literally what you type into the property, including the file extension. It will then create a copy of the file and attach it as a separate attachment to the Batch Folder. The original file will remain intact and unchanged on the Batch Folder.

Enter in a name you want to name the PDFs in the Custom Filename property located in the rightmost property grid. Include the file extension in the file name.
Click the save icon at the top right of the middle property grid.

⚠	You MUST include the file extension in the naming of your file. If you do not, you will not get a useable file once the documents are merged.

Click over to the "Activity Tester" tab.
Select the Batch Folder containing the document you want to Merge.
Click the Test icon at the top right of the Batch Viewer.

At first glance, it might appear that the Merge activity didn't actually do anything. This is because it has not altered the main content of the Batch. If you would like to view the newly created file, follow these additional steps:

Navigate through your Test Batches in the node tree to the Batch Folder you tested the Merge activity on.
Click on the "Advanced" tab.
Under "FILES" on the right-hand panel, you should see the new merged PDF file.

Why You Need to Include the File Extension

If you do not include the file extension in your Custom Filename...

... you will still get an attached file, but it will not be a PDF or other useable file type.

The Attachment Name Property

The Attachment Name property is a little more complicated than the Custom Filename property. The Attachment Name property uses expressions to name your file. In this tutorial, we will be using String Interpolation expressions to name our files.

Also, the Merged file simply overwrites the main content attached to the Batch Folder rather than creating a brand new file. So, in our examples you will see the file name on the Batch Folder itself change.

Click the ellipsis icon to the right of the Attachment Name property.
When the "Attachment Name" window pops up, insert an expression for how you want to name the attachments. In our example we have used a String Interpolation expression to name the document with a random GUID:
```
$"{Guid.NewGuid}.pdf
```
Click "OK" located in the top right of the pop-up window.

Click the save icon at the top right of the middle property grid to save your changes.

Click over to the "Activity Tester" tab.
Select the Batch Folder containing the document to be merged in the Batch Viewer.
Click the Test icon at the top right of the Batch Viewer.

The file has now been merged, named, and replaced the existing file in the Batch. You can see the new name of the file under the Batch Folder name.

Selecting the Content Type

If you want to use Data Elements from your Content Model to name your files, you can do this by selecting your Content Model in the Content Type property. This will provide the scope from which you can call Data Elements in your String Interpolation code.

Under our Content Model, we have a Data Model with two Data Fields: Company Name and Contact Name. Let's say we want to use these two Data Fields to name the file.
Click on the hamburger icon to the right of the Content Type property to access the drop down.
Navigate to and select the Content Type that contains the information you want to include in your naming expression. In this case, we're selecting the Content Model containing the Data Fields we want to use to name the file.

Click the ellipsis to the right of the Attachment Name property.
Start your String Interpolation expression with $" then add a { to bring up the intellisense and choose the first part of the code to call.
The intellisense will show you what you can use in your expression within the scope of your specified Content Type. We can see that we have access to both of the Data Fields we want to use for the naming convention.

Finish your expression. In our example, we used:
```
$"{Company_Name}.{Contact_Name}.pdf"
```
Click "OK" located in the top right of the "Attachment Name" pop-up window.

Click the save icon at the top right of the middle property grid.

Click over to the "Activity Tester" tab.
Select the Batch Folder containing the document you want to merge in the Batch Viewer.
Click the Test icon in the top right of the Batch Viewer.

The file has been merged, named, and replaced the original file. You can see the new name under the Batch Folder name in the Batch Viewer.

Using the Defaults

If you choose to not enter a Custom Filename or Attachment Name, Grooper will still run the Merge activity. However, the Merged file will overwrite the main content of the folder and simply be named the same as the Batch Folder.

If you leave the naming properties as their defaults, the Step will still Merge the document.
Click the save icon at the top of the middle property grid if needed.

Click over to the "Activity Tester" tab.
Select the Batch Folder containing the document you want to Merge in the Batch Viewer.
Click the Test icon in the top right of the Batch Viewer.

The merged PDF file is named the same as the Batch Folder.

The Clear On Completion Property

Enabling the Clear on Completion property will delete the Page objects from your Batch Folder once the Merge activity has been completed.

Set the Clear on Completion property to True.
Click the save icon located at the top of the middle property grid.

Click over to the "Activity Tester" tab.
We have expanded out the Batch Folder in the Batch Viewer to show that this document has one Page inside.
Make sure the Batch Folder is selected.
Click the Test icon located in the top right of the Batch Viewer.

After testing, you can see that the file has been built and named (notice the change in the file name underneath the name of the Batch Folder).
However, there are no more Page objects in the Batch Folder. They have been cleared once the Merge Activity completed.