How can you share Grooper objects, like Content Models, Batch Processes, Batches and more, with other Grooper users?
About
Grooper allows you to export Grooper objects from a Grooper Repository as a zip archive file. You can then bring in those objects into a Grooper Repository by importing the zip file.
The process is straightforward, but there are a few things to watch out for.
FYI
Additionally you can "publish" Projects from one Grooper Repository to another. This allows Grooper users connected to multiple Grooper environments to copy objects directly from one environment to another without the need to export and import a zip file.
When exporting/importing Grooper objects, you will do one of three things.
You will either:
Export/import Batches
Export/import full Projects
Export/import single objects inside a Project
In the following tutorial, we're going to export several objects from a "testing" Grooper Repository and import them into a "production" Grooper Repository.
Export Grooper Objects to a Zip File
Exporting Batches - Single Batches
First, we're going to export a single Batch from a Grooper Repository. You can export either "Production" or "Test" Batches.
Right-click the Batch you want to export.
Select Share
Select Export to Zip Archive...
This will bring up the Share • Export to ZIP Archive configuration window.
Use the Filename property to define the storage path as well as the zip file's name.
Press the Execute button to export the Batch, saving it to a zip in the selected location.
How will a user then get this Batch into a Grooper Repository? They will import it. Check out the #Import Grooper Objects from a Zip File section of this article for more information.
FYI
If you select the Filename property and press the ellipsis button on the end, this will bring up a folder navigator to select an export path and name the file.
Exporting Batches - Multiple Batches
What if you want to export more than one Batch? Do you have to export individual zip files for every single Batch? You could do this, but there's another way. Simply put all the Batches you want to export in a folder. Then, export the folder.
When you export a folder to a zip file, all its contents are exported as well.
I want to export both these Batches.
By placing them in a folder, I can do so without exporting each one individually.
All of a folder's contents will be exported when exporting to a zip archive.
Or in our case, both Batches
Exporting Full Projects
You can also export full Projects to zip files. All its contents will be exported as well. Generally speaking, the Project contains all the processing resources necessary (the Content Model, Batch Process and other Grooper objects) to execute a Batch Process and process one particular document set. However, sometimes, you will reference resources in other Projects using one or more Referenced Projects. In this case, you will need to ensure all referenced Projects are exported at the same time to ensure the zip file can be imported down the road.
Exporting Full Projects - Single Projects Without References
We'll start with the simpler situation, exporting a Project that has noReferenced Projects.
We want to export this Project.
All of its contents will be exported as well.
FYI: This includes any subfolders and/or children of its contents.
According to the Referenced Projects property, this Project makes no references to other Projects.
This makes our job easy. We can export the Project as a single item.
Right-click the Project you want to export.
Select Share
Select Export to Zip Archive...
In the Share &bull: Export to Zip Archive window, use the Filename property to select the zip file's path and name.
Press the Execute button.
Exporting Projects - Exporting Multiple Projects and Projects With References
If you want to export multiple Projects, you'll need to place them in a folder, and export the folder (as we did when we exported multiple Batches in the previous tab of this article).
The same advice is true for Projects with references to other Projects.
Say we want to reference this Project named "Invoice".
According to the Referenced Projects property, this Project makes references to two other Projects.
An extractor from the "Essentials" Project is used in this Content Model's configuration.
An extractor from the "Shared Resources" Project is used in the configuration of this Data Model'sData Elements.
To properlyexport the "Invoices" Project, the "Essentials" Project and the "Shared Resources" Project must be exported along with it. We will export all three projects by placing them in a folder and exporting the folder as a zip file.
FYI
The Analyze References button can be useful when evaluating a Project's references.
Pressing this button will show you the Node Tree path for every object used by referenced projects.
Hint: The referenced Project's name will be at the beginning of the path. The referenced object's name will be at the end the path.
• For example the "Invoices" Project makes use of the "Words" extractor (the referenced object which is at the end of the path) in the "Essentials" Project (the referenced Project which is at the beginning of the path)
To properly export the "Invoices" Project, it and all its referenced Projects should be placed in a folder. Then, the folder should be exported.
All three Projects have been placed in a folder.
Exporting the folder will export all the Projects contained, ensuring all references are preserved.
⚠
If you do export a Project without exporting its referenced Projects, you will get an error upon attempting to import the zip file.
⚠
Be aware if you have a complicated web of references, you may need to check the referenced Project to see if it references any Projects itself.
Imagine we want to export this Project named "Human Resources"
According to the Referenced Projects property, this Project references the "Invoices" Project.
That means, we need to not only included the "Invoices" Project in the export, but the "Essentials" and "Shared Resources" Project it references as well.
In other words, we'd need to export a folder with all four Projects contained to properly preserve the references throughout the various Projects.
Exporting Objects in a Project
You may also export individual objects within a Project. For example, you may want to share a particular profile you've created with another Grooper user or repository.
The process is essentially identical to what we've seen so far. Right-click the object, select export to zip archive, configure the file's path and name.
We're going to export an IP Profile named "Permanent Cleanup" in the "URLA" Project.
Right click the object you want to export.
Select Share
Select Export to Zip Archive...
In the Share • Export to Zip Archive window, use the Filename property to select the zip file's path and name.
Press the Execute button.
If you need to export multiple objects, you can put them in a folder and export the folder (just as we've seen with exporting multiple Batches and multiple Projects).
We can export all three of these IP Profiles.
We just have to export their parent folder.
⚠
When exporting objects in a Project please be vigilant in order to maintain reference integrity.
If you wanted to export this OCR Profile, you couldn't only export this single object.
The OCR Profile references an IP Profile as part of its configuration.
Both objects would need to be exported at the same time (by placing the OCR Profile and the IP Profile in a folder and exporting the folder).
FYI: The more intertwined the references between objects in a Project, the trickier it will be to do this. Especially if references to objects in external Projects are present, you may end up needing to export the entire Project (and any Projects it references).
Import Grooper Objects from a ZIP File
If you wish to follow along with this tutorial, you may import the ZIP archive files linked below into your Grooper Repository.
In previous versions of Grooper, you imported Grooper objects from one location, the Root Node of the Grooper Repository. Grooper would then place the imported assets in the Grooper Repository in a way that mirrored their location in the node tree they were exported from. In Grooper 2022, you will choose where you want the imported objects to land by importing to a node location of your choosing.
Importing Batches
You can only import Batches to a folder location that can house Batches. Batches can be either imported to the Batches > Production folder node, the Batches > Test, folder node, or any of their child folders.
To import a Batch right-click the folder node you want to import to.
In this case, we will import to the Test folder.
Select Share.
Then, select Import ZIP Archive...
This brings up the Share • Import ZIP Archive window.
Use the Filename property to enter the ZIP's file path or browse to the file.
Press Execute to import.
If successful, you will receive the following message.
Press OK to continue.
Your Batch will be added to the folder location you originally right-clicked to start the import.
FYI
A folder containing multiple Batches in a ZIP file may be imported as well, just like we did a single Batch.
Importing Projects
Importing Projects is much the same as importing Batches. The only difference is at what node in the node tree you can import them.
You can only import Projects to a folder location that can house Projects. Projects can be only be imported to the Projects folder node or any of its child folders.
Otherwise, the process is identical.
To import a Project right-click the folder node you want to import to.
In this case, we will import to the Projects folder.
Select Share.
Then, select Import ZIP Archive...
This brings up the Share • Import ZIP Archive window.
Use the Filename property to enter the ZIP's file path or browse to the file.
Press Execute to import.
If successful, you will receive the following message.
Press OK to continue.
Your Project will be added to the folder location you originally right-clicked to start the import.
FYI
A folder containing multiple Projects in a ZIP file may be imported as well, just like we did a single Project.
Importing Objects in a Project
You can also import a variety of other Grooper objects, including Content Models, profiles (such as OCR Profiles), and extractors (such as Data Types). If it can live in a Project, you can import it to a Project or a subfolder within a Project.
We will demonstrate this by showing you how to import a Content Model.
Right-click the Project (or Project subfolder) you want to import the object to.
In this case, we will import a Content Model in the ZIP file to the "Human Resources" Project.
Select Share.
Then, select Import ZIP Archive...
This brings up the Share • Import ZIP Archive window.
Use the Filename property to enter the ZIP's file path or browse to the file.
Press Execute to import.
If successful, you will receive the following message.
Press OK to continue.
Your imported Grooper object will be added to the Project you originally right-clicked to start the import.
FYI
A folder containing multiple Projects in a ZIP file may be imported as well, just like we did a single Project.
Common Issues
Issue #1: Importing Objects That Already Exist
If you try to import an object that is already present in your Grooper Repository, Grooper will not let you.
If the GUIDs of the items match, you will be presented with the following error:
<Object Name> already exists elsewhere in the repository
Issue #2: Importing Objects To the Wrong Location
Remember, you can only import objects to a node location designed to hold that type of object.
For example, Batches to a folder location designed to hold Batches. If you try and import the ZIP to a node location that can't hold Batches you will be given an error message.
Here we tried to import a Batch to a Project node.
Grooper gives us an error message.
<Object Name> does not allow children of <Object Type>
This tells us that the source location we tried to import cannot accept the object we're trying to import.
In this case, a Project can't accept a Batch. Batches don't go in Projects. They go in the Batches > Production or Batches > Test folders.
Issue #3: Importing Objects With Missing References
This issue can happen when objects were exported incorrectly from Grooper in the first place. When importing Grooper objects that reference other Grooper objects, both objects must be imported together. If the referenced object is missing, Grooper will give you an error.
For example, this Project makes a reference to another Project.
In this case, the Project making the reference is named "ACE Training".
The referenced Projectshould also be exported.
In this case, the referenced Project is named "Connection".
But what happens if we don't export both Projects and instead only export the Project making the reference?
Grooper will not let you import the object and give you an error message instead.
This message lets you know the inbound node (our "ACE Training" Project) contains references to external nodes (our "Connections" Project) that do not exist in the repository.
Essentially, the "ACE Training" Project is making a reference to something that doesn't exist, either in the ZIP file or the target Grooper Repository.
