Box (CMIS Connection Type)

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 CMIS Connection Type that connects 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 2024). 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 referenced in this article. You will need your own Box account to fully configure these resources.

About

Integration with Box in Grooper leverages the CMIS+ architecture to allow you to take full advantage of this powerful Content Management System.

⚠

BE AWARE: Connecting to Box requires some setup in your Box account before configuring a CMIS Connection 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. This will be done in one of two ways depending on whether you are (1) entering an account ID entered into the CMIS Connection's Box User ID property or (2) entering a Box custom app's "App Settings" JSON entered into the CMIS Connection's Custom App Settings property Option 1: Connecting using a 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 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 Custom App Settings ("App Settings" JSON) This route is preferable for smaller Box accounts. Connecting with a Box account ID (Box User ID) will consume one of your Box user accounts. This can cause connection issues for organizations with the minimum of 3 user accounts in Box. Instead, these users should use the Custom App Settings method of connecting. This will not consume one of your user accounts. For more information on how to create a custom app in Box. Visit the articles below: https://developer.box.com/guides/applications/app-types/custom-apps/ https://developer.box.com/guides/mobile/ios/quick-start/configure-box-app/ After creating the 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.

How to

Understanding the Box platform

FYI	This article assumes you already have a Box account and can access it.

Understanding Box as a file system

It is important to understand Box is essentially a cloud-based file system. It is a storage repository consisting of files in folders.

Understanding Box as a data storage platform

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

Metadata Templates can be assigned to files or folders in Box.

• The image on the right is showing the Metadata Template assigned to a folder in this Box environment.
• Metadata Templates are added in Box by your Box Admin. Any number of custom metadata fields can be added to the template.
• This Metadata Template is very simple. It has just three fields ("ID", "First Name" and "Last Name")

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 for a document with a corresponding field in the Metadata Template on export.

To see how you would go about creating a "Mapped Export", click here: #Configuring a Mapped Box Export

Understanding the Content Model for Mapped Exports

The purpose of this Content Model is to simply extract three fields of information from a document in its accompanying Batch.

• These three fields in the Data Model ("ID", "First Name" and "Last Name") correspond to the three fields in the Box Metadata Template ("ID", "First Name" and "Last Name").
• When performing a Mapped Export, Grooper can not only export the document to a folder location in Box, but export the data it collects for these three fields to the Metadata Template Box attaches to the exported file.

To see how you would go about creating a "Mapped Export", click here: #Configuring a Mapped Box Export

Mapped Export Prereq: Extracted Data

Please note! Before the Document Export activity can send data, it must have data.

In a production scenario, this will be accomplished by the 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 document (i.e. the Batch Folder) object in the node tree.
   • Please note! You are not selecting the Batch, not the Batch's root folder, not one of the document's Page objects, but specifically the document's Batch Folder object. This is where the information lives.
2. Click on the Viewer tab.
3. Press the Review button.
   • This will bring up the document in a "Review" page.
4. Click the "Data Viewer" icon.
5. This will bring up the extracted data of the document.
   • If the fields have data present, the document has stored index data present.
   • If the fields are empty, run the Extract activity on the document to collect and store its index data.

How to create a Box CMIS Connection

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

Prereqs: Account ID from Box

In order to connect to Box in Grooper you’ll 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.

⚠

BE AWARE! There are actually two ways Grooper can connect to Box There are two ways a CMIS Connection can connect to Box. With an account ID entered into the Box User ID property (described in this article) With a Box custom app's "App Settings" JSON entered into the Custom App Settings property. The Custom App Settings route is preferable for smaller Box accounts. Connecting with a Box account ID (Box User ID) will consume one of your Box user accounts. This can cause connection issues for organizations with the minimum of 3 user accounts in Box. Instead, these users should use the Custom App Settings method of connecting. This will not consume one of your user accounts. For more information on how to create a custom app in Box. Visit the articles below: https://developer.box.com/guides/applications/app-types/custom-apps/ https://developer.box.com/guides/mobile/ios/quick-start/configure-box-app/ After creating the 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.

Create the Box CMIS Connection in Grooper

Click here for an interactive walkthrough

Create a CMIS Connection

1. Right-click a Project (or a folder in the Project).
2. Select Add, then CMIS Connection...
3. Name the CMIS Connection whatever you want.
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 tab ("Prereqs: Account ID From Box") in this article.
6. Once your ID has been entered, you will then choose your Metadata Format.
   • Bear in mind, 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.

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 repository. This will create a CMIS Repository object Grooper can use to navigate Box's folder and file structure. To do so:

7. Press the "List Repositories" button.
• "CMIS Repositories" and "CMIS Connections" are two different things in Grooper.

• If you think of Box and Grooper like two separate electrical poles, then the CMIS Connection is the wire that stretches between them. It is the intangible arm that reaches out from Grooper and grasps Box.
• The imported CMIS Repository on the other hand is the cache where our data is stored (the files and folders in Box).

