Box (CMIS Binding) - 2021

From Grooper Wiki
Jump to navigation Jump to search
This article was written for an older version of Grooper (v2.90). How you configure Export Mappings and the Export activity changed in version 2021. Please visit the Export (Activity) article for more up to date information.
Box cmis binding 000.png

Secure collaboration with anyone, anywhere, on any device, now connected to Grooper.

A completed Content Model and accompanying Batch used for this setup can be found here. It is not required to download to understand this article, but can be helpful because it can be used to follow along with the content of this article. This file was exported from and meant for use in Grooper 2.9


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

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.

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. These Client IDs are version specific.

Grooper 2.90: cvl1qcgv14wu2dsyji3evncrq0de5h3l
Grooper 2021: z9iyazstefwydilz4x3abdi3w79wogow


How To

Following is an example of how to configure a CMIS Connection object for Box and achieve an export of data.

Some of the tabs in this tutorial are longer than the others. Please scroll to the bottom of each step's tab before going to the step.

Understanding the Source

Perhaps the most challenging aspect of explaining how to leverage this functionality is the fact that it requires access to a Box environment. One was created for the sake of this article, but unfortunately cannot be shared externally. The scope of this article also does not allow explaining setting up Box, as that's an exhaustive topic on its own.

Given that, it will be assumed you have access to a Box environment that Grooper can connect to via a CMIS Connection.

The image on the right is showing the Metadata Template being used for this folder in this Box environment. As you can see it's very simple, just three fields of information.

Box cmis binding 003.png

Understanding the Content Model

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

  • Extraction is being accomplished via simple Data Types with their Collation property set to Key-Value Pair and the Horizontal Layout property set to Enabled.
  • It should be noted that the document in the accompanying Batch had its Document Type assigned manually. The Content Model is not performing any classification.
Box cmis binding 001.png

Index Data

Before the Document Export activity can send data, it must have data. 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 properly classified document (you can at the very least manually assign a Document Type) it creates Index Data and marries it to the document via a JSON file called Grooper.DocumentData.json. A couple of ways to verify its existence are as follows.

  1. First, navigate to the Document (or Folder) object in the node tree; not the Batch, not the Batch Folder, not the Page, but specifically the Document object. This is where the information lives.
  2. From there, click on the Index Data tab.
  3. After doing so you can see data displayed. Were the document classified, but not successfully extracted, the data structure would be present, but the fields empty.
Box cmis binding 006a.png

  1. Another means of verifying is to again, click on the Document object in the node tree.
  2. Click the Advanced tab.
  3. Click the Files tab.
  4. In the List View you should see the Grooper.DocumentData.json file.
  5. When you click on that file, you should see the stored JSON information of the indexed data displayed in the viewer below.
Box cmis binding 006b.png

Back to top to continue to next tab

Account ID

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

  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.
Box cmis binding 002.png

Configuring a Box CMIS Connection for Export

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.

  1. Expand the node tree to the Infrastructure folder and in the CMIS Connections folder create a CMIS Connection object.
  2. Set the Connection Type property to
  3. Set the Box User ID property to the Account ID you retrieved from you Box Account Settings.
  4. Set the Use Metadata property to True so Grooper can create CMIS Content Types from your Box Metadata Templates.
Box cmis binding 004a.png
  1. With the previous settings saved, you can now click the List Repositories button.
  2. Having clicked the previous button, there should be a repository (there may be multiple in your environment) in the Repository List view. Clicking on it ...
  3. ... will allow the Import Repository button to be clicked. This will change the red dot on the icon to green, meaning there's an active connection to this repository.
  4. It will also create several objects in the Grooper node tree: CMIS Repository ojbect, Content Types folder object, and two CMIS Content Type objects - Document and Folder.
Box cmis binding 004b.png
  1. Select the CMIS Repository ojbect.
  2. Expand the tree of the Document Content Type object within the Content Types view, and select the CMIS Content Type for the child object representing the Box Metadata Template you wish to connect to (it will have a red dot initially.)
    • These child CMIS Content Types, or Box Metadata Templates, would not be available if the Use Metadata property were not set to True.
    • This will be different for your environment, but notice the Content Type Properties list view below. This lists the Writable Properties and also gives other important information about thier configuring like the data type of the columns.
  3. With the desired Content Type imported, a new object representing it will exist in the node tree.
