Integrating a New External DMS
This article outlines the steps to creating an integration for use in TeamConnect's DMS Connector Tool. It should be noted that the TeamConnect JavaDocs should be reviewed prior to setting up a custom integration outside of Mitratech’s out-of-the-box offering.
Set up your environment
- Use the same environment as you would for writing a custom java rule for teamconnect.
- Obtain enterprise-api.jar from WEB-INF/lib of relevant version of TeamConnect if you wish to use it in your development environment to see dependencies actively.
Writing .properties and .java files
- Determine necessary properties
SharePointOnlineIntegration.properties - determine information that you will need user input for. This may be server information and webservice authentication information. - Write Java
- A single class file is required for an integration. It must extend the abstract DmsAdapterDescription found in enterprise-api.
- Your class extending DmsAdapterDescription implements the webservice calls made out to the external DMS. TeamConnect comes out of the box with Spring's REST Template library for making REST calls. Other relevant libraries can be found in WEB-INF/lib in the TC .war file, such as jaxb. Classes available for your version of Java may help as well. Additional libraries needed may have to be added to the TeamConnect classpath.
- See abstract class below for documentation on what each single method does.
- Compile Java into a class file.
DmsAdapterDescription
package com.mitratech.teamconnect.enterprise.api.dms.adapter;
import com.mitratech.teamconnect.enterprise.api.custom.CustomItem;
import com.mitratech.teamconnect.enterprise.api.model.Document;
import com.mitratech.teamconnect.enterprise.api.model.DocumentSourceLocation;
import com.mitratech.teamconnect.enterprise.api.model.File;
import com.mitratech.teamconnect.enterprise.api.model.Folder;
import com.mitratech.teamconnect.enterprise.api.model.enums.DmsAdapterMetadata;
import com.mitratech.teamconnect.security.PublicAPI;
import java.util.List;
import java.util.Map;
/**
* Interface describing necessary functions for an integration with TeamConnect and an external DMS. Class
* extends CustomItem and therefore has access to the TC Platform
* {@link com.mitratech.teamconnect.enterprise.api.Platform}
*
* @author Luis Valerio
*
* @since 5.2
*/
@PublicAPI
public abstract class DmsAdapterDescription extends CustomItem
{
private DocumentSourceLocation dmsInformation;
/**
* Retrieve document content from an external DMS.
*
* @param document File with a corresponding document in the external DMS.
* @return byte array of document content
*/
public abstract byte[] readDocumentContent(Document document);
/**
* Get name of document as it is in the external DMS side. Used to check if document name is out of sync.
*
* @param document Document whose name is to be checked for synchronicity
* @return name of the document on the DMS side
*/
public abstract String getDocumentName(Document document);
/**
* Retrieves documents stored in the external DMS and returns a collection of metadata objects
* representing each of the retrieved documents. This list will be used to create new documents under an
* existing TeamConnect object. TeamConnect expects filenames to include the extension.<br>
* <br>
*
* Objects in this list do not need to be sorted, new, or validated in any way, as internal enterprise
* logic handles parent-child relational mapping, duplication detection, and simple document validation.
*
* For DmsExternalDocument objects of type FILE, search for multiple versions of the file as well and add
* them to that object's version list.
*
* @param attachmentFolder the top-level folder of an object record that has a corresponding entry in the
* external DMS
* @return metadata objects used to create documents under an object record
* @see {@link com.mitratech.teamconnect.enterprise.api.dms.adapter.DmsExternalDocument#DmsExternalDocument(String, char, String, String, int)}
*/
public abstract List<DmsExternalDocument> getDocumentsForAttachmentFolder(Folder attachmentFolder);
/**
* Upload a document and its content to an external DMS.
*
* @param document File to upload to DMS
* @param data byte array of document's content
* @return ID of successfully uploaded document
*/
public abstract String uploadDocument(File document, byte[] data);
/**
* Create a folder in the external DMS. If parents of given folder do not exists, method should also
* create all parents up to the equivalent of TeamConnect's "Attachments" folder.
*
* @param folder TeamConnect folder to create in DMS.
* @return ID of successfully created folder
*/
public abstract String createFolder(Folder folder);
/**
* Given the TeamConnect File object, delete the corresponding document on the external DMS side.
*
* @param document File with a corresponding document in the external DMS
*/
public abstract void deleteDocument(File document);
/**
* Update DMS side document with changes made in TeamConnect. At a minimum, there is an expectation that
* this method updates the name of the document with the new name provided by TeamConnect
*
* @param document to update
*/
public abstract void updateDocument(Document document);
/**
* Move document to the specified new location.
*
* @param document the document to move. Can use getFolder() if current location is needed.
* @param folder the target folder to move the document.
* @return the unique ID of the file that was moved.
*/
public abstract String moveDocument(Document document, Folder folder);
/**
* Copy a document to the specified location.
*
* @param docToCopy Original document
*
* @param folder folder location to place the docToCopy
* @return unique Id of the new document copy
*/
public abstract String copyDocument(File docToCopy, Folder folder);
/**
* Check in document to the external DMS given input from a TeamConnect user.
*
* @param document File with corresponding document on the DMS side.
* @param data byte array of new content. If DMS has no concept of record locking or checking in, then do
* a straight update of the content
*
* @return unique Id of the new version of the document.
*/
public abstract DmsExternalDocument checkInDocument(File document, byte[] data);
/**
* Check out document from external DMS. Set document status to "checked out" or "locked" on DMS side if
* applicable. If not, method can be left left stubbed. Content is retrieved separately.
*
* @param document File to check out.
*/
public abstract void checkOutDocument(File document);
/**
* Verify connection with DMS. A thorough test will verify access to the external DMS as well as the
* expected "folder" or "repository" for storing documents.
*/
public abstract void testConnection();
/**
* Update the document's metadata on the external DMS. This is useful for when document actions made via
* calls to the external DMS do not automatically update the metadata in an intuitive way to the user, and
* a subsequent call (or calls) to the external DMS is/are needed. Otherwise, this call can be stubbed.
*
* @param document the document whose metadata is to be updated on the external DMS
* @param metadataMap the map containing a metadata flag used to indicate the desired metadata field to
* update and a corresponding string used to populate the metadata field
*/
public abstract void updateMetadata(Document document, Map<DmsAdapterMetadata, String> metadataMap);
/**
* Implementation should at minimum content search. Can take advantage of advanced features if given DMS
* supports, such as wildcards.
*
* To speed up search as well as processing in TeamConnect, narrow the scope of search to only return IDs
* that are relevant to TeamConnect and skip any internal only areas of the DMS.
*
*
* @param queryString user input search string from Global Search
* @return list of unique identifiers of documents with results
*/
public abstract List<String> search(String queryString);
public DocumentSourceLocation getDmsInformation() {
return dmsInformation;
}
public void setDmsInformation(DocumentSourceLocation dmsInformation) {
this.dmsInformation = dmsInformation;
}
}
Preparing your TeamConnect instance
- If you are using a version of TeamConnect that allows DMS integration (5.2 or later), find the "Integrations" folder located in Top Level -> System from the Documents section.
- Create a folder specifying the type of integration you are adding (e.g. iManage, Sharepoint)
- Drop the .class file and .properties file created in the last section into this folder.
Using the DMS Connector Tool
- An integration is added to your TeamConnect instance by navigating to Tools -> DMS Connector
- In the Type dropdown, you should see the folder name you created in the last section.
- Once you've selected a type, the values displayed on the page should correspond to the labels you added to your integration .properties
- Click the Add button and see your integration in the list.
- Use the Test integration button to see if your connection works.
