The "Download" and "Upload" buttons are found in the top right of the Design page.
The "Download" and "Upload" buttons allow users to export and import Grooper objects to Grooper Repository.
This gives you the capability to do two things:
You can save copies of Grooper assets for change management.
For example, you can save a copy of your Project by downloading it. Then, if you made changes that corrupted the Project, you could upload the copy, replacing the newer version with the older version.
You can share Grooper objects with other users.
For example, Grooper University users will download Projects to share with the Grooper Education team. The Grooper Education team then uploads the Projects in their own Grooper Repositories to review them and give feedback.
You may download the ZIP(s) below and upload it into your own Grooper environment (version 2023). The first contains one or more Batches of sample documents. The second contains a Project with resources used in examples throughout this article. The third contains a sample Content Model.
Grooper allows you to download Grooper objects from a Grooper Repository to a ZIP archive file. You can then bring in those objects into a Grooper Repository by uploading the ZIP file.
When download/upload Grooper objects, you can do one of three things.
You can:
Download/upload Batches
Download/upload full Projects
Download/upload Grooper objects inside a Project
The process is straightforward, but there are a few things to watch out for.
Most notably be aware of the following:
When downloading a Project, it is best practice to use the "Usage" tab to verify there are no broken references to objects in other Projects.
You may only upload Batches to the Batches > Test folder, the Batches > Production folder or one of their subfolders.
You may only upload Projects to the Projects folder or one of its subfolders.
For other Grooper objects downloaded from a Project, you may only upload them to a Project (or a valid location inside a Project).
When uploading Batches, Projects and other Grooper objects, if the item exists in the selected branch of the Node Tree, Grooper will overwrite the existing object.
For example, if you import a Project to a folder named "Grooper" and that folder already contains that Project (i.e. has the same GUID), that Project will be overwritten.
When uploading folders containing multiple Batches, Projects or other Grooper objects, if the folder exists in the selected branch of the Node Tree, Grooper will overwrite the existing folder and all its contents.
For example, if you import a folder named "Grooper" to the Projects node, and that folder already exists (i.e has the same GUID), that folder and everything inside it will be overwritten.
When uploading Batches, Projects and other Grooper objects, if an object in the ZIP already exists in the Grooper Repository at a different level, the upload will fail.
Grooper will check each node's GUID. If any GUID in the ZIP matches any GUID in the Grooper Repository, Grooper will throw an error.
When uploading a folder, Grooper will also check all objects inside the folder. If any of its contents exist in the Grooper Repository, the upload will fail.
FYI
Additionally you can "publish" full 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.
All the Project's contents will be exported as well.
To download multiple Projects, they must be placed in the same folder first. See the "Downloading Multiple Projects" tab below for more information.
Before Downloading: Check References
Generally speaking, a Project contains all the processing resources necessary to execute a Batch Process and process a particular document set. This may include:
A Content Model
A Batch Process
Other Grooper objects like OCR Profiles and IP Profiles
However, sometimes a Project will reference resources in other Projects using one or more Referenced Projects.
If you are downloading a Project ZIP so another Grooper user can upload it to their own environment, you will need to ensure both the Projectand any referenced Project will need to be downloaded together. This will ensure the user uploading the ZIP has all the resources necessary to upload the ZIP into their Grooper Repository.
For this reason, it is best practice to analyze your Project references prior to downloading to ensure you are not missing a referenced resource.
Use a Project's "Usage" tab to give you information about references to any object in otherProjects.
BE AWARE!! Uploading a ZIP will fail if an referenced object is not present in the destination Grooper Repository.
Example 1: A Project With No External Project References
In this example, we will use the "Usage" tab to verify a Project has no external references.
Select the Project.
Navigate to the "Usage" tab.
Nothing is listed in the "Outbound References" or "Inbound References"
This Project has no external references to objects in other Projects.
This Project is entirely "self-contained". All the necessary processing resources are contained in the Project itself. It is not dependent on any other Project to function.
In situations like this, you can download the Project without any worries whatsoever. Go to the "Downloading Single Projects" tab to see how to download this Project.
Example 2: A Project With External Project References
In this example, we will use the "Usage" tab to inspect a Project that does have external references.
Select the Project.
Navigate to the "Usage" tab.
Note there are items listed in the "Outbound References" and/or "Inbound References".
Here, something in the selected Project has an "outbound reference" to an OCR Profile in another Project.
"Outbound References" list any external objects in other Projects that are being referenced by internal objects in the selected Project.
"Inbound References" list any internal objects in the selected Project being referenced by external objects other Projects.
This Project is dependent on resources in another Project to work. In situations like this, you need to be aware if the destination Grooper Repository has all the resources it needs to upload the ZIP you download. This Project makes reference to a "Shared Resources" Project.
If the user does not have the "Shared Resources" Project in their Grooper Repository. You will need to download bothProjects to ensure the user has all the assets they need when uploading the ZIP file. Go to the "Downloading Multiple Projects" tab to see how to download multiple Projects.
⚠
Grooper will NOT alert you if a reference is missing when you download a Project (or any other Grooper object). It is up to you to ensure all referenced objects are included in the downloaded ZIP, if required.
Additional Tips and Best Practices
FYI
Use the "Usage" tab to track down references in your Project.
For "Outbound References":
The "TO" line will show you the object in an external Project that something within the selected Project is referencing.
Here we see the following reference path: Shared Resources > OCR Assets > Standard OCR
From right to left, the object being referenced is in a Project named "Shared Resources", in a folder named "OCR Assets", and finally the object being referenced is named "Standard OCR"
Expand a "TO" line to display the "FR" line. The "FR" line will show you the object within the selected Project that is referencing the "TO" object.
Here we see the following reference path: Invoices Process > Recognize
From right to left. the object making the reference is in a Batch Process named "Invoices Process" and finally referenced by the step named "Recognize".
Clicking any of these reference paths will take you directly to the object in the Grooper Node Tree.
We clicked the following reference path:
Shared Resources > OCR Assets > Standard OCR
This takes us directly to the referenced object.
In our case this is an OCR Profile named "Standard OCR"
Note the first item in the path is the Project containing the referenced object.
In our case the Project named "Shared Resources"
This can be a quick way to navigate to referenced objects and track down what Projects contain them.
⚠
BE AWARE!! Just because nothing is listed in a Project'sReferenced Projects does not mean there are no external references.
When a Project references objects in another Project it should list that external Project in the Referenced Projects property.
However, there are circumstances where Project references are inadvertently removed. This is NOT best practice, but it can happen.
Note here Referenced Projects lists (none).
We've manually removed the Project reference for the purposes of this demonstration.
Removing the Project reference DOES NOT remove the reference to the object in the external Project. However, Grooper will tell you something is wrong if you use the "Usage" tab.
Navigate to the "Usage" tab.
Notice there is a red warning sign next to our reference path in "Outbound References".
This lets us know the selected Project is missing a Project reference.
It is ALWAYS best practice to resolve this warning. If you see these missing Project references, please assign the reference using the Project'sReferenced Projects property.
Downloading Single Projects
Select the Project you want to download.
Press the "Download" button at the top right of the page.
This will bring up a window confirming you wish to download the selected object.
Press the OK button.
Grooper will download the Project to your browser's download location.
The downloaded file will be a ZIP file, whose name will be whatever the selected Project's name is.
Downloading Multiple Projects
What if you want to download more than one Project? For example, you may want to download multiple Projects if one Project references resources in another one.
To download multiple Projects, first put all the Projects you want to download in a folder. Then, select and download the folder.
When you export a folder to a ZIP file, all its contents are exported as well.
After moving the Projects you want to download to a subfolder in "Projects" folder:
Select the folder.
The selected folder, including all its contents will be downloaded to the ZIP file.
In this case, these two Projects.
Press the "Download" button at the top right of the page.
This will bring up a window confirming you wish to download the selected object.
Press the OK button.
Grooper will download the folder and its children (i.e. the multiple Projects inside it) to your browser's download location.
The downloaded file will be a ZIP file, whose name will be whatever the selected folder's name is.
You may also download individual objects within a Project.
For example, you may want to share a particular profile you've created with another Grooper user or repository.
For example, you may want to save a copy of your Content Model so that you can revert to a previous version if you plan on making changes to that Content Model.
Downloading Objects in a Project
To demonstrate downloading a single Grooper object, we're going to download the Content Model in our "Mortgage" Project.
Select the object you want to download.
Press the "Download" button.
This will bring up a window confirming you wish to download the selected object.
Press the OK button.
Grooper will download the object to your browser's download location.
The downloaded file will be a ZIP file, whose name will be whatever the selected object's name is.
⚠
BE AWARE!! When downloading objects in a Project, please be vigilant in order to maintain reference integrity.
If you wanted to download this OCR Profile, you couldn't only download this single object.
The OCR Profile references an IP Profile as part of its configuration.
Both objects would need to be downloaded at the same time.
You can download multiple objects by placing them in a folder and downloading the folder.
For information on how to download multiple objects, see the next tab, "Downloading Multiple Objects in a Project".
FYI: The more intertwined the references between objects in a Project (or Projects), the trickier it will be to do this. You may end up needing to download the entire Project (and even any Projects the Project references).
Downloading Multiple Objects in a Project
If you need to download multiple Grooper objects, you can put them in a folder and download the folder (just as we've seen with downloading multiple Batches and multiple Projects).
Select the folder you wish to download.
The selected folder, including all its contents will be downloaded to the ZIP file.
In this case, these various IP Profiles and OCR Profile.
Press the "Download" button at the top right of the page.
This will bring up a window confirming you wish to download the selected object.
Press the OK button.
Grooper will download the folder and its children (i.e. the multiple Grooper objects inside it) to your browser's download location.
The downloaded file will be a ZIP file, whose name will be whatever the selected folder's name is.
Press "Choose File" to choose a Grooper ZIP file to upload.
Use the file browser to select the ZIP you wish to upload.
Double-click the ZIP or press "Open" to continue.
⚠
Take care when selecting the ZIP file. Your upload will fail if:
The ZIP file is not a ZIP exported from Grooper.
The ZIP contains something besides a Project or a folder that contains Projects.
You will see the file you selected listed next to the "Choose File" button.
Press the "Upload" button to upload the ZIP.
If successful, you will receive the following message at the bottom of the webpage.
Your Project will be added to the folder location you originally right-clicked to start the import.
FYI
You can upload multiple Projects by uploading a ZIP of a folder containing more than one Projects.
ZIPs containing folders of multiple Projects are uploaded just like we did a single Project.
i.e. Select the node you want to upload to. Then, press the "Upload" button and select the Grooper ZIP. If it's a valid upload location, the folder will be uploaded, including all the Projects it contains.
Uploading Objects to a Project
You can also upload a variety of other Grooper resources to a Project. This includes:
Content Models
Profiles (such as OCR Profiles and IP Profiles)
Extractors (such as Data Types and Value Readers
Any other Grooper object that can live in a Project
If it can live in a Project, you can upload it to a Project or a subfolder within a Project.
⚠
You CANNOT upload ZIP files containing Batches or Projects to a Project.
If you attempt to upload Batches or Projects to a Project, your upload will fail.
⚠
BE AWARE!!
What happens if you upload a Grooper object that already exists somewhere in your Grooper Repository? One of two things will happen:
If the object exists at the same level in the Project you're uploading to, the node will be overwritten.
If the Project exists elsewhere in the node tree, at a different level, the upload will fail.
Remember, you can only import objects to a node location designed to hold that type of object.
A Grooper ZIP containing Batches (or a folder of multiple Batches) may only be uploaded to the following locations:
The Batches > Production folder node
Or one of its subfolders
The Batches > Test folder node
Or one of its subfolders
A Grooper ZIP containing Projects (or a folder of multiple Projects) may only me uploaded to the following locations:
The Projects folder node
Or one of its subfolders
A Grooper ZIP containing any other type of object may only be uploaded to:
A valid node location in a Project.
For example, you can't upload a Batch to a Project.
Here we tried to import a Batch to a Project node.
Grooper gives us an error message telling us the ZIP file cannot be imported.
The error message takes the following format:
'<Destination node's name>' does not allow children of type '<ZIP'd Object's type>'.
This tells us that the object we tried to upload cannot be uploaded to the node we've selected.
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.
Uploading Objects That Already Exist
The upload will behave differently depending on if the object exists at the same level of the branch you're uploading to or at a different level or in a different branch.
When uploading to the same level, Grooper will overwrite the existing node.
When uploading to a different level, the upload will fail.
Example #1: Uploading an Object that Exists in the Same Branch
Here, we will upload a Content Model that exists in the selected branch of the node tree.
In this case, the existing Content Model will be overwritten.
We're uploading the ZIP to this Project.
The ZIP contains this Content Model.
Since the Content Model exists in the selected branch, Grooper will upload the ZIP file, and the existing Content Model will be overwritten.
How does Grooper know the Content Models are the same? Their GUIDs. Each Grooper object has a unique GUID. If the GUIDs match, they are the same object.
⚠
BE AWARE!! When you upload in this manner, Grooper gives you NO warning you're about to overwrite an existing object. Be sure you want to overwrite the existing object with that in the ZIP file.
Example #2: Uploading an Object that Exists in a Different Branch
Here, we will upload an IP Profile that exists in a different branch.
If you try to upload an object that is already present in your Grooper Repository, AND it is in a different branch in the node tree, Grooper will not let you.
The upload will fail in this case.
We attempted to upload the ZIP to this Project
The ZIP contains this IP Profile.
The Project does contain the object we're trying to upload, BUT NOT AT THE SELECTED BRANCH. It exists in a different branch (in this case a subfolder).
After trying to upload we get an error message telling us the ZIP file cannot be imported.
The error message lets us know the object already exists and where in the node tree it's located.
'<ZIP'd Object's name>' already exists at '<Object's node tree location>'.
It doesn't matter where in the Grooper Repository the object is. It could be in a subfolder of the node you've selected. It could be in a different location altogether in the node tree hierarchy. If the object exists anywhere else besides the selected node's branch, the upload will fail.
How does Grooper know the object in the ZIP is the same as some other object? Their GUIDs. Each Grooper object has a unique GUID. If the GUIDs match, they are the same object (regardless where they are in the node tree).
Uploading Objects With Missing References
Grooper will let you download an object that references another object. This may be good or bad depending on what you want to do.
When this is good:
You're downloading the object so that you can re-import it later into your own Grooper Repository.
This won't be an issue because the referenced object already exists in your Grooper Repo.
Users typically do this for change management, so they have a version of something they can revert to by uploading the saved ZIP, overwriting the changed/corrupted object.
When this is bad:
You're downloading the object so that you can share it with another Grooper user.
This may be an issue because there's no guarantee the other Grooper user has that referenced object in their Grooper Repository.
If a user uploads a ZIP and does not have the referenced object in their Grooper Repository, the upload will fail.
For example, something in this "Invoices" Project makes a reference to something in another Project.
Remember, a Project's "Usage" tab will tell you which objects from external Projects are being referenced.
In this case, an OCR Profile in the "Shared Resources" Project is being referenced.
If you download this Project and another user attempts to upload it, they must have the referenced object in their Grooper Repository. Otherwise, the upload will fail.
Here, we attempted to import the "Invoices" Project.
Remember, something in this Project' references something in the "Shared Resources" Project.
For the purposes of this demo, I've deleted the "Shared Resources" Project. So, it doesn't exist in the Grooper Repository I'm trying to upload to.
This message lets you know the ZIP can't be imported.
The node we're trying to upload references items that do not exist in the repository.
The error message will also give you the GUIDs for each missing item.
Publish Projects to a Connected Repository
WIP
This article is a work-in-progress. This portion was copied from the 2022 version of this article. It's guidance is largely accurate. However, all screenshots were taken from the 2022 thick client.
If you're connected to multiple Grooper Repositories and need to get a Project from one Repository to another, there's no need to export a ZIP file from one Repository, then import the ZIP in another Repository. You can save yourself some steps by "publishing". This allows you to copy Projects and their contents from one Grooper Repository to another.
Publishing Projects is like exporting and importing all at once from one Grooper Repository to another. The same guidance detailed above when exporting and importing objects applies to publishing Projects as well.
The biggest difference is you can only publish full Projects, not Batches or individual objects contained within a Project.
You can also only publish oneProject at a time. This means if you are attempting to publish a Project that references another Project, you will need to publish the referenced Projectfirst.
⚠
Be aware "Publishing" is a essentially a "copy and paste" operation. The Project is "copied" from the source Grooper Repository and "pasted" to the destination Grooper Repository. You will need to ensure you have enough disk space to make the copy and paste. This means:
The user's file system publishing the Project must have enough diskspace the create a temp file for the "copied" Project.
The target Grooper Repository's file store must have enough diskspace for the "pasted" Project.
Aside from that, the process is straightforward.
Right-click the Project you want to publish.
Select Share.
Then, select Publish to Grooper Repository...
This will bring up the Share • Publish to Grooper Repository window.
Use the Target Repositories property to select the Repository (or Repositories) you wish to publish to.
Check the box next to the Repository you want to select.
We've selected a Grooper Repository we're connected to named "Grooper 2022"
Press the Execute button to publish.
If successfully published, a copy of the Project will be made in the target Grooper Repository or Repositories.
We published to the Grooper Repository named "Grooper 2022".
We can verify the published Project is now present.
