Box (CMIS Binding)

This article is about the current version of Grooper. Note that some content may still need to be updated.
2025	2023	2.90

Box is a connection option for cloud CMIS Connections. It Grooper to the Box content management system for import and export operations.

You may download the ZIP(s) below and upload it into your own Grooper environment (version 2025). The first contains one or more Projects with resources used in examples throughout this article. The second contains one or more Batches of sample documents. Media:2025 Wiki Box Projects.zip Media:2025 Wiki Box Batches.zip Please note the Projects ZIP does not contain the configured CMIS Connection or Export Behaviors that are referenced in this article. You will need your own Box account to fully configure these resources.

About

The "Box" binding gives Grooper access to files and folders in the Box content management platform. Box connections are how you import content from and export content to a Box account.

• You must have an enterprise Box account to connect to Grooper. Connection to personal accounts is not supported.

The Box binding can be selected as a connection option when configuring a CMIS Connection. After configuring the connection, Box folders are exposed to Grooper as a CMIS Repository. CMIS Repository nodes are created as children of the CMIS Connection by importing a reference to their source location.

The Box CMIS Repository mimics Box's file system hierarchy as well. Once a CMIS Repository is created, you can import, export, search, and browse documents from Grooper.

• The Box binding can be used for import operations via CMIS Import using "Import Descendants" or "Import Query Results".
• It can be used for export operations via CMIS Export.
  • Box can be used for simpler "unmapped" exports, if you just want to export Grooper documents as files to a folder in Box.
  • Box can also be used for "mapped" exports.
    • Box's "Metadata Templates" allow the platform to store additional document data as fields.
    • Extracted Data Field values in Grooper can be exported to fields in a Metadata Template along with the document's file.
    • In the CMIS Export setup, a Data Field in Grooper is mapped to a corresponding field in the Box Metadata template. When the document is exported the value is copied from Grooper and entered into the mapped field in Box.

Box account setup

BE AWARE: Connecting to Box requires some setup in your Box account before configuring a CMIS Connection

There are two ways a Grooper CMIS Connection can connect to a Box account.

1. With an account ID ("Box User ID").

   The Box account ID is entered into the "Box User ID" property in the Box Connection Settings.

2. With a JSON Web Token ("Custom App Settings").

   The custom app's App Settings JSON is entered into the "Custom App Settings" property in the Box Connection Settings.

Both of these options require some additional setup in Box. If you are integrating Box with Grooper for the first time, your Box administrator will need to add Grooper as a "Custom App" before connecting.

Option 1: Connecting using a Box account ID - Box User ID

Sceenshot of the "Add App" dialogue in the Box Admin Console

This is the easiest method for most users. It will add a Grooper app to your Box account. This app is pre-approved by Box, meaning you don't have to wait for Box to approve the custom app.

• Using the Box Admin Console, go to "Apps" then "Custom Apps" to add Grooper.
• As part of the setup, you will be prompted to enter a "Client ID", listed below:

  z9iyazstefwydilz4x3abdi3w79wogow

Option 2: Connecting using JWT - Custom App Settings

The "Custom App Settings" route is preferable for smaller Box accounts.

• Connecting with a Box account ID ("Box User ID" in Grooper) will consume one of your Box user accounts. This can cause connection issues for organizations using only the minimum of 3 user accounts in Box.
• Instead, these users should use the "Custom App Settings" method of connecting in Grooper. This will not consume one of your user accounts.

This will require you to create a custom "platform app" in Box.

• After creating the custom platform app, Box approves it, and you activate it, you will copy the "App Settings" JSON from Box into the Custom App Settings property in Grooper.
• For more information on how to create a custom platform app in Box. Visit the articles below:

  https://developer.box.com/guides/applications/app-types/platform-apps/

  https://developer.box.com/guides/authorization/custom-app-approval/

  https://developer.box.com/guides/authentication/jwt/

About the resources used in this article

This article assumes you already have a Box account and have completed any required setup in Box to integrate with Grooper.

Understanding Box as a file system

At its core, Box is a cloud-based file system.

• It is a storage repository consisting of files in folders.
• Files and folders are accessed from the web app at box.com.
• Box is a cloud native platform. There is no on-premise version of Box.

Understanding Box as a data storage platform

As well as a basic file system, Box can store data in fields using "Metadata Templates".

Metadata Templates are assigned to files or folders in Box.

