After my previous blog post about how to create an Ephesoft plugin, I wanted to do the same exercise from scratch with another plugin. So, I decided to create a plugin to export documents to Dropbox. So, I re-created the same structure of my other project and I cleaned all context files and Java classes. But, I didn't really started from scracth, I used the CMIS export plugin as template.
I decided to create a helper to isolate the code concerning Dropbox. The tricky thing with Dropbox is the authentication. First, you need to create an application in Dropbox that provides you an application key and an application secret. Using these 2 parameters and the Dropbox SDK, you can get an authentication URL. If you open this URL in a browser, you can get an application code. This code will allow you to get an access token that has to be stored somewhere safely, because it will be used for all requests done to Dropbox. So, our Dropbox helper is in charge of the authentication and as well of the upload of document in Dropbox.
Similarly to the CMIS plugin, the Dropbox exporter is in charge of finding documents in the current batch instance, creating the name that will be used in Dropbox, defining the folder where will be exported documents. And finally, this exporter will call the Dropbox helper to create new files in Ephesoft. To achieve that, we'll have the same properties as the CMIS plugin: Root Folder Name, File Extension, File name.
To create a plugin in Ephesoft, you need to define a service that will be called by Ephesoft in the workflow. So this service is simply calling the Dropbox exporter.
How to use it?
So, we are following the same procedure identified in my previous blog. First, you need to open the Workflow Management page and upload the Dropbox plugin. An important step is to add Dropbox JAR libraries in Ephesotft. You need to download the Java SDK for Dropbox: https://www.dropbox.com/developers/core/sdks/java. In the ZIP file, you''ll find 2 JAR files in the folder lib called dropbox-core-sdk-1.7.6.jar and jackson-core-2.2.3.jar. These 2 files have to be uploaded to the lib folder in Ephesoft, i.e. in Application/WEB-INF/lib. After that, you need to restart your Ephesoft instance. You should see this message during the startup of Ephesoft:
Initialization of the Dropbox Plugin Service.
When Ephesoft is restarted, we are going to add this plugin to our batch class. For this blog, we are using a standard batch class provided by Ephesoft called "Searchable PDF Template". In the export module, just before the cleanup plugin, we add our new Dropbox plugin and we save the batch class. Don't forget to click on the button Validate and next Deploy Workflow to apply changes.
Now, it's time to create our application in Dropbox. We open the Dropbox Developer Console on https://www.dropbox.com/developers/apps. You can click on the button Create app. Next, click on Dropbox API app, click on Files and datastores and select "Yes, My app needs access to files already in Dropbox." and select "All file types" and decide of an application name. Finaly, you need to click on the button Create app.
The next screen will provide the application key and application secret.
The Dropbox application is created and, now, we need to configure the Dropbox plugin in Ephesoft. We are going to set the switch to ON and fill the application key and secret with the ones provided by Dropbox. Deliberately, we let the application code empty. We decide to export all documents in a folder called Ephesoft. This folder will be created if it doesn't exist. We want to export pdf documents. Finally, as the CMIS plugin, we specify how to format the file name.
Now, you can try to upload a new batch. But, this batch instance will fail because the Ephesoft application in Dropbox has not been authorized yet. So, if you check the log file, you'll see a message like this:
Exporting documents to DropBox... - Dropbox export plugin: initialisation... - Dropbox export plugin: authenticating... 1. Go to: https://www.dropbox.com/1/oauth2/authorize?locale=en_US&client_id=XXX&response_type=code 2. Click "Allow" (you might have to log in first) 3. Save the authorization code in the plugin properties.
Open the URL in your browser, click on the button Allow and save the generated configuration code in the plugin configuration in the Ephesoft UI.
You'll need to restart the export module of the current batch instance in the Ephesoft UI. During this export process, the plugin is going to use the configuration code to request a token. This token will be re-used for all next following export jobs. This access token is automatically saved in a configuration file in "Application\WEB-INF\classes\META-INF\dcma-dropbox-plugin\dcma-dropbox-plugin.properties". You should find in the log file:
Exporting documents to DropBox... - Dropbox export plugin: initialisation... - Dropbox export plugin: authenticating... - Linked account: Ben Chevallereau - Dropbox export plugin: uploading... - Uploaded: File("/Ephesoft/BI14_documentDOC1.pdf", iconName="page_white_acrobat", mightHaveThumbnail=false, numBytes=218725, humanSize="213.6 KB", lastModified="2014/01/23 23:46:25 UTC", clientMtime="2014/01/23 23:46:25 UTC", rev="11e408d7a") - Dropbox export plugin: uploading... - Uploaded: File("/Ephesoft/BI14_documentDOC2.pdf", iconName="page_white_acrobat", mightHaveThumbnail=false, numBytes=81488, humanSize="79.6 KB", lastModified="2014/01/23 23:46:26 UTC", clientMtime="2014/01/23 23:46:26 UTC", rev="31e408d7a")
You just need to check your Dropbox account and you'll see your newly exported document.
I spent about 8 hours on creating this plugin. The first plugin has been really useful to understand how Ephesoft works with custom plugin, how I need to create a Maven project to be compatible with Ephesoft. But it has been relatively quick this new plugin. Furthermore, I spent a significative quantity of time to understand how the authentication works with Dropbox and how to manage it with an Ephesoft plugin.
Using the debugging directly in Eclipse (using jpda) has been a good way to increase the development time, and the use of the CMIS export plugin as a template has been, as well, a good way to structure properly this plugin.