8. Afterwards, he repository (or repositories) available for import will appear; select the repository you wish to import.
   • 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.
9. Press the "Import Repository" button to import the selected repository.
10. Ensure the listed repository is the one you wish import.
11. Press the "Execute" button.
12. This will create a CMIS Repository object for the selected repository.
13. Grooper will use this object when importing from or exporting to folder locations in Box.
    • The CMIS Connection only initiates the connection from Grooper to Box.
    • The CMIS Repository is an object that represents a specific folder in Box.
      • It is this repository object that allows Grooper to interoperate with the folder location in Box.

Import documents using Box

WIP	COMING SOON!!

Export documents using Box

Configuring a basic Box export

You can export processed documents from Grooper using a Box connection by configuring an Export Behavior.

• Export Behaviors are required to export all documents and data, regardless of what storage location they're going to.
• As a type of CMIS Connection, we will configure a CMIS Export when configuring the Export Behavior.
• These basic export steps detail simply how to get a document from Grooper to a folder location in Box.
  • However, these steps will apply to all Box exports, including Mapped Exports detailed below.

Add the Export Behavior and CMIS Export Definition

This configuration is specific to this article. While aspects of it can apply to any configuration, it's worth noting that your environment may require slightly different settings (especially considering proprietary pieces of information like the Account ID). Note that the URLs in the image cannot be connected to externally, so attempting to copy this configuration verbatim will give you errors. This is meant as a guide, and will require an actual Box environment on your end to be established, and real information from it supplied.

FYI

This article demonstrates how to configure an Export Behavior on a Content Model. Export Behaviors can be configured on any Content Type (Content Models, Content Categories or Document Types) or on the Export activity step itself. For more information on Export Behaviors visit the Export (Activity) article.

Click here for an interactive walkthrough

1. Select your Content Model.
2. Make sure you are on the "Content Model" tab
3. Select the ellipsis button to the right of the Behaviors property.
4. Select the "Add" button.
5. In the drop-down menu, select Export Behavior.
6. Select the ellipsis button to the right of the Export Definitions property.
7. Click the "Add" button.
8. Select CMIS Export.

Configure the CMIS Export Definition

After adding an Export Behavior you must configure CMIS Export.

• This is a crucial step, as you're essentially laying out the map in front of your Export Behavior, and telling it what you want exported, where you want the data saved, and what properties you want written to the exported object. In other words, you're circling the destination in the brightest red possible, while giving the Behavior everything it needs to take with it.

Click here for an interactive walkthrough

1. Click the hamburger symbol to the right of the CMIS Repository' property.
2. In the drop-down menu, select the CMIS Repository you wish to export to.
   • In our case, this is the "All Files" repository, representing the root folder of our Box account.
3. If you want export to a subfolder in the Box account, select the desired folder using the Target Folder property.

   • The Subfolder Path property allows you to dynamically create folder locations on export using a .NET code expression.

4. Pressing the ellipsis next to the Target Folder property will bring up a folder browser.
   • From here, you can select any folder in your Box account you want to export to.
5. Once you've selected the folder you want, click "OK".
6. Next, you will need to choose the Object Type you're exporting.
   • We're exporting documents (not folders) So, we've selected File'.
7. When finished, click "OK".
8. Save.

⚠

The Export Format property is extremely critical when exporting documents. This determines what kind of file Grooper creates and exports (e.g. a PDF or TXT or XML file). This property will be configurable once File is selected. For more information on Export Formats, visit the Export (Activity) article.

Configuring a "mapped" Box export

Mapped exports allow users to map data Grooper extracts to fields in a Box metadata template. Configuring a "mapped export" is part of configuring the CMIS Export'. Data can be mapped to a single metadata template or multiple metadata templates.

Mapping to a Single Metadata Template

Click here for an interactive walkthrough

1. Mapped exports are configured as part of your Export Behavior.
   • In this tutorial our Export Behavior is configured on our Content Model.
2. Select "Export Definition".
3. Under Object Data, select "Secondary Types."
   • While optional, choosing a Secondary Type tells Grooper which particular Metadata template you want it to point to.
     • A Metadata Template is how Box stores its information. It describes a set of key-value pairs that can be assigned to a file or folder.
4. Select your desired Secondary Type.
   • Since this example document is taken from the Grooper Wiki Metadata Template, we've chosen the Grooper Wiki Secondary Type. Yours will differ.
5. Once selected, click OK.
6. From here, select Write Mappings.
   • This is where you'll tell Grooper the exact information you want from your Metadata Template. Hence why selecting a Secondary Type was necessary.
7. You'll want to specify the output value for the CMIS Name property.
8. Select Expression.
9. Enter your expression in the dialogue box.
   • In this step, we're basically mapping our export to the name of the file we have in Box.