• Metadata Templates are added in Box by your Box Admin.
• The Metadata Template in this image is very simple. It has just three fields ("ID", "First Name" and "Last Name").
• Any number of custom metadata fields can be added to a Metadata Template.
• Multiple Metadata templates may also be applied to a single file and/or folder.

With a Metadata Template attached to a file or folder, values for each field can be saved in Box. With a "mapped export", you can marry data Grooper collects in a document's Data Model with a corresponding field in the Metadata Template with an Export activity.

More information on creating a "mapped export" can be found in the Configuring a "mapped" Box export section of this article.

Understanding Grooper for Mapped Exports

When setting up a CMIS Export, you can define "Write Mappings" to platforms like Box that have custom metadata fields for their files. Configuring a "Write Mapping" will map the value of a Data Field for the document in Grooper to a field in a Box Metadata template. When the Export activity runs, the document and the data are exported. A file is created in Box and the Data Field's value is mapped to the field in its Metadata Template in Box.

We call this kind of export a "mapped export" in Grooper (as opposed to an "unmapped export" that exports the document only).

This is an example Content Model we're going to use to show you the basics of mapped exports in Box.

The purpose of this Content Model (and its Data Model) is to extract three Data Fields from a document in Grooper. Once those fields are extracted in Grooper, they can be mapped to fields in Box on Export.

• The three fields in the Data Model are: "ID" "First Name" and "Last Name"
• They correspond to the three fields in the Box Metadata Template: "ID" "First Name" and "Last Name").
• On executing the Export activity, Grooper will both export the document to a folder location in Box and export the data it collects to the Metadata Template Box attaches to the exported file.

More information on creating a "mapped export" can be found in the Configuring a "mapped" Box export section of this article.

Mapped Export Prereq: Extracted Data

Please note! Before the Export activity can send data, it must have data to send! In other words, the Extract activity must collect data first.

• In a production scenario, this will be accomplished by an Extract step of a Batch Process.
• However, take care when you're testing your configuration to ensure documents have extracted data before exporting to Box.
  • It's easy to get in the habit of testing extraction on a Data Field or a Data Model and feel good about the results, but it must be understood that the information displayed when doing so is in memory, or temporary.
  • When the Extract activity is successfully run against a classified document, it creates "index data" and marries it to the document via a JSON file called Grooper.DocumentData.json.

You can verify a document has extracted data follows:

Click here for an interactive walkthrough

1. Navigate to the Batch in the node tree.
2. Click on the Viewer tab.
3. Press the Review button.
   • This will open the Batch in a "Review" page with three default Review Views: a Folder Viewer, a Data Viewer, and a Thumbnail Viewer.
