2023:Box (CMIS Binding)

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.

Basic one linter about what a Box connection is.

About

You may download and import the files below into your own Grooper environment (version 2023). The first contains a Project with several Content Models used as examples throughout this article. The second contains some example Batches of sample documents. Media:2023_Project_-_Wiki_-_Box (CMIS Binding).zip Media:2023_Batches_-_Wiki_-_Box (CMIS Binding).zip

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 Grooper 2022: z9iyazstefwydilz4x3abdi3w79wogow Grooper 2023: z9iyazstefwydilz4x3abdi3w79wogow

How To

Understanding Box For Mapped Export

Understanding Box As A File SystemUnderstanding Box As Data Storage PlatformUnderstanding the Content ModelExtracted Data

Understanding Box As A File System

This article assumes you already have a Box account and can access it. It is important to understand Box is essentially a cloud-based file folder system.

As well as a basic file system, Box can store data using Metadata Templates 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. 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

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

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

You can verify the extracted data's existence as follows:

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. From there, click on the Viewer tab. Once there, click the Review button. This will upon up the Reviewer tab.
Click the Data Viewer icon This will bring up the extracted data of the document.

Back to top to continue to next tab

How to Create a Box CMIS Connection

Prereqs: Account ID from BoxCreate Box CMIS Connection in Grooper

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. When logged into Box, click the icon for your account to expose a drop-down menu. Click on Account Settings. Scroll to the bottom of this page and take note of the Account ID.

Create Box CMIS Connection in Grooper

Right-click a Project (or a folder in the Project). Select Add, then CMIS Connection...
Name the CMIS Connection whatever you want. Select "Execute".
Once your CMIS Connection has been created, set your Connection Settings to Box. This defines settings for Grooper to connect to Box. You will then need to enter your Box Account ID. If you are unsure of where to find it, please see the Prereqs tab before this one. 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.
Having saved your settings, you can now import the repository. To do so: Click the "List Repositories" button. FYI Repositories and 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 Repository on the other hand is the cache where our data is stored.
The repository(ies) awaiting import will appear. At this time, the dot under imported will be red, and it will say "False" under Imported. Once "List Repositories" has been selected, you will then be able to click "Import Repository."
Select the repository you wish to import. Click Execute.
Now we have a CMIS Repository.

By now, you're wondering what does importing a repository have to do with connecting to Box? Why is this important? We need the repository because, later on, when we format our export mapping, we'll need to reference this repository. You can't tell Grooper which item will be exported, if you have no item to export.

Configuring a Basic Box Export

Add an Export BehaviorConfigure the Export Definition

Add an Export Behavior

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.

Select your Content Model. Make sure you are on the "Content Model" tab Select the ellipses to the right of "Behaviors".
Select the Add button. In the drop-down menu, select Export Behavior.
Click the ellipses to the right of "Export Definitions".
Click the Add button. Select "CMIS Export".

Configure the Export Definition

Now that you've set up your basic configuration, let's move on to configuring your Export Definition. This is a crucial step, as you're essentially laying out the map in front of your configured 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 the little hamburger-looking symbol to the right of "CMIS Repository". In the drop-down menu, navigate down to the file(s) you want to export in your repository.
If you want to change where the exported item(s) will be saved, select "Target Folder".
From here, you can select your desired Target File. Once chosen, click OK.
With your Target Folder selected, you will then need to choose the Object Type. Select "File". When finished, click OK. FYI Always check the Export Format to ensure that your are setting up the format as an attached file (this can be found under Object Data). For more information on Export Formats, see here: Export (Activity) - 2021
Save.

Back to top to continue to next tab

Configuring a Mapped Box Export

Mapping to a Single Metadata TemplateMapping to Multiple Metadata Templates

Mapping to a Single Metadata Template

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.

Remaining on the Content Model tab of the Content Model, select Behaviors once more.
Select "Export Definition".
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.
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. Once selected, click OK.
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.
You'll want to specify the output value for the CMIS Name property. Select Expression.
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. FYI Since the ID is specified as a Decimal format in Grooper, we've added the .ToString extension so it can be exported as text. When finished, click OK.
FYI 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. For our case, we need to match three things: ID, First Name, and Last Name. First, select Grooper Wiki ID. Match it with the "ID" object from the drop-down menu.
Select Grooper Wiki First Name. And match it with First_Name
Lastly, select Grooper Wiki Last Name. Match it with the Last_Name item. With everything matched, click OK.
In the Export Definitions window, click OK.
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. Select your Secondary Types Click OK.
While the convention is the same, we've changed the Name property to avoid any confusion for Box when we export.
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.
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.
Click OK.
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.

Final Results

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

Right-Click ExportPerforming the Export Within a Batch Step

Right-Click Export

Normally, exporting would be done through a Batch Process, since all an Export Behavior does is tell Grooper what do do when the process gets to the Export step. However, for the purposes of this article, we will demonstrate how exporting could be done through right-clicking the document.

Select your Batch. Go to the Viewer tab. Right-click the document. Select Activities, then Document Processing, and finally, Export.
In the window that pops up, select Export Behavior.
Add a Behavior. Select the Content Type. Select Export Definitions.
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.
Note that the document will now be linked to your Box account.

Performing the Export Within a Batch Step

We will now demonstrate a proxy version of the correct way exporting is performed, ie within a Batch Step process. How to set up a Batch Process will not be discussed here, as it's assumed the reader already knows how to do that. If you would like to know how to set up a Batch Process, click here: [[1]]. This section will display the creating the Export step and working in the Activity Tester of the Batch Process.

Right-click (or create) your Project. Select Add, followed by Batch Process
Name your Batch Process. Click Execute.
Select the drop-down menu for Content Type. Choose the Document Type.
With the Batch Process created, right click. Add a Batch Process Step.
Name the Step. Click Execute.
Select the Activity you wish to perform. In our case, this is the Export Activity. Select the Scope. For this instance, we can leave the scope at Folder. Once more, you'll need to define the Export Behavior. To see how to do that, click here: #Configuring a Mapped Box Export Once finished setting up the Behavior, click Save.
With everything set up in the Batch Process Step, navigate to the Activity Tester tab. Click the play button to execute the tester.