10. When finished, click OK.

    • Since the ID is specified as a Decimal format in Grooper, we've added the .ToString extension so it can be exported as text.
    • Descriptions and Tags can help you further refine your export mapping, but as they aren't necessary, we've left them alone.

Now, we move onto simple matching. For this, we're specifying which particular pieces of Metadata we're mapping to. Thus, it's important to match each piece exactly.

11. For our case, we need to match three things: ID, First Name, and Last Name. First, select Grooper Wiki ID.
12. Match it with the "ID" object from the drop-down menu.
13. Select Grooper Wiki First Name.
14. And match it with First_Name
15. Lastly, select Grooper Wiki Last Name.
16. Match it with the Last_Name item.
17. With everything matched, click OK.
18. In the Export Definitions window, click OK.
19. Save.

Mapping to multiple "metadata templates"

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

Much of the steps leading up to constructing your Export Behavior and Definition are the same up to this point. If you would like to see how to configure your Content Model for export, click here: #Configuring a Basic Box Export.

Click here for an interactive walkthrough

1. Select your Secondary Types
2. Click OK.
   • While the convention is the same, we've changed the Name property to avoid any confusion for Box when we export.
3. Similar to the preceding section, once your Name property has been set up, you'll begin matching the object in Write Mappings with the piece of Metadata you want to map to.
   • While there is more to match this time around, it's still the same process.
4. Once everything is matched, click OK.
   • Note that while our Repository and Target Folder appear the same as those of the earlier section, a different CMIS Repository was created. The document will still be exported to the same place in Box, however.
   • The obvious difference is in the Secondary Types and Write Mappings sections. Since we mapping to multiple Metadata types, we have two CMIS Type References and seven additional properties that are associated with the Grooper Wiki - Additional Info Secondary type.
5. Click OK.
6. Save.

Now, we have an exported file mapped to two Metadata Templates. Wonder why we didn't do anything with the tables? Unfortunately, Box cannot read tables, it can only read instances of single value. Hence, why we chose the data we did.

Testing the export and viewing the final results

Now that the Export Behavior(s) have been configured, it's time to export the document to Box.

• Normally, exporting is done in the Export step of a Batch Process.
  • The Export activity executes the Export Behaviors defined for the classified documents in a Batch.

• Outside of executing the whole Batch Process, when testing your Export Behaviors, you can do so in one of two ways:
  • You can export a single document by right-clicking it and applying the Export activity.
  • You can use an Export step's "Tester" tab to export one or multiple documents.

Testing by right-clicking a document

⚠	Note: If you haven't done so, classify the document and run the Extract activity before exporting.

First, you need to select the document in a "Batch Viewer". Any "Batch Viewer" will do. For example:

Click here for an interactive walkthrough

1. Select your Batch.
2. Go to the "Viewer" tab.
3. Apply the Export activity.
   • Right-click the document. Then, select Activities, then Document Processing, and finally, Export.
4. A window will pop up to configure the Export activity.
   • ONLY if you have NOT configured an Export Behavior already, configure the Export activity's Export Behavior .

   • Export Behaviors may be configured in one of two ways:
     • Using the the Behaviors settings of a Content Model and/or its Document Types and Content Categories
     • Locally to the Export step using its Export Behaviors property.
     • We consider it best practice to configure Export Behaviors on a Content Model and/or its Document Types and Content Categories. The ability to configure Export Behaviors on an Export step is largely present for upgrade compatibility for older versions of Grooper before Export Behaviors existed.
     • For more information, visit the Export article.

5. Press the "Execute" button.

From this point on, you will need to set up your Export Definition exactly as depicted above in the "Configuring a Mapped Export" Section. To see those steps, click here: #Configuring a Mapped Box Export

Once your document has been exported, you will see it displayed on the homepage of your Box account.

Selecting the newly imported document, you will be able to view the Metadata mapped to the document from Grooper.

FYI	Now that the document has been exported you may notice a link icon next to the attached file. 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.

Testing the export with the Export step tester

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
   • For the purposes of this article, we have simply made a Batch Process with a single step (which is an Export activity)
2. ONLY if you have NOT configured an Export Behavior already, configure the Export activity's Export Behavior .

   • Export Behaviors may be configured in one of two ways:

• Using the the Behaviors settings of a Content Model and/or its Document Types and Content Categories
• Locally to the Export step using its Export Behaviors property.

• We consider it best practice to configure Export Behaviors on a Content Model and/or its Document Types and Content Categories. The ability to configure Export Behaviors on an Export step is largely present for upgrade compatibility for older versions of Grooper before Export Behaviors existed.

• For more information, visit the Export article.

3. Navigate to the "Activity Tester" tab.

To test export for a single document:

1. Select a document in the Batch you wish to export.
2. Click the "Test Activity" button.
   • This will apply the selected Batch Process step to the selected document.
   • In our case, this will export the selected document to Box.

If you want to see what this would look like within a proper Batch Process, click the Submit Job button.

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

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)

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.