Email Cloud Service Link Ingestion - tsgrp/HPI GitHub Wiki

##What is it?

In Bulk Upload, there is now the ability to parse through the email content and if a link to a supported cloud service document or folder is found, allow the user to upload those documents into HPI. While this is a useful tool, there is understandably a bit of configuration that is necessary to make it all work.

##Currently Implemented Services

• Google Drive
• Microsoft OneDrive
• Dropbox

##Registering HPI with the Cloud Services

Each service will require some configuration. You must register your application with the service to gain access to their API. Every instance of HPI on a different domain will need to be registered.

Note: If you are enabling more than one service, make sure your Root domains match across services - e.g. use 'mydomain.com' for both Google and Microsoft.

###Google Drive

Go to the Google App Console. Click the 'Create Project' button. Once the project is created, on the left-hand side, under APIs & auth, click on 'APIs'. In the list of APIs, turn on the Drive API (click the 'OFF' button on the right). You can turn off the other APIs, but that is not necessary.

Under 'APIs & auth' click on 'Credentials'. Under OAuth, click 'Create new Client ID'. In the pop-up, make sure Web application is selected and click 'Configure consent screen'. Under PRODUCT NAME, put the name the user will see when asked to authenticate. The other inputs on this screen are optional. After saving, a modal should pop up.

Under Authorized Javascript Origins, put in the domain that HPI is at (http://localhost:9000, e.g.). Under Authorized Redirect Uris, put down a dummy path as we won't actually be redirecting after authentication. Click 'Create Client ID'. This should take you to the screen with your ClientID and Client secret. To get back to this screen, under APIs & auth, click on 'Credentials'.

###Microsoft OneDrive (SkyDrive)

Go to the Microsoft App Console. Click 'Create application'. Type in the Application name and click 'I accept'. This will create your application and take you to the home screen for your application configuration.

In the menu on the left, click 'API Settings'. Select 'Yes' for 'Mobile or desktop client app:'. Under Redirect URLs, add a dummy redirect url. Note - Microsoft requires the domain name to contain a '.com'/'.org'/etc.

Click on 'App Settings' on the left to get your ClientID and Client secret.

###Dropbox

Dropbox doesn't require any type of authentication or registration at this point, as we don't use the API. If this changes, this section will be updated accordingly.

##OpenContent Configuration

In OpenContent, we define 'supported urls' and 'unsupported urls'. Each group lists url fragments that OC will look for when parsing email content to find cloud links. Supported urls are urls that HPI will parse and use to import content. Unsupported urls are url fragments from services we know we don't support. These will also be found when parsing the email, and we will display a screen to the user saying that we found an unsupported service url.

These lists are created in core-bean-config.xml and cloud-service-defaults.properties. Each service (both supported and unsupported) gets its own bean in core-bean-config.xml and the list of url fragments to look for are in a comma-delimited list in core-defaults.properties. Any changes to the defaults you want to make should be done in your project-bean-config.xml and project-placeholders.properties.

These are the default settings:

Supported:

• Google - docs.google.com, drive.google.com
• Microsoft - onedrive.live.com
• Dropbox - dropbox.com

Unsupported:

• Oxygen Cloud - www.oxygencloud.com
• Box - box.com
• Amazon - amazon.com/clouddrive
• Citrix ShareFile - sharefile.com
• iCloud - icloud.com
• Globalscape - globalscape.com

##HPI Admin Configuration

If you want to parse for cloud links, first enable that setting in the Bulk Upload advanced config. Then, do the following for the supported services.

###Google Drive Copy and paste in the Client ID from your registered Google project. The Client ID can be found by going to the app console, selecting your project, and under 'APIs & auth', clicking on 'Credentials'. The Client ID should be on the right.

###Microsoft OneDrive Copy and paste in the Client ID from your registered Microsoft project. The Client ID can be found by going to the app console. The string of numbers under your project name is the Client ID.

###Dropbox Because HPI doesn't need Dropbox's API, no project was registered, and thus no HPI Admin configuration is needed. If this changes, this section will be updated accordingly.

##Adding a Cloud Service To add a cloud service there are a few places that will need to be updated:

• In OpenContent, the service will need to be configured in core-bean-config.xml and cloud-service-defaults.properties.
• If a Client ID of some kind is needed, the Bulk Upload Custom Config will need to be updated to provide that configuration.
• In cloudlinkauthentication.js, a view will need to be added for the service's authentication. This view needs to have an authorize function that puts an authObject on self.options with the info the service needs to make requests to its API. It should then trigger the 'authenticationRouter:next' event on app, sending this.options.routeIndex + 1 as a parameter. Look at the other services for examples.
• In cloudlinkutils.js, add an object for the new service. It will need a parseLink function that returns a string/object that represents the path/id of the document or folder that the service's API can use to get the document/folder. It will also need a getDocuments function that takes in the string/object returned by parseLink and the authentication object created in cloudlinkauthentication and triggers bulkupload:filesUploaded event on app with OCOs.
• Update this doc on how to configure the new service.

The above is a general outline. Your service may need to tweak some of this, but any unique logic should be kept in cloudlinkauthentication.js and cloudlinkutils.js.