4. Select "Data View" to open the Data Viewer.
5. The Data Viewer has two panels: the Data Grid and the Document Viewer
   • The Data Grid shows the fields, sections and tables in a document's Data Model.
   • The Document Viewer displays the document (including all available renditions such as the "Text Rendition" that shows OCR'd or extract text from the Recognize activity).
6. If the fields in the Data Grid have data present, data has been extracted and saved to the document.
7. If the fields are empty, run the Extract activity on the document to collect and store its index data.

   • You can run the Extract activity from the Data Grid (unless that permission has been restricted by your administrator).

Creating a Box CMIS Connection

Creating and configuring a CMIS Connection is the first step to importing and exporting with Box.

BE AWARE! There are actually two ways Grooper can connect to Box. We only describe one in this article.

There are two ways a CMIS Connection can connect to Box.

1. With an account ID ("Box User ID").
   • This is entered into the "Box User ID'" property in the Box Connection Settings.
   • This is the route described in this article.
2. With a JSON Web Token ("Custom App Settings").
   • This requires your organization to create a custom "platform app" in Box.
   • The custom app's App Settings JSON is entered into the "Custom App Settings" property in the Box Connection Settings.

Both of these methods require setup in your Box account (performed by your Box administrator). See above for more information

We will detail the simpler method in this article: Using an account ID from Box and the "Box User ID" property in the Box Connection Settings.

Prereqs: Account ID from Box

In order to connect to Box in Grooper you will need and enterprise account and what Box refers to as an Account ID.

Click here for an interactive walkthrough

1. When logged into Box, click the icon for your account to expose a drop-down menu.
2. Click on Account Settings.
3. Scroll to the bottom of this page and take note of the Account ID.

Create the Box CMIS Connection in Grooper

Click here for an interactive walkthrough

Create a CMIS Connection

1. Right-click a Project in the node tree (or a folder in the Project.
2. Select "Add", then "CMIS Connection..."
3. Enter a name for the CMIS Connection.
4. Select "Execute".

Configure the CMIS Connection for Box

Once your CMIS Connection has been created, set your "Connection Settings" to Box. This defines settings for Grooper to connect to Box.

5. Select "Box User ID" and enter your Box Account ID.
   • If you are unsure of where to find your Box Account ID, please see the previous section (#Prereqs: Account ID From Box).
6. If needed, you can edit the "Metadata Format" property. This defaults to "Normal" which is appropriate for most users.
   • If you want to perform a "mapped export", your Metadata Format will need to be "Normal".
   • For more information on mapped exports, see the Configuring a "mapped" Box export section of this article.
7. Save the CMIS Connection.

Import Your Box Repository

Having saved your connection settings, Grooper has established a connection to your Box account, and you can now import the Box storage location into Grooper. This will create a CMIS Repository node Grooper can use to navigate Box's folder and file structure. To do so:

8. Select the CMIS Connection and press the "List Repositories" button.
   • "CMIS Repositories" and "CMIS Connections" are two different things in Grooper.

   • CMIS Connections only connect Grooper to Box.
   • CMIS Repositories represent the files and folders in Box.

9. The "List Repositories" button lists available CMIS Repositories that can be imported into Grooper. Select the CMIS Repository you wish to import. For Box, you should only ever see one repository: "All Files"
   • At this time, the value under "Imported" will be "False", and the dot next to it will be red. Once imported, this value will change to "True", and the dot will turn green.
10. Press the "Import Repository" button to import the storage location into Grooper.
11. In the pop-up window, ensure the listed repository is the one you wish import, and press the "Execute" button.
12. This will add a CMIS Repository node to the CMIS Connection (as its child).
13. Grooper will use this CMIS Repository node when importing files from or exporting Grooper documents to folder locations in Box.
    • The CMIS Connection only initiates the connection from Grooper to Box.
    • The CMIS Repository is a node that represents a specific folder in Box. This node allows Grooper to interoperate with the folder location in Box.

Import documents using Box

WIP	IN PROGRESS!!

Setting up an Import Behavior on the Content Model

Click here for an interactive walkthrough

1. Select the Content Type Node Object where you will configure the Import Behavior.
2. Select the Behaviors property and click ... to open the Behaviors Editor window.
3. Click the Add button within the Behaviors Editor window.
4. Select Import Behavior from the dropdown list.
5. Open the Import Definitions Editor Window by clicking ... .
6. Click the Add button within the Import Definitions Editor window.
7. Select CMIS Import.

   • You can have more than one Import Definition set up on an Import Behavior

8. Click the "☰" button to access the dropdown list for the CMIS Repository property and choose an imported Repository from which Grooper can map data.
9. Click the "☰" button on the CMIS Content Type Property and choose between "Folder" or "File."
10. Configure the Secondary Types, Read Mappings, and/or Write Mappings properties if necessary.
11. When finished, click OK on the Import Definitions window.
12. Click OK on the Behaviors Editor window.
13. Save all changes

Configuring an Import Job

1. Click the Imports icon.
2. On the Imports Page, click the Add New Jobs button to bring up the Import Jobs editor window.
3. Add a Description for the Import Job.
4. Select the Provider property and click "☰" to choose the Import Provider.
5. Select Import Query Results
   • Import Descendants is a valid option as well; it's just about how refined you want the import to be. Do you want everything from the entire Repository? Or do you want to import only certain Documents from within certain folders that match specific criteria?
6. Select the Repository property.
7. Click "☰" and go through the Node Type Objects within the dropdown list until you reach the Box Repository and select it.
8. Configure the CMIS Query by clicking "..." to bring up the editor window.
9. If you are processing a Batch upon importing, then configure the Batch Creation property; otherwise click Submit to submit the Import Job.
10. Grooper will display the Import Job in the list window, where you can monitor its status.
11. Once completed, you can view the imported Batch by going to the Design page and clicking Batches --> Test --> Imported Batches and selecting the newly imported Batch.
    • Grooper will organized imported Batches by the date and time the Import Job was submitted.
    • If you processed the Batch upon importing, it will be in the Productions Folder instead.

Export documents using Box

You can export processed documents from Grooper using a Box connection by configuring an "Export Behavior". Export Behaviors are required to tell the Export activity how to export Batch Folder content based on its Document Type. Because Grooper connects to Box using a CMIS Connection, we will configure a "CMIS Export" definition for the Export Behavior.

Configuring a basic ("unmapped") Box export

Box is in a special category of CMIS Bindings that allow you to perform a "mapped export". Mapped exports allow users to export data collected in Grooper to fields in Box (by "mapping" Grooper Data Fields to fields in a Box metadata template).

However, you can also perform a simpler "unmapped" export. This will simply export files to a folder for each Batch Folder exported.

• The steps required for unmapped exports will also apply to mapped exports.
  • Unmapped exports only export files (PDFs, TIFFs, CSVs, XMLs etc.).
  • Mapped exports export both files and map data to fields in the CMS platform.
• Mapped Box exports are detailed in the Configuring a "mapped" Box export section below.

Add the Export Behavior and CMIS Export Definition

To export documents using a Box connection, you need to configure an Export Behavior and add a CMIS Export definition.

• Export Behaviors can be added to any Grooper Content Type but are often added to Content Models.
• Adding an Export Behavior to a Content Model will apply the Export Behavior to any Document Type in the Content Model (as long as the Document Type doesn't have its own Export Behavior configured).
• Whenever the Export activity runs, Grooper will export a Batch Folder's document and/or data content according to the Export Behavior's configuration.

• More information on Export Behaviors and exporting in general can be found in the Export article.

Click here for an interactive walkthrough

To add an Export Behavior:

1. Select a Content Type (Content Model, Content Category or Document Type) in the node tree.

   • Content Types inherit Export Behaviors if they have none configured.
     • Ex: If you configure an Export Behavior for a Content Model, all Document Types will use those export settings (as long as they don't have their own Export Behaviors configured).
     • Ex: If a Content Type has an Export Behavior configured and a Document Type has an Export Behavior configured, the Document Type's Export Behavior will be used (not its parent Content Model's).

2. Open the "Behaviors" editor (Press the "..." button)..
3. In the Behaviors editor, press the "Add" button.
4. Select "Export Behavior" from the dropdown list.
5. With "Export Behavior" selected, open the "Export Definitions" editor (Press the "..." button).
6. In the Export Definitions editor, press the "Add" button.
7. Select "CMIS Export" from the dropdown list.
   • There are many different types of Export Definitions in Grooper. They all export Batch Folder document/data content to different platforms using different protocols. CMIS Export is the appropriate choice for Box exports. CMIS Export is used to export content to platforms using CMIS Repositories.

Configure the CMIS Export definition

After adding the CMIS Export definition, you must configure it!

• Adding an "Export Behavior" is just the first step.
  • When the Export activity runs, it looks at each Batch Folder. If the Batch Folder has a Document Type with an Export Behavior, it knows its going to Export it.
  • Besides that, an Export Behavior is really just a container for Export Definitions.
• The Export Definition is where the action is. Export Definitions define:
  • What Batch Folder content should be exported (the document's images, attached files, and/or data in its Data Model)
  • If a file is generated, what format that file should be (for example PDF or TIFF or CSV or several other format options)
  • Where the files and data are going (a CMS platform, a Windows file system, a database, etc.).
• CMIS Export is an Export Definition for content exported over a CMIS Connection to a CMIS Repository. In this case, to Box.

Click here for an interactive walkthrough

To configure an unmapped CMIS Export for Box:

1. Select the "CMIS Repository" property and click the hamburger icon.
2. Use the dropdown menu to select the CMIS Repository you wish to export to.
   • In our case, this is our Box CMIS Connection's only child CMIS Repository: "All Files". This represents the root folder of our Box account.
3. The "Target Folder" and "Subfolder Path" properties allow you to control what folder documents are exported to.
   • Target Folder: Use this property to select existing folders in Box. Press the ellipsis button to bring up a folder browser.
   • Subfolder Path: Use this property to dynamically traverse and create folder locations using code expressions. Press the ellipsis button to bring up a code editor.
4. Next, you must choose the "Object Type" you're exporting. "File" is the only option for Box.
5. Configure the "Export Formats" as needed.
   • This property will not appear until "File" is selected for "Object Type".
   • Export Formats define what file format (PDF, TIFF, TXT etc) is exported for each Batch Folder.
6. When finished, click "OK" to finalize the CMIS Export settings.
7. In the Behaviors editor, click "OK" to finalize the Export Behavior settings.
8. Save changes to the Content Model (or whichever Content Type you are configuring).

FYI

Files are named in CMIS Export by configuring a mapping expression for the "cmis:name" property (The display name for this is usually "Name"). If you do not edit the "Write Mappings", Grooper will name the file for you. If the Batch Folder has an attachment file, all exported files will be named after the attachment file. If the Batch Folder does not have an attachment file, all exported files will be named after the Batch Folder's display name.

More on Export Formats

Export Formats are critical to exporting documents. It determines what kind of file Grooper creates (PDF, TIFF, CSV, XML etc.) and what Batch Folder content is used to create that file (child Batch Page images, a file attached to the Batch Folder, or data collected from its Data Model).

There are too many Export Formats to detail fully in this article (You can visit the Export article for more information about Export Formats). However, there is one critical thing you should understand about Export Formats and CMIS Export.

One Export Format is added by default: "Attached File". With no further configuration, this will attach the Batch Folder's "main attachment file". Be aware of two common scenarios.

Common scenario 1: In Batch Processes where a Merge step runs before Export, this will export the file generated by Merge.

• This is typically ideal.
• In typical configurations, the Merge activity replaces the Batch Folder's "main attachment file" (if present) with the PDF or TIFF it generates. So, no further Export Format configuration is required to export a Grooper generated PDF or TIFF document.

Common scenario 2: In Batch Processes where a Batch is created by an Import Job and a Merge step is not present, this will export whatever file was imported at the start of the Batch Process.

• This is not always ideal.
• When an Import Job imports a file into Grooper, a Batch Folder is created and the file is attached to it. This is the Batch Folder's "main attachment file".
  • If you simply want to export the same file you imported to export location, no further Export Format configuration is required.
  • However, if you want to export a new file generated by Grooper you will need to (1) delete the Attached File format and (2) add one of your choosing (most typically a PDF Format).

Configuring a "mapped" Box export

Mapped exports allow users to map data Grooper extracts from Batch Folders to fields in a Box metadata template.

• Box's "metadata templates" allow the platform to store additional document data as fields.
• Extracted Data Field values in Grooper can be exported to fields in a metadata template along with the document's file.
• In the CMIS Export setup, a Data Field in Grooper is mapped to a corresponding field in the Box metadata template. When the document is exported the value is copied from Grooper and entered into the mapped field in Box.
• Data can be mapped to a single metadata template or multiple metadata templates.
• Only single instance data can be mapped. Only single instance Data Fields are mappable. Data Fields in multi-instance Data Sections cannot be mapped. Data Column values cannot be mapped.

Mapping to a single Box metadata template

This tutorial will show you how to set up "mapped export" for CMIS Export to a Box CMIS Repository. A single metadata template will be used in this scenario. Files and folders in Box can have multiple metadata templates assigned to them. However, they commonly will only have one.

• This tutorial assumes you've already added an Export Behavior to a Content Type (Content Model, Content Category or Document Type).
• This tutorial assumes you've already configured a CMIS Export definition for "unmapped" export.

Click here for an interactive walkthrough

Mapped exports are configured as part of your "CMIS Export" definition in an Export Behavior.

1. Open the "Behaviors" editor for the Content Type.
   • Export Behaviors are configured on Content Types (Content Models, Content Categories and Document Types).
   • In this tutorial our Export Behavior is configured on our Content Model.
2. With the Export Behavior added and selected, open the "Export Definitions" editor.
3. With the CMIS Export definition selected, open the "Secondary Types" editor.
   • Note: The "Secondary Types" property only appears for Box CMIS Repositories, after setting the "Object Type" property to "File".
   • "Secondary Types" for Box connections are metadata templates. Choosing a Secondary Type will add the selected metadata template to the file in Box
4. Use the Secondary Types editor to select the Box metadata template you want to assign to the exported documents.
5. Once selected, click OK.
6. Once you've selected a Secondary Type, open the "Write Mappings" editor.
7. The Write Mappings editor is a property grid used to map Box metadata fields to Grooper Data Fields or values calculated by code expressions.
   • Box properties and field names are on the left.
     • "Name", "Description", and "Tags" are editable properties for all Box files, even when you do not select a Box metadata template.
     • After these properties, metadata template fields are listed one-by-one in the following format: "Template Name • Field Name"
   • Values are mapped using each property's editor on the right.
8. There are two ways to map data from Grooper to a field or property in Box:
   • Selecting Data Fields from a dropdown list.
     • Press the hamburger button at the end of the Box property to expose the list of available Grooper Data Fields. Select the one you want to map to the Box property.
     • Make sure the Grooper Data Field's value type matches the Box field's value type. If the Box field is a string field, the Data Field needs to be a string field. If the Box field is a date field, the Data Field needs to be a DateTime field. And so on.
     • There's a shortcut if Grooper Data Field names match the field names in the metadata template. Right click anywhere in the grid to use the "Auto Map" command. This will automatically map fields if their names match (Otherwise you will need to configure each mapping individually).
   • Entering a code expression.
     • To enter an expression, expand the Box property in the Write Mappings property grid. Then, either enter the expression in the "Expression" property or open the "Expression" editor to enter the expression. Whatever the expression evaluates to will be what Grooper exports to Box.
     • Make sure the value type the expression evaluates to matches the field's value type in Box. If the Box field is a string field, the expression will need to evaluate to a string value. If the Box field is a date field, the expression will need to evaluate to a DateTime value. And so on.
     • It is common to use an expression for the "Name" field in Box. This will evaluate to the exported file's name.
9. After you've completed your Write Mappings, press "OK".
10. Press "OK" in the Export Definitions to finalize changes to CMIS Export.
11. Press "OK" in the Behaviors editor to finalize changes to the Export Definitions.
12. Press the "Save" button.

Mapping to multiple Box metadata templates

For this section, we've changed the original document, and are using a different Content Model.

Note: For this section, we've changed the original document, and are using a different Content Model that has more Data Fields.

While mapping to a single metadata template in Box is common, you can also add multiple metadata templates to a single file in Box. You will simply select multiple metadata templates in the Secondary Types editor. When you configure the Write Mappings, fields for both templates can be mapped to Grooper Data Fields.

• This tutorial assumes you've already added an Export Behavior to a Content Type (Content Model, Content Category or Document Type).
• This tutorial assumes you've already configured a CMIS Export definition for "unmapped" export.
• This tutorial assumes you're familiar with mapping to a single metadata template in Box.

Click here for an interactive walkthrough

Mapping to multiple metadata templates is not much different than mapping a single metadata template. You just need to select multiple Secondary Types and keep track of them when you're configuring the Write Mappings.

1. Select your CMIS Export configuration in your Export Behavior.
2. In the Secondary Types editor, select each metadata template you want to add to the exported document in Box.
   • Note: The "Secondary Types" property only appears for Box CMIS Repositories, after setting the "Object Type" property to "File".
3. Press "OK" when finished.
4. Open the "Write Mappings" editor.
5. Write Mappings for multiple Secondary Types (i.e. metadata templates) is done the same as when using a single one. Write Mappings are edited with a series of "Mapping Expressions" for each editable property in the CMIS Repository. Using either:
   • The property's dropdown menu.
   • The property's "Expression" editor.
6. Keep track of which metadata template you're mapping to by paying attention to the naming convention Grooper uses.
   • Box fields are always prefixed by their metadata template's name.
   • So, the property name in the Write Mapping is: "Template Name • Field Name"
7. Press "OK" when finished editing the Write Mappings.
8. Press "OK" in each editor window until you can save the node you're configuring.

Bonus: Testing the export

After configuring anything in Grooper, it's usually a good idea to test it out before you put it into production.

In production, Export Behaviors are executed by the Export step in a Batch Process.

But you don't have to put a document through an entire Batch Process to test it. You can test your Export Behavior (and its CMIS Export configuration) in two ways:

• "Click command testing" - You right-click a single document (Batch Folder) and apply the Export activity.
• "Step testing" - You can select an Export step in a Batch process and use the "Activity Tester" tab to export one or more documents.
• Be aware: In either case, the document must be classified and have data extracted before exporting.
  • It must be classified to export using its Document Type's Export Behavior.
  • It must have data extracted if performing a mapped export or the extracted data is used in the Subfolder Path expression.

Click command testing

You can right-click a Batch Folder and apply any Grooper Activity from any Batch Viewer. This includes the Export activity.

Click here for an interactive walkthrough

For example:

1. Select your Batch.
2. Go to the "Viewer" tab.
3. Apply the Export activity.
   • Right-click the document. Then, select "Run Activity", then "Document Processing", and then "Export".
4. A window will pop up to configure the "Export" activity.
   • As long as the Document Type assigned to the Batch Folder has an Export Behavior configured (or inherits one from a parent Content Type), no configuration is required. All export logic will be defined by the Document Type's Export Behavior.
   • While it is possible to configure Export Behaviors in the Export activity itself, we do not advise doing so. It is best practice to configure Export Behaviors on Content Types. The ability to configure Export Behaviors local to the Export activity exists for backwards compatibility. This is to ensure upgrade compatibility for older versions of Grooper where Export Behaviors did not exist.
5. Press the "Execute" button.

FYI

Now that the document has been exported you may notice a link icon next to the attached file (if one was not present before). This link indicates Grooper "knows" something about where this document is outside of Grooper. The document's exported file path location in Box is now stored in the document Batch Folder's properties.

Step testing

This section will detail texting export using an Export step's "Activity Tester".

Click here for an interactive walkthrough

1. Select the Export step of a Batch Process.
   • You will need to ensure the Batch Process Step's "Scope" is set to the appropriate level.

     Example: If the documents (Batch Folders) you want to export are at the root of your Batch, that's Folder level 1.

   • The Export activity itself should require no configuration.
     • As long as the Document Type assigned to the Batch Folder has an Export Behavior configured (or inherits one from a parent Content Type), no configuration is required. All export logic will be defined by the Document Type's Export Behavior.
     • While it is possible to configure Export Behaviors in the Export activity itself, we do not advise doing so. It is best practice to configure Export Behaviors on Content Types. The ability to configure Export Behaviors local to the Export activity exists for backwards compatibility. This is to ensure upgrade compatibility for older versions of Grooper where Export Behaviors did not exist.
2. Navigate to the "Activity Tester" tab.
3. Select a document (Batch Folder) in the Batch you wish to export.
4. Click the "Test Activity" button.
   • This will apply the selected Batch Process Step to the selected document.
   • In our case, an Export step. This will export the selected document to Box.

Testing with the "Test Activity" button is a "single-threaded" operation. Even if you select multiple documents, only a single processing thread will be used.

If you have a large number of documents you want to export, you can use the "Submit Job" button. Submit Job will submit all Export activity tasks to your running Activity Processing services for processing. The benefit to this is twofold:

• Processing jobs run "multi-threaded". It will use all processing cores the Activity Processing can use.
• Processing jobs run in the background allowing you to continue working in Design.

FYI

Now that the document has been exported you may notice a link icon next to the attached file (if one was not present before). This link indicates Grooper "knows" something about where this document is outside of Grooper. The document's exported file path location in Box is now stored in the document Batch Folder's properties.

The view from Box after Export

Once your document has been exported, you can log into your Box account to verify. Navigate to whatever folder you exported to.

• Remember, the folder pathing is determined by how you set up CMIS Export.
• In this case, a single document was exported to the root of the Box repository.

If you performed a "mapped export", you can see the results of your Write Mappings.

1. Open the exported document in Box.
2. Click on the "Metadata" icon.
3. In the Metadata panel, you can see the metadata template you selected in the CMIS Export's "Secondary Types" configuration.
4. The Grooper Data Field values are mapped to the metadata template's fields according to the CMIS Export's "Write Mappings" configuration.

Metadata Modes: Normal vs Strict vs Disabled

When configuring a Box CMIS Connection, you have three options for the "Metadata Mode". Depending on what you choose will enable a file's properties and/or fields from a metadata template.

• Normal - All properties and metadata fields are enabled.
• Strict - Only metadata fields are enabled.
• Disabled - Only properties are enabled.

What are properties vs metadata?

In this context, "properties" refer to a file's properties (like its file name or extension) and "metadata" refers to fields in a Box metadata template. Properties are local to the file itself. Metadata is information about the file stored in Box.

How are properties and metadata used in Grooper?

Queries and mappings.

Queries

When properties and metadata are enabled, you can search for them using CMIS Queries. If properties/metadata are disabled, they won't be usable in the queries WHERE clause.

This is important when:

• Using "Import Query Results" - The CMIS Query determines what gets imported. Properties and/or metadata can be used as conditions for import.
• Using the CMIS Repository's "Search" tab - This tab uses a CMIS Query to search for documents.
• Using "CMIS Lookup" - The lookup uses a CMIS Queries to lookup values.

Mappings

"Mappings" refers to "Read Mappings" and "Write Mappings". This is how Grooper interoperates with property and metadata values on import and export.

This is important when:

• Using "Import Behaviors" with "Read Mappings" - This allows you to copy property and field data from Box to Data Fields in the imported document's Data Model.
• Using "CMIS Export" with "Write Mappings" - This allows you to export Data Field values in the document's Data Model to properties and fields in Box.

What should I choose?

If you are unsure, choose "Normal".

This will give you full access to properties and metadata when configuring Import Query Results, CMIS Export or anything else in Grooper that accesses a Box CMIS Repository.

What are Box File properties that might be important?

Below is a table of common Box file properties that are accessible from Grooper. If they are "queryable", these properties can be used in a CMIS Query. If they are "writable" they can be written on Export using CMIS Export's Export Mappings.

Box File Properties
Display Name	CMIS Type Name	Description	Queryable?	Writable?
Name	cmis:name	The file's name.	Yes	Yes
Description	cmis:description	A description you can add for the file. This shows up in the "Details" panel in Box.	Yes	Yes
Tags	tags	This is a string array field. Tags in Box are used for quickly labeling files. Tags can be searched in the Box UI. If you want to add tags to a document exported to Box, you will need to edit this property's mapping expression in the CMIS Export Write Mappings.	No	Yes
Creation Date	cmis:creationDate	The date the file was created.	Yes	No
Last Modification Date	cmis:lastModificationDate	The last date the file was modified. FYI: Box supports "versioning" which allows multiple versions of a file to be saved to the same file location in Box.	Yes	No
Content Stream Length	cmis:contentStreamLength	This is functionally the file's size, in bytes.	Yes	No
Extension	extension	This is the file's extension (PDF, TIFF, TXT etc)	Yes	No

Known issues & limitations

File and folder limitations in Box

To mitigate problems when exporting to Box, users should be aware of the following limitations in Box:

• No single folder can contain more than 15,000 files. For the best performance, a single folder should have at most 10,000 files.
• Folder names should not be longer than 100 characters.
• File paths should not be longer than 255 characters.

Box CMISQL Query limitations

Search values are required for Box CMISQL Queries. You must include a WHERE clause with at least one valid search condition.

The Box API has some built in requirements to perform search queries. This is not something Grooper can get around. In the past, this has caused Grooper users a lot of confusion when configuring WHERE clauses in CMISQL search queries.

To avoid confusion the following properties are not queryable at this time:

• Created by (cmis:createdBy)
• Modified by (cmis:lastModifiedBy)

The Box binding does not support does not support the IN_FOLDER predicate.

• You must use the IN_TREE predicate instead when selecting a folder location to query.
• Be aware the IN_TREE search is recursive where IN_FOLDER is not. This means any subfolders will be queried as well as the targeted folder.

Box has some documented limitations in its CMIS implementation in general. In most cases, Grooper is able to circumvent these issues, but not in all cases. Grooper is only able to return what Box gives us when executing a CMISQL query.

• Documents are not immediately queryable after their metadata templates have been edited in Box. If you have just added/edited fields in a Box document's metadata template, there is some lag time between when Grooper can query that data. You may need to wait several hours before a CMISQL query will return the document.
• We have encountered sporadic issues when using aliases (i.e. SELECT propertyName AS 'AliasName') in a Box CMIS Lookup query. As such, CMIS Lookups used to populate Grooper fields may be unreliable. However, please continue to report this issue to the support team at support@bisok.com. Additional reports will help the QA team diagnose this issue and help the Development team implement a solution, if possible.

Upgrade issues

There is a known issue upgrading Box CMIS Repositories from 2.9 to 2021 and beyond. The way Import and Export Mappings are configured changed radically from version 2.9 to 2021. Further, the Box binding was dramatically improved in version 2021.

Due to this, you may experience issues with your Import or Export Mappings when upgrading to 2021 and beyond. You may need to manually reconfigure your Import or Export Mappings upon upgrading. If you are using a Box connection, please validate your mappings and test them upon upgrading to ensure they behave appropriately.