2.90:CMIS Lookup (Lookup Specification): Difference between revisions

Revision as of 16:11, 23 April 2020

Performing data lookups on CMIS sources like SharePoint can be a powerful data integration tool.

A base Content Model for use with this article 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

About

Grooper uses the CMIS protocol to connect to a variety of Content Management Systems. This connection can be used to integrate data in powerful ways by allowing the collection of one (or sometimes many) fields of information within a model in Grooper (let's call it Field A), then leveraging that extracted data point against the column of like information in the Content Management system (called Column A) to then pass back other desired fields from other columns in the same row of information.

How To

The most basic thing to understand about performing a lookup in Grooper is what the "lookup field" is and what the "target field(s)" is(are). The lookup field is the trigger, and the target fields are the result.
Put another way, the 'lookup field is what will be populated with information from an Activity like Extract (a user could also manually enter data into the field). This field will then be "bounced" off of the source of data to supply the remaining fileds, or the target fields, with information

Understanding the SourceUnderstanding the Content ModelConfiguring a CMIS Connection

Understanding the Source

Perhaps the most challenging aspect of explaining how to leverage this functionality is the fact that it requires access to a SharePoint document library. 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 a SharePoint document library, as that's an exhaustive topic on its own. Note that CMIS Lookups are not limited to SharePoint, that just happened to be the content system chosen for this article.
Given that it will be assumed you have access to a source that Grooper can connect to via a CMIS Connection.

The below image is showing a SharePoint document library with a single document in it and several columns added and populated with information.

Understanding the Content Model

The Content Model used here is very simple. It has no Content Types or any extraction setup. It simply has a Data Model with several fields. None of that is necessary to setup and demonstrate the lookup.

Configuring a CMIS Connection

This configuration is specific to this article. While aspects of it can apply to any configuration, it's worth noting that this is not THE way to configure a CMIS Connection. This will be configured for a SharePoint environment. 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 SharePoint environment on your end to be established, and real URLs from it supplied.

Expand the node tree to the Infrastructure folder and in the CMIS Connections folder create a CMIS Connection object. Set the Connection Type property to SharePoint. Fill in the Base URL property with the URL for the SharePoint site you're wanting to connect to. You can be as granular with this as you want. What this means is you can set the URL to a specific site, and have the CMIS Connection object pertain to that specific site of the SharePoint environment (https://hydra.sharepoint.com/sites/ChiliConToso), or, you could set the URL to the base SharePoint URL and manage all sites from one CMIS Connection object (https://hydra.sharepoint.com).
The Authentication Method property can only be set to SharePoint OAuth when configuring a SharePoint connection. When you click the Authentication property the first time you're configuring a CMIS Connection object with the Connection Type property set to SharePoint you will get a window will pop up to allow the entering of credentials for your Office 365 account. To log out, click the ellipsis button on the property. Set the Enable Library Types property to True. There are two main Content Type objects within a CMIS Repository object: Document and Folder. These have sub-libraries withen them that have content specific to their type. Setting the Enable Library Types property to True will allow the creation of CMIS Content Type objects based on these sub-libraries. This must be done in order to connect to the specific library and have visibility to its writable properties.
With the previous settings saved, you can now click the List Repositories button. 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 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. 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.
Select the CMIS Repository ojbect. Expand the tree of the Document Content Type object within the Content Types view. These libraries, or sites, would not be available if the Enable Library Types property were not set to True. Select the Content Type object that relates to the library/site you want to connect to that has the writable properties you want, then use the Import Types drop-down menu and select Entire Branch. This will be different for your environment, but notice the Content Type Properties list view below. This lists the Writable Properties, like the ones highlighted, and also gives other important information about thier configuring like the data type of the columns. With desired Content Type imported, a new object representing it will exist in the node tree.	Writer's note - Having created this article and gone back through it, I now realize steps 10-13 here are not absolutely necessary to configure the CMIS Lookup. It will not impede one's ability to do so, and this is valuable information otherwise, as you can use the object created in these steps to map import and export properties for other activites. Feel free to not do steps 10-13.

@@ Line 21: / Line 21: @@
 Given that it will be assumed you have access to a source that '''Grooper''' can connect to via a '''[[CMIS Connection]]'''.<br/><br/>
 The below image is showing a SharePoint document library with a single document in it and several columns added and populated with information.
-[[File:cmis_lookup_001.png|1200px]]
+[[File:cmis_lookup_001.png|1550px]]
 </tab>
 <tab name="Understanding the Content Model" style="margin:25px">
@@ Line 33: / Line 33: @@
 <tab name="Configuring a CMIS Connection" style="margin:25px">
 ====Configuring a CMIS Connection====
+This configuration is specific to this article. While aspects of it can apply to any configuration, it's worth noting that this is not THE way to configure a '''[[CMIS Connection]]'''. This will be configured for a SharePoint environment. 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 SharePoint environment on your end to be established, and real URLs from it supplied.<br/>
 {| class="wikitable"
 | style="padding:25px; vertical-align:center" |
-# Click the '''Create Table''' button.
+# Expand the node tree to the '''[[Infrastructure Folder|Infrastructure]]''' folder and in the '''[[CMIS Connections Folder|CMIS Connections]]''' folder create a '''CMIS Connection''' object.
-# Click the '''''Content Type''''' property and click the drop-down arrow to get a mini node tree view.
+# Set the '''''Connection Type''''' property to ''SharePoint''.
-# Select the first '''Content Type'''.  In the case of this exmaple, it will be the '''Document Type''' named '''Database Export 01'''.
+# Fill in the '''''Base URL''''' property with the URL for the SharePoint site you're wanting to connect to.
+#* You can be as granular with this as you want. What this means is you can set the URL to a specific site, and have the '''CMIS Connection''' object pertain to that specific site of the SharePoint environment (https://hydra.sharepoint.com/sites/ChiliConToso), or, you could set the URL to the base SharePoint URL and manage all sites from one '''CMIS Connection''' object (https://hydra.sharepoint.com).
 || [[File:cmis_lookup_004a.png|1000px]]
 |-
 | style="padding:25px; vertical-align:center" |
-# <li value="4">Becaues the '''Database Export 01''' '''Content Type''' was selected, the following '''''Data Element Scope''''' property will have a drop down of which will contain '''Data Elements''' relative to this particular '''Content Type'''.</li>
+# <li value="4"> The '''''Authentication Method''''' property can only be set to SharePoint OAuth when configuring a SharePoint connection.</li>
-# Selecting the '''Earnings''' '''Data Table''' will set the baseline structure of the table to be created, and it will inherit upward.
+# When you click the '''''Authentication''''' property the first time you're configuring a '''CMIS Connection''' object with the '''''Connection Type''''' property set to ''SharePoint'' you will get a window will pop up to allow the entering of credentials for your [https://en.wikipedia.org/wiki/Office_365 Office 365] account.
-#* Think back to the notion of the one-to-many relationship. This table can have a dynamic number of rows and the '''Data Columns''' are capable of capturing and reporting back unlimited instances of data, hence multiple rows. The '''Data Fields''' within this scope, however, are only capable of capturing and returning a single piece of data. But, given the nature of inheretence, the table that will be created will make columns not just for the '''Data Columns''' of the '''Data Table''', but for each of the '''Data Fields''' contained within this scope.
+#* To log out, click the ellipsis button on the property.
-#* Were there '''Data Fields''' further up the inheretence tree, say at the base '''Data Model''' of the main '''Content Model''' the table would also attempt to inheret those as well.
+# Set the '''''Enable Library Types''''' property to ''True''.
+#* There are two main '''Content Type''' objects within a '''CMIS Repository''' object: '''Document''' and '''Folder'''. These have sub-libraries withen them that have content specific to their type. Setting the '''''Enable Library Types''''' property to ''True'' will allow the creation of '''CMIS Content Type''' objects based on these sub-libraries. This must be done in order to connect to the specific library and have visibility to its writable properties.
 || [[File:cmis_lookup_004b.png|1000px]]
 |-
 | style="padding:25px; vertical-align:center" |
-# <li value="6"> The '''''Table Name''''' property is arbitrary, but by default is a concatenation of the strings passed by the '''''Content Type''''' and '''''Data Element Scope''''' properties.M</li>
+# <li value="7"> With the previous settings saved, you can now click the '''List Repositories''' button.</li>
-# Click the '''Execute''' button to close this window and continue the process forward...
+# 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 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.
+# 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'''.
 || [[File:cmis_lookup_004c.png|1000px]]
 |-
 | style="padding:25px; vertical-align:center" |
-# <li value="8"> Here's where '''Grooper''' is doing the hard work for us. Notice in the '''Review/Edit SQL Statement''' window the SQL Statement required to create our table is already written for us.</li>
+# <li value="10"> Select the '''CMIS Repository''' ojbect.</li>
-# Click the '''Run SQL Statement''' button to create the table.
+# Expand the tree of the '''Document''' '''Content Type''' object within the '''Content Types''' view.
-|| [[File:cmis_lookup_004d.png|1000px]]
+#* These libraries, or sites, would not be available if the '''''Enable Library Types''''' property were not set to ''True''.
+# Select the '''Content Type''' object that relates to the library/site you want to connect to that has the writable properties you want, then use the '''Import Types''' drop-down menu and select '''Entire Branch'''.
+#* This will be different for your environment, but notice the '''Content Type Properties''' list view below. This lists the Writable Properties, like the ones highlighted, and also gives other important information about thier configuring like the data type of the columns.
+# With desired '''Content Type''' imported, a new object representing it will exist in the node tree.
+|| '''''Writer's note - Having created this article and gone back through it, I now realize steps 10-13 here are not absolutely necessary to configure the CMIS Lookup. It will not impede one's ability to do so, and this is valuable information otherwise, as you can use the object created in these steps to map import and export properties for other activites. Feel free to not do steps 10-13.'''''<br/>
+[[File:cmis_lookup_004d.png|1000px]]
 |}
 </tab>
 </tabs>