2023:Download or Upload Grooper Nodes

WIP	This article is a work-in-progress or created as a placeholder for testing purposes. This article is subject to change and/or expansion. It may be incomplete, inaccurate, or stop abruptly. This tag will be removed upon draft completion.

How can you share Grooper objects, like Content Models, Batch Processes, Batches and more, with other Grooper users and environments?

Download them from one Grooper Repository and upload them to another!

About

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. This will be covered in the #Publish Projects to a Connected Repository section of this article.

WIP

EDITORS NOTE: All content below this point was taken from the Import or Export Grooper Objects - 2022 article. Largely, the guidance is the same, with some UI differences. In the 2022 thick client, "export" corresponds to "download" in the 2023 web client. In the 2022 thick client, "import" corresponds to "upload" in the 2023 web client. This article is under construction and will be updated using 2023 terminology and screenshots.

How To

Download Grooper Objects to a ZIP File

Downloading Batches

One or more Batches can be downloaded from a Grooper Repository.

• Both "Production" and "Test" Batches can be downloaded.
  • "Production" Batches are downloaded from the "Batches > Production" folder or one of its subfolders in the Node Tree.
  • "Test" Batches are downloaded from the "Batches > Test" folder or one of its subfolders in the Node Tree.
• To download multiple Batches, they must be placed in the same folder first. See the "Downloading Multiple Batches" tab below for more information.

Downloading Single BatchesDownloading Multiple Batches

Downloading Single Batches

Select the Batch 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 Batch to your browser's download location. The downloaded file will be a ZIP file, whose name will be whatever the selected Batch's name is.

Downloading Multiple Batches

What if you want to download more than one Batch?

To download multiple Batches, first put all the Batches 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 Batches you want to download to a subfolder in the "Production" or "Test" folder: Select the folder. The selected folder, including all its contents will be downloaded to the ZIP file. In this case, these two Batches. 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 Batches 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.

|}

Downloading Projects

You can also download full Projects as ZIP files.

• 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 ReferencesDownloading Single ProjectsDownloading Multiple Projects

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 Project and 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 other Projects.
• 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 both Projects 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's Referenced 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's Referenced Projects property.

Downloading Single Projects

We'll start with the simpler situation, exporting a Project that has no Referenced 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's Data 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

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).

Click here to return to the top

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.

• Media:Sample Batch - v2022.zip
• Media:Sample Project - v2022.zip
• Media:Sample Content Model - v2022.zip

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 BatchesImporting ProjectsImporting Objects in a ProjectCommon Issues

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 resources, including Content Models, profiles (such as OCR Profiles), extractors (such as Data Types) or other Grooper objects. 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 resource objects in a ZIP file may be imported as well, just like we did a single object.

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 Project should 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.

Click here to return to the top

Publish Projects to a Connected Repository

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 one Project at a time. This means if you are attempting to publish a Project that references another Project, you will need to publish the referenced Project first.

⚠

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.