Box cmis binding 004c.png
  1. Select the newly created CMIS Content Type representing your chosen Box Metadata Template.
  2. Set the Export Enabled property to True.
  3. Select the Export Content Type property and click the drop-down arrow to get a mini node tree view, and select the Content Type that contains the scope of information you wish to export.
Box cmis binding 004d.png
  1. Select the Export Field Mappings property and click its ellipsis button. This will open a Field Mappings window.
    • The left column represents the columns of information in your Box Medatdata Template, the column on the right represents the Data Elements or expressions in Grooper you will map to those columns.
  2. For the Name column, I'm choosing to populate it with a simple expression that will pass the classified Document Type of the current folder.
    • The expression used is:
  3. For the remaining fields, simply select their corrensponding Data Fields from the model you're wishing to export from.
    • CMIS Content Type fields can be mapped to Grooper Data Fields. However, Data Fields that exist within Data Sections with the Scope property set to MultiInstance cannot be mapped.
    Note: Data contained in Data Tables and Data Sections with the Scope property set to MultiInstance can only be exported from Grooper using Database Export, or a custom activity.
Box cmis binding 004e.png
  1. The Name and Object Type ID fields are considered required by Box, and Grooper will pass an error if they're not mapped. I'm choosing to not map Object Type ID and deal with the error later.
  2. This is the error passed, but I will Save Anyway.
Box cmis binding 004f.png

Back to top to continue to next tab

Performing Mapped Export for Box CMIS Connection

The approach taken below is via the object command interface. These same settings can be applied to a Step in a Batch Process to achieve the same results, albeit in a slightly different area of the Grooper UI.

  1. Get to a Batch Viewer any way you feel comfortable, but here I selected the Batch from...
    Batch Processing > Batches > Test
  2. Click on the Batch Viewer tab.
  3. Right-click on the Batch Folder and use the Contents > Apply Activity... object command.
Box cmis binding 007a.png
  1. In the subsequent Contents • Apply Activity window, set the Activity Type to Document Export.
  2. Expand the Activity properties and set the Export Provider property to Mapped Export.
  3. Be sure the Scope and Folder Level properties are set according to your Batch structure.
  4. Select the Export Settings property and click the ellipsis button.
Box cmis binding 007b.png
  1. In the subsequent Mapped Export window, select the CMIS Repository property and in its drop-down menu, select the appropriate CMIS Repository object.
  2. Select the Target Folder property and in its pop-up window, select the folder in Box you wish to export to.
    • In Box files live in folders, and Metadata Templates are created and can be applied to any folder. In Grooper, the CMIS Content Type is configured for export against the appropriate Metadate Template, while export is executed against the actual Box folder.

The remaining properties are not critical to export, but worth discussing:

  • Update Link - If true, the Content Link on the document will be updated to point at the exported content.
  • Content Format - If set to Use Default, the Content Format specified on the CMIS Content Type will be used. If set to Custom, the settings specified here will override those specified on the CMIS Content Type.
  • Path Cloning - When enabled, export paths are calculated based on the item's original import path. When disabled, export paths are calculated according to the Folder Level Mappings defined on the CMIS Content Type object.
  • Ignore Unmapped Items - If true, the export process will ignore unmapped items. Otherwise, an error will be raised when an unmapped item is encountered. A Batch Folder object is considered unmapped if no Content Type is assigned, or if the assigned Content Type has no export mappings defined.
    • This is useful here because I chose not to map the Object Type ID.
  • Name Conflict Resolution - Indicates the action to be taken when a duplicate document is encountered during export. A duplicate document exists in the target repository if the mapped CMIS Content Type includes a writable Name property, and a document exists in the target folder with the same property value.
Box cmis binding 007c.png
  1. After clicking the OK button on the previous window, in the Process All window, set your desired Thread Count for this activity.
  2. Click the Start button.
Box cmis binding 007d.png
  1. In your Box environment, you can now select your newly exported file and see it has metadata populated from the extraction performed in Grooper.
Box cmis binding 007e.png

Version Differences

Prior to Grooper 2.9 the ability to connect to Box via CMIS Connection did not exist.