Skip to content
Documentation
|
Latest Release
|
Get a Demo

Introduction

The Neuron ESB Dropbox Connector (Adapter) provides direct access to the Dropbox REST API (v2). Using this adapter, organizations can easily integrate their business content management requirements with Dropbox. This adapter provides four modes – API, Publish, Subscribe and Solicit/Response. Publish and subscribe modes provide similar functionality as the File and FTP adapters. In publish mode, a Dropbox folder is polled for documents. When a new document is found it is published to a topic as the body of the Neuron ESB message. In subscribe mode, when the Dropbox adapter receives a new message, the body of the message is written to a Dropbox folder as a document. Solicit/Response performs the same functionality as subscribe mode with the added functionality of receiving a file info document as the response and the ability to create a shared link for the uploaded file. The API mode provides you with access to the Dropbox REST API. You can use this mode to call any of the Dropbox APIs and receive a response.

When developing applications that utilize this adapter, developers will be able to use the Adapter Metadata Generation Wizard to provide JSON samples that describe the request and/or response documents that can be used when using the Dropbox adapter in API mode.

Before reading this document

If you are not familiar with Neuron ESB Adapters, take a moment to consult the Adapter Overview. This document assumes you have the following knowledge:

  1. What adapters are and how they are leveraged in Neuron ESB
  2. Register a Neuron ESB Adapter within a Neuron ESB Solution
  3. Create an Adapter Endpoint in a Neuron ESB Solution
  4. Set a Neuron ESB Adapter Endpoint Properties
  5. Invoke a Neuron ESB Adapter Endpoint

Supported Modes

The Dropbox Adapter supports Publish, Subscribe, Solicit/Response and API modes. Publish and subscribe are both one-way calls. The solicit/response and API modes send request-reply calls to the Dropbox API.

Properties

Every Neuron ESB Adapter has design time properties that can configured within a standard Microsoft property grid (as shown below). These properties are used to determine the behavior of the adapter at runtime. The group of Connection properties is used to configure the Dropbox API URL and the OAuth Provider used for authorization.

Dropbox Url

The base Url used when making calls to Dropbox. This should always be https://api.dropboxapi.com/2. When using API mode, when making calls to a specific API you would set the ESB Message’s local path, which will be appended to this Url.

OAuth Provider

This is the pre-configured OAuth Provider that will be used when making calls to Dropbox. See the section titled Dropbox OAuth Provider for details on how to create an OAuth connection.

Send Timeout

This is the amount of time in seconds the Dropbox adapter will wait to upload a file when in subscribe or solicit/response mode, or for a reply when in API mode. The default value is 60 seconds and should be long enough for most calls. However, if you performing complex queries you may want to extend the timeout.

Proxy Server

Allows you connect to Dropbox via a proxy server. By default this value is set to System Default. Changing the value to custom will expose additional properties:

  • Address – The URL address to the proxy server
  • Port – The port for the proxy server address
  • Use Custom Credentials – By default this is set to false and will use the credentials that the Neuron ESB instance is running under. Changing this value to True will allow you to select a stored credential from Neuron ESB.

Publish Mode Properties

In publish mode, the Dropbox adapter will poll a Dropbox folder and publish documents to a topic. The content of the document found in Dropbox will become the content of the Neuron ESB Message body.

Publish Topic

The Neuron ESB topic that messages will be published to.

Polling Interval

The amount of time between each polling attempt to see if there are any files to download from Dropbox.

Polling Batch Size

The maximum number of files to download during each polling attempt. Valid values are 1-1000. This property should be set based on the sizes of files being downloaded. The smaller the file, the higher you can set this number. For very large files you should set this value to a lower value.

Publish Folder

The relative path of the Dropbox folder to poll for files. To select the root folder, leave this property blank. To select a subfolder, click the ellipsis button, navigate to the folder you want to download files from and click OK. You can also type the path to the folder, i.e. “RootFolder\SubFolder”.

File Mask

File spec for retrieving files from Dropbox. Must be in the form of “*.*”. This also supports wild characters like “*” and “?”. Masks can be used for file name as well as extension i.e. “my?name.*”. Example: “*.log”. If all files should be returned use ‘*’ or “*.*”. Multiple search filters can be supplied if separated by a comma or semicolon i.e. “*.txt;*.doc”.

Delete After Download

Deletes the file on Dropbox after it is retrieved. Default value is True. Setting this to False will display the properties Enable Timestamp Comparison and Check Window.

Enable Timestamp Comparison

If True, compares the last write timestamp of the Dropbox file to retrieve, with the timestamp of the previously retrieved file of same name. If timestamps are the same, the file is not retrieved again unless the Check Window property has been exceeded. If False, the file will be downloaded with every polling interval. This property is only enabled when Delete After Download is set to False.

Check Window

The timespan range from the current date time which the file will be considered a duplicate and not be downloaded if Timestamp Comparison is enabled. Format is “d:hh:mm:ss”. For example, if the file is downloaded at 8:00 AM, and the check window is 12:00:00, then file will automatically be downloaded again at 8:00 PM even if the file has not changed. This property is only enabled when Delete After Download is set to False.

Archive File After Download

When set to True, the adapter will archive the file on Dropbox after it is retrieved. Default is False. This will override the ‘Delete After Download’ property. Setting this to True will display the property Archive Folder.

Archive Folder

The relative path of the Folder to archive the downloaded files to. Can be a single folder, or a path i.e. “RootFolder\SubFolder”. This is only enabled when Archive File After Download is set to True.

Publish Metadata Only

Publishes the metadata of the file, not the actual data. The file will be moved to the specified Archive Folder. This is useful when you only want to pass a pointer to the file to another system (i.e. a link to the file in a SharePoint site). When setting this to True, the Archive File After Download property will also be set to true and you will be required to set an archive folder.

Publish Empty Message

Publishes an empty message if a zero byte file is returned from Dropbox.

Remove BOM

Provides the option for the adapter to remove the Byte Order Characters (BOM) preceding data in UTF8/UTF16 and other web formatted files.

Audit Message on Failure

When set to true, a message that has been received from Dropbox but fails publishing to a topic will be audited to the failed messages table.

Error Reporting

Determines how all errors are reported in Event Log and Neuron Logs. Either as Errors, Warnings or Informationals.

Error On Polling

Determines if polling of the folder will continue when an error occurs and if consecutive errors are reported. If StopPollingOnError is selected, when an error occurs the adapter endpoint will go into the Failed state. If SuppressConsecutiveErrors is selected, when an error occurs the adapter endpoint will continue to poll at the next polling interval. If the same error is encountered it will not be logged. If ReportAllError is selected, when an error occurs the adapter endpoint will continue to poll at the next polling interval. All errors will be logged.

Subscribe Mode Properties

In subscribe mode, the Dropbox adapter will create or overwrite a document in a Dropbox folder. The content of the Neuron ESB Message body will be saved as the content of the document created in Dropbox.

Subscribe Folder

The relative path of the Dropbox folder to send files to. To select the root folder, leave this property blank. To select a subfolder, click the ellipsis button, navigate to the folder you want to download files from and click OK. You can also type the path to the folder, i.e. “RootFolder\SubFolder”.

Generate Unique File Names

Setting this to true will automatically generate a unique file name based on a Guid on Dropbox for the uploaded file. When set to false, the filename will be determined in this order:

  1. The value of the Neuron ESB Message property dropbox.Filename (this would have to be set by a user in a process or workflow)
  2. If #1 does not return a file name, the internal Neuron ESB Message ID + the numerical value of DateTime.UtcNow.Month + the numerical value of DateTime.UtcNow.Ticks + .txt

Overwrite

When set to True, if the file already exists on Dropbox, the adapter will attempt to overwrite it. When set to false and the filename exists in the Dropbox folder, the file will not be uploaded and an error will be logged.

Auto Rename

If the filename already exists in the Dropbox folder, the Dropbox server will rename the new file to avoid the conflict.

Upload Large Files

Setting this to true will use the Dropbox upload session API to upload the file in blocks, and will display the property Maximum Block Size. This is required for files over 150MB, optional for smaller files.

Maximum Block Size

The maximum number of megabytes to upload during each session append to Dropbox. The maximum value supported is 150MB.

When set to true, once a file is uploaded to Dropbox, a shared link will be created for the file. Setting this property to true will display the properties Require Password, Set Expiration, Audience, Access Level and Allow Download. In solicit/response mode, the URL for the shared link will be returned as the message property dropbox.FileUrl.

Require Password

When set to true, the shared link will require a password before it can be downloaded. Setting this property to true will display the property Password.

Password

The password to use when creating a shared link that requires a password for download. This property can also be set per message using the message property dropbox.SharedLinkPassword.

Set Expiration

If you want the link to expire in a certain amount of time, set this to true. Setting this property to true will display to property Expires In.

Expires In

The timespan in which the share link will remain active. This timespan is added to the date and time the file is uploaded. The format is d.hh:mm:ss.

Audience

The new audience who can benefit from the access level specified by the link’s access level specified in the Access Level property. This is used in conjunction with team policies and shared folder policies to determine the final effective audience type. This field is optional.

Access Level

The level of access for the shared link. This field is optional. The following values are currently supported:

  • viewer – Users who use the link can view and comment on the content.
  • editor – Users who use the link can edit, view and comment on the content. Not all file types support editing.
  • max – Provides the maximum access level you can set the link to.

Allow Download

Flag whether or not to allow the file to be downloaded.

Using the Dropbox Adapter

The Dropbox Adapter has four modes:

  • Publish
  • Subscribe
  • Solicit/Response
  • API

Publish and subscribe modes operate in the same manner as the file and FTP adapters. The Neuron ESB message body contains the file to be uploaded or downloaded from Dropbox. Solicit/Response mode will provide you with a file info response. The API mode allows you to call the Dropbox API directly. The message formats for the APIs can be retrieved using the Metadata Generation Wizard.

For more information about the Dropbox API, visit the Dropbox API Reference.

Integrating with Dropbox can be done in many different ways. Using publish, subscribe and solicit/response modes you can directly download and upload files to Dropbox. Using API mode you can integrate with any of the Dropbox APIs. The request messages can be created in a C# or C# Class step in a process or workflow. You can also pass-thru a REST request received by a client connector and route it to a Dropbox Adapter endpoint. This document focuses on creating the requests with a C# step in a process.

Security

As noted previously, the adapter supports OAuth 2.0 when integrating with Dropbox. The adapter handles all the security requirements at runtime. When you’re constructing a request message to send to Dropbox you do not need to worry about setting credentials.

Request and Response Message Formats

The Dropbox adapter only supports JSON content for request and response messages. The request and response message formats depend on the API being called. You can retrieve JSON samples using the Metadata Generation Wizard described below.

Dynamic Message Properties

The Dropbox adapter supports several message properties that can be used to dynamically change the behavior of the adapter at runtime. All the message properties have the prefix “dropbox”. For example, if you want to set the filename that will be used when uploading a file to Dropbox on a per-message basis, you could use the following code in a C# step:

context.Data.SetProperty(“dropbox”, “Filename”, “test.xml”);

Subscribe and Solicit/Response Mode Message Properties

These message properties can control the behavior when uploading files to Dropbox:

FolderName of the Dropbox folder that the file will be written to
FilenameThe name that will be used when uploading
SharedLinkPasswordThis password that will be required when download a file from a newly created shared link
FileUrlThe URL of the file uploaded to Dropbox

Publish Mode Message Properties

These message properties are set when downloading files from Dropbox:

FolderName of the Dropbox folder from which the file was retrieved
FilenameName of the file received from Dropbox
LengthLength of the file in bytes
TimestampThe date time stamp of the file on Dropbox
ModeRepresents the configured Adapter Mode for the endpoint
DescriptionThe file description of the file on Dropbox
DownloadUrlThe direct URL to download the file on Dropbox
ArchiveFileInfoThe full file info of the downloaded file after it has been archived
ArchiveFolderThe folder the downloaded file has been archived to after it has been archived
ArchiveUrlThe direct URL to download the archived file on Dropbox

API Mode Properties

There are no dynamic message properties used in API mode.

Create a Dropbox Account

If you don’t already have one, you will need to sign-up for a Dropbox account. You can get a free account from https://www.dropbox.com/register. After completing the sign-up details and confirming your email address, you will need to perform some setup in your account before you can use the adapter.

Dropbox Application Setup

The Dropbox adapter uses OAuth 2 to authenticate users. You will need to create and configure an application in Dropbox for your account. This section will provide high-level details of how to create an application. For a the most current guide on creating an application in Dropbox, go to the Dropbox OAuth Guide.

  1. Create and configure an application – Navigate to https://www.dropbox.com/developers/apps and click the Create app button and complete the following steps:
    1. Choose an API – select the Scoped access radio button.
    2. Choose the type of access you need – select either the App folder or Full Dropbox option, depending on your requirements. To use this account with the tutorial in this documentation, select Full Dropbox.
    3. Name your app – enter a name for you app, like Neuron ESB Integration.
    4. Agree to the terms and conditions and click the Create app button.
  2. Once the app has been created, you need to configure it. On the Settings tab:
    1. Copy the App key and App secret values. These will be used when creating the Dropbox OAuth provider in Neuron ESB.
    2. Add a Redirect URI. For this tutorial, set the value to https://localhost/neuron and click Add.
    3. Leave the remaining properties on the Settings tab as their default values.
  3. Click on the Permissions tab and enable the following permissions listed under Individual Scopes (at a minimum, other permissions may be required when using the adapter in a team setting or in API mode):
    1. files.metadata.read
    2. files.content.write
    3. files.content.read
  4. Click the Submit button that appears on the bottom of the web browser to save your changes.

Create Folders in Dropbox

Now you will create the folders in Dropbox the adapter will access for reading and writing files. Navigate to https://www.dropbox.com/home. If you are required to log-in again, use the same account you used to create the application in the previous section. On the home page, click the Create button and then Folder:

Create a folder called From Neuron. Set the Who can access to Only you, and click the Create button:

Repeat the above steps and create a second folder called “To Neuron” and a third folder called “Neuron API”. All three of these folders will be used in the tutorials. Make sure you create them all in the root! After you create a new folder you will automatically navigate into it!

Tutorial

This tutorial is broken down into three parts:

  • Creating a Dropbox OAuth Provider
  • Uploading files to Dropbox
  • Downloading files from Dropbox
  • Directly calling the Dropbox APIs

Each section will describe the Neuron configuration that needs to be created in order to complete that part of the tutorial. It is expected that the reader of this document is familiar with creating/configuring topics, publishers, subscribers and file adapter endpoints. The tutorials will describe in detail how to create Dropbox OAuth providers and adapter endpoints.

Tutorial Requirements

The four tutorials all have the following requirements:

  • A Dropbox account (see above)
  • A Dropbox application created and configured (see above)
  • Folders created in Dropbox (see above)
  • A new, blank Neuron ESB Configuration that has been saved as DropboxTutorialESB
  • The Neuron ESB runtime is configured and started with the configuration DropboxTutorialESB

Creating a Dropbox OAuth Provider

Once you’ve created the Application and saved the App key and App secret, you can create the Dropbox OAuth Provider in Neuron. The adapter will utilize the OAuth provider when authenticating with Dropbox. Dropbox does not support the Client Credentials OAuth Flow. Therefore you need to acquire an initial access token from Dropbox when you create the OAuth Provider. When you retrieve an access token during setup, you will also get a refresh token. When the short-lived access token from Dropbox expires, the OAuth provider will automatically retrieve a new access token using the refresh token. The refresh token is long-lived and does not expire unless an administrator deletes the Dropbox application you created for this integration.

Please verify the tutorial requirements above have been completed prior to starting this tutorial.

To create an OAuth Provider:

  1. Open Neuron ESB Explorer and the DropboxTutorialESB configuration referred to in the above requirements.
  2. In Neuron ESB Explorer, click on the Security->OAuth Providers and click New. Set the name of the OAuth Provider to Dropbox OAuth Provider and select Dropbox from the Provider drop-down list:



  3. In the properties for the Dropbox OAuth Provider, set the follow properties:
    1. Client ID – set this to the value of the App key from the Dropbox application
    2. Client Secret – set this to the value of the App secret from the Dropbox application
    3. Redirect URI – set this to https://localhost/neuron
    4. Scope – TODO
  4. After entering the OAuth provider properties, click the Test button:



  5. The OAuth Login form will appear, requesting your Dropbox credentials. Enter the email and password for the account you created and click the Sign in button:



  6. After a moment you will be requested to Continue to connect Neuron ESB to your Dropbox account. Click the Continue button:



  7. Finally, you will be asked if you would like to allow the Neuron ESB Integration app to have the listed permissions against your account. Click the Allow button:



  8. You will see that an Access Token has been added to the OAuth Provider. This is a valid OAuth token, and the adapter will attempt to use it at runtime.  If the access token expires the OAuth provider will automatically request a new one:



  9. Click the Apply button for the the OAuth provider and then save your solution.

Uploading Files to Dropbox (Subscribe Mode)

This tutorial walks you through building an integration that will read files from a local folder using the file adapter and uploading those files to a Dropbox folder.

This tutorial requires:

  • Verify the tutorial requirements above have been completed
  • Complete the tutorial Creating a Dropbox OAuth Provider
  • Add the following items to the DropboxTutorialESB configuration:
    • Topic – File
      • Subtopic – File.Outbound
    • Publisher – FilePublisher with subscriptions to File. Outbound (Send)
    • Subscriber – DropboxSubscriber with a subscription to File.Outbound (Receive)
    • Adapter Endpoint:
      • Name – File In
      • Adapter – File
      • Mode – Publish
      • Processing Mode – Messaging
      • Publish/Subscribe – Checked
      • Party Id – FilePublisher



      • Folder Path – C:\FileIn (or another folder that you choose)
      • File Type – *.*
      • Publish Topic – File.Outbound

Save the Neuron configuration after applying the above changes.

*Note – Typically when performing one-way messaging with any adapter you should use a topic with a durable transport, either MSMQ or RabbitMQ. For this tutorial you can use TCP or Named Pipe for the topic transport for ease of setup.

Creating an Adapter Endpoint that Uploads Files to Dropbox

  1. Navigate to Connections->Adapter Endpoints and click New. Set the name of the adapter endpoint to Dropbox Upload, select Dropbox from the Adapter drop-down list and select Subscribe from the Mode drop-down list. Select the Messaging radio button, check the Publish/Subscribe box and select BoxSubscriber from the Party Id drop-down list:



  2. Click on the Properties tab. Select the Dropbox OAuth Provider from the OAuth Provider drop-down list. Click on the Subscribe Folder property, then the ellipsis button. A dialog with the folders accessible to the Dropbox adapter is displayed:




    Select From Neuron and click OK. All the other properties will keep their default values:




    Don’t forget to click the Apply button!

  3. Save the Neuron ESB configuration.

At this point, you should have a file adapter endpoint that publishes messages to the topic File.Outbound, and a Dropbox adapter endpoint subscribing to messages from that same topic.

To test uploading files to Dropbox, all you need to do is copy a file into the folder that you configured the File In adapter endpoint to read messages from. Once the file adapter has read the message from the local folder, it should appear in the Dropbox folder From Neuron.

This tutorial walks you through building a process that will upload a file to a Dropbox folder, create a shared link and return the uploaded file info as a response.

This tutorial requires:

  • Verify the tutorial requirements above have been completed
  • Complete the tutorial Creating a Dropbox OAuth Provider

Creating an Adapter Endpoint that Uploads Files to Dropbox

  1. Navigate to Connections->Adapter Endpoints and click New. Set the name of the adapter endpoint to Dropbox Solicit Response, select Dropbox from the Adapter drop-down list and select Solicit Response from the Mode drop-down list. Select the Messaging radio button and uncheck the Publish/Subscribe box:




  2. Click on the Properties tab:
    1. Select the Dropbox OAuth Provider from the OAuth Provider drop-down list.
    2. Click on the Subscribe Folder property, then the ellipsis button. A dialog with the folders accessible to the Dropbox adapter is displayed:




      Select From Neuron and click OK.

    3. Set the following properties:
      • Generate Unique Filename = False
      • Overwrite = True
      • Auto Rename = True
      • Upload Large Files = False
      • Create Shared Link = True
      • Require Password = False (this feature requires a Professional or Enterprise Dropbox account)
        • Password – if you set Require Password to True, leave this blank. A randomly generated password will be set in a business process
      • Set Expiration = False (this feature requires a Professional or Enterprise Dropbox account)
      • Audience = public
      • Access Level = viewer
      • Allow Download = True




        Don’t forget to click the Apply button!

  3. Save the Neuron ESB configuration.

Create a Business Process that Uploads a File to Dropbox

This process will demonstrate uploading a file to Dropbox and receiving a file info response with a shared link.

  1. Navigate to Processes in the Neuron ESB Explorer



  2. Click the New drop down and select Create Process



  3. Click on the UI element named New Process 1 and in the Property Grid on the right-hand side of the Neuron ESB Explorer enter “Upload File” in the Name text field.

    Graphical user interface, application Description automatically generated

  4. In the Search Steps text field of the Process Step Library enter “C#”

    Graphical user interface, text, application Description automatically generated

  5. Drag the C# process step on to the design canvas and drop it in the middle of the UI element labeled “Upload File”. Set the name of the process step to Set Filename and Password.
  6. Double-click on the C# step to open the code designer. The following code can be used to set the filename of the file being uploaded and generate a password to assign to the shared link that will be created:
    // Set the Filename message property to use for the uploaded file
    context.Data.SetProperty("dropbox", "Filename", "test.xml");

    // Generate a password to assign to the shared link that will be created
    // Note - this is a simple password generator which would not necessarily solve specific password requirements.
    // Modify this as needed for your own password requirements
    // Note - The password message property will only be used if Require Password adapter endpoint property is set to true.
    //        You must have a Dropbox Professional or Enterprise account to set a password
    string valid = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890";
    System.Text.StringBuilder res = new System.Text.StringBuilder();
    int length = 8;
    Random rnd = new Random();
    while (0 < length--)
    {
         res.Append(valid[rnd.Next(valid.Length)]);
    }

    // Set the SharedLinkPassword message property
    context.Data.SetProperty("dropbox", "SharedLinkPassword", res.ToString());

    // Output the password for testing purposes
    context.Instance.TraceInformation("Password = " + res.ToString());
  7. Click the Apply button in the code editor and navigate back to the Upload File process.
  8. In the Process Step Library, find the Adapter Endpoint step and drag it onto the designer directly under the C# step:

    Graphical user interface, application Description automatically generated

  9. Click on the Adapter Endpoint step, set the name to Upload to Dropbox and select Dropbox Solicit Response from the Adapter Endpoint drop-down list in the properties grid:



  10. In the Process Step Library, find the C# step and drag it onto the designer directly under the Adapter Endpoint step:



  11. Set the name of the C# process step to Get Download URL.
  12. Double-click on the C# step to open the code designer. The following code can be used to get the shared link download URL for the uploaded file:
    var url = context.Data.GetProperty("dropbox", "FileUrl", "");
    context.Instance.TraceInformation("Download URL: " + url);
  13. Click the Apply button in the code editor and navigate back to the Upload File process.
  14. This entire process should look like this:



  15. Apply the changes to the process by clicking the Apply button in the process designer toolbar:



    Congrats! You are now ready to fully test the Business Process.

Testing the Dropbox in Solicit/Response Mode

You can now test the above process using the Process Tester.

  1. Open the process tester by clicking the Test Process button in the process designer toolbar:



  2. The Edit Test Message dialog will appear. You do not need to enter or change the message body:

    Graphical user interface, application Description automatically generated

  3. Click the OK button, and you will see each step in the designer highlight as it is executed.
  4. Several entries will appear in the Output window at the bottom of the designer. Most of these are from the Dropbox Adapter displaying its debug output. There will be two entries from the code steps in the process. The first one will appear at the beginning of the list. Drag the vertical scroll bar to the top of the output window:

    Text Description automatically generated

    Here you will see the password that was generated for the download URL.

    The last two lines in the output window at the bottom of the designer will contain the download URL and the file info response body:



    Double-click the last output entry to see the entire text.

    You can copy the Download URL value and paste it into a browser to download the file. If you set the Require Password property to True, you will be prompted to enter a password, which you can also copy from the output entries.

Downloading Files from Dropbox (Publish Mode)

This tutorial walks you through building an integration that will read files from a Dropbox folder and saving those files to a local folder using the file adapter.

This tutorial requires:

  • Verify the tutorial requirements above have been completed
  • Complete the tutorial Creating a Dropbox OAuth Provider
  • Add the following items to the DropboxTutorialESB configuration.
    • Topic – File
      • Add the subtopic – File.Inbound
    • Publisher – DropboxPublisher with subscriptions to File.Inbound (Send)
    • Subscriber – FileSubscriber with a subscription to File.Inbound (Receive)
    • Adapter Endpoint:
      • Name – File Out
      • Adapter – File
      • Mode – Subscribe
      • Processing Mode – Messaging
      • Publish/Subscribe – Checked
      • Party Id – FileSubscriber



      • Folder Path – C:\FileOut (or another folder that you choose)
      • File Type – txt



        Save the Neuron configuration after applying the above changes.

        *Note – Typically when performing one-way messaging with any adapter you should use a topic with a durable transport, either MSMQ or RabbitMQ. For this tutorial you can use TCP or Named Pipe for the topic transport for ease of setup.

Creating an Adapter Endpoint that Downloads Files from Dropbox

  1. Navigate to Connections->Adapter Endpoints and click New. Set the name of the adapter endpoint to Dropbox Download, select Dropbox from the Adapter drop-down list and select Publish from the Mode drop-down list. Select the Messaging radio button, check the Publish/Subscribe box and select DropboxPublisher from the Party Id drop-down list:



  2. Click on the Properties tab. Select the Dropbox OAuth Provider from the OAuth Provider drop-down list and set the Publish Topic to File.Inbound. Click on the Publish Folder property, then the ellipsis button. A dialog with the folders accessible to the Dropbox adapter is displayed:



    Select To Neuron and click OK:



    Don’t forget to click the Apply button!

  3. Save the Neuron ESB configuration.

At this point, you should have a Dropbox adapter endpoint that publishes messages to the topic File.Inbound, and a file adapter endpoint subscribing to messages from that same topic.

To test downloading files from Dropbox, all you need to do is copy a file into the To Neuron folder that you created in Dropbox to read messages from. Once the file adapter has read the message from Dropbox, it should appear in the local folder you configured for the file adapter named File Out.

Directly calling the Dropbox APIs

This tutorial walks you through building an integration that calls the Dropbox APIs directly. You will learn how to use the Metadata Generation Wizard to browse the Dropbox APIs and generate JSON examples for each call you want to make. The integration will utilize a Business Process that will query Dropbox for the list of available files and download the oldest one.

Note – Dropbox utilizes two URLs for it’s API:

  • api.dropboxapi.com – arguments are passed as JSON in the request body and return results as JSON in the response body.
  • content.dropboxapi.com – these are use for content uploading and downloading. The request and response bodies are reserved for the file contents. arguments are instead passed as JSON in a header named Dropbox-API-Arg. 

Both URL format are demonstrated in this tutorial.

This tutorial requires:

  • Verify the tutorial requirements above have been completed
  • Complete the tutorial Creating a Dropbox OAuth Provider
  • The File Out adapter endpoint created in the section Downloading Files from Dropbox

Creating an Adapter Endpoint that Calls the Dropbox API

  1. Navigate to Connections->Adapter Endpoints and click New. Set the name of the adapter endpoint to Dropbox API, select Dropbox from the Adapter drop-down list and select API from the Mode drop-down list. Select the Messaging radio button but uncheck the Publish/Subscribe box:



  2. Click on the Properties tab. Select the Dropbox OAuth Provider from the OAuth Provider drop-down list. Since this adapter endpoint will use the API mode you will not need to set any additional properties:



    Don’t forget to click the Apply button and save your changes!

Creating an Adapter Endpoint that Calls the Dropbox Content API

  1. Navigate to Connections->Adapter Endpoints and click New. Set the name of the adapter endpoint to Dropbox Content API, select Dropbox from the Adapter drop-down list and select API from the Mode drop-down list. Select the Messaging radio button but uncheck the Publish/Subscribe box:



  2. Click on the Properties tab. Change the Dropbox URL to https://content.dropboxapi.com/2. Select the Dropbox OAuth Provider from the OAuth Provider drop-down list. Since this adapter endpoint will use the API mode you will not need to set any additional properties:



    Don’t forget to click the Apply button and save your changes!

Using the Metadata Generation Wizard

The Metadata Generation Wizard is a tool that is used to generate sample messages and schema definitions for certain adapters and their operations. The Metadata Generation Wizard can be used to generate sample JSON request and response messages for the Dropbox Adapter. This section requires that you’ve completed the previous section Creating an Adapter Endpoint that Calls the Dropbox API.

  1. First, in Neuron ESB Explorer navigate to Repository->Json Documents:



  2. Next, click the Generate button:



    The Generate button can be accessed from any of the following menus:
  • In the “Repository” tab in:
    • XML Schemas
    • XSL Transformations
    • XML Documents
    • Text Documents
    • Json Documents
    • Swagger Documents
  • In the Connections tab in:
    • Adapter Registration
    • Adapter Endpoints
  1. On the Welcome Page, click Next:



  2. On the Connect to Data Source page choose an adapter and adapter endpoint. In this case, choose the Dropbox and the Dropbox API adapter endpoint created previously. Click Next:



  3. For the Dropbox adapter, the Category represents all the APIs that are available in Dropbox. For this tutorial, select a the Folders category and then select the Get items in folder operation by clicking the Add button:



  4. Repeat step 5 for the Files category and Download a file operation (don’t forget to click the Add button). Click Next:



  5. Review the operations selected. Click Next:



  6. Finally, click Finish to generate the documents:



    To see the sample message, navigate to the Json Documents Repository and select the document Get items in folder. For Json samples, the URL that would be called is set in the Source URL property:



    You can use these Json samples to guide your development when creating integrations to Dropbox.

Create a Business Process that Calls Dropbox APIs

This process will demonstrate calling out to Dropbox to retrieve a list of files in a folder and then download the oldest file.

  1. Navigate to Processes in the Neuron ESB Explorer



  2. Click the New drop down and select Create Process



  3. Click on the UI element named New Process 1 and in the Property Grid on the right hand side of the Neuron ESB Explorer enter “Get Oldest File” in the Name text field.



  4. In the Search Steps text field of the Process Step Library enter “Http”



  5. Drag the Http Client Utility process step on to the design canvas and drop it in the middle of the UI element labeled “Get Oldest File”.
  6. Right-click on the UI element named “Http Client Utility” and select “Configure”. The Http Client Utility editor will open:



  7. The first call to Dropbox is to retrieve the list of items in the Neuron API folder.

    Set the Method drop-down list to POST and the path to /files/list_folder. Click on the Body tab and select the Raw radio button and enter the following JSON text into the body window: 
    {
       "path": "/Neuron API",
       "recursive": false,
       "limit": 1
    }
    The “limit” parameter is used to limit the number of files downloaded at once. When testing this process, you can change this value to a higher number.



  8. Click the Save button to close the editor.
  9. In the Process Step Library, find the Adapter Endpoint step and drag it onto the designer directly under the Http Client Utility:



  10. Click on the Adapter Endpoint step and select Dropbox API from the Adapter Endpoint drop-down list in the properties grid:



  11. Apply the changes to the process by clicking the Apply button in the process designer toolbar:



  12. If, at any point, you want to test the process, you can do so by clicking the Test Process button in the process designer toolbar:



    The Edit Test Message dialog will appear. In this example you don’t need to change anything in the dialog, just click the OK button to start the test. The last line in the Output window at the bottom of the designer will contain the response body:



    Double-click the last output to see the text. Formatted, it’ll look similar to this:

    {
      "entries": [
        {
          ".tag": "file",
          "name": "XMLFile.xml",
          "path_lower": "/neuron api/xmlfile.xml",
          "path_display": "/Neuron API/XMLFile.xml",
          "id": "id:qu_27wgnBk8AAAAAAAAAGw",
          "client_modified": "2022-02-02T20:11:34Z",
          "server_modified": "2022-02-02T20:11:35Z",
          "rev": "5d70e9fe713358e444c61",
          "size": 428,
          "is_downloadable": true,
          "content_hash": "b0e739e4040ee8d43e1c10033c21050088a9c04223ad87656bbfd4f14d12e500"
        }
      ],
      "cursor": "AAGIGAvY15Al81vVB4PFYP66eBb6QJrM...",
      "has_more": true
    }
    In this call, one item was returned from the Neuron API folder. Notice that the “has_more” property is true, indicating there are more files to list. Since we want to look for the oldest file we need to keep retrieving the file list until the has_more property is false.
  13. The number of entries returned in the previous step is based on the “limit” property used in the request. Regardless of how many entries are returned, we need to loop through all the returned files to find the oldest file returned. In the Process Step Library, find the C# step and drag it onto the designer directly under the Adapter Endpoint step:



  14. Double-click on the C# step to open the code designer. The following code can be used to loop through the list of files from the response JSON. The fileInfo and file name of the oldest file returned are saved as the context properties, oldestFile and fileToDownload, respectively. The has_more flag is also saved to a context property, which will be used in the next step. Make sure you click the Apply button in the code editor after you’ve added the code: 
    // Load the response into a JSON object
JObject folderItems = context.Data.ToJObject();
JArray entries = (JArray)folderItems["entries"];

// Used to track the oldest file
dynamic oldestFile = entries[0];

// Check to see if there are any entries
foreach (dynamic fileInfo in entries)
{
  if (DateTime.Compare((DateTime)fileInfo.server_modified, (DateTime)oldestFile.server_modified) < 0)
  {
    oldestFile = fileInfo;
  }
}

// Save the oldest file in case there are more entries to retrieve
context.Properties.Add("oldestFile", oldestFile);
context.Properties.Add("fileToDownload", oldestFile.path_display);

// Initialize the hasMore property used by the While step
context.Properties.Add("hasMore", (bool)folderItems["has_more"]);

// Initialize the cursor for the next call
context.Properties.Add("cursor",(string)folderItems["cursor"]);
  15. We want to repeatedly call Dropbox to list more files until the “has_more” property is false. To accomplish this we will utilize a While loop in our process. In the Process Step Library, find the While step and drag it onto the designer directly under the C# step:




  16. Click the green outer portion of the While step, and in the property grid click the ellipsis button next to the Condition property:




  17. Enter the following code that checks the value of the “has_more” property, and click the Apply button:
    return (bool)context.Properties["hasMore"] == true;
  18. If the “has_more” property is true, then you need to make another call to Dropbox to get the next set of files. Inside the While step, drag another Http Client Utility, Adapter Endpoint and C# step, in this order:



  19. Double-click the Http Client Utility step and set the Method drop-down list to POST and the path to /files/list_folder/continue. Click on the Body tab and select the Raw radio button and enter the following JSON text into the body window:
    {
      "cursor": "{#context(cursor)}"
    }
    The value of the cursor property was previously saved as the context property “cursor” in the first C# step. Click the Save button:



  20. Configure the Adapter Endpoint step to use the Dropbox API adapter endpoint:



  21. Double-click the C# step and add the following code. This code is almost identical to the previous C# step:
    // Load the response into a JSON object
JObject folderItems = context.Data.ToJObject();
JArray entries = (JArray)folderItems["entries"];

// Get the previously saved oldest file
dynamic oldestFile = (JObject)context.Properties["oldestFile"];

// Check to see if there are any entries
foreach (dynamic fileInfo in entries)
{
	if (DateTime.Compare((DateTime)fileInfo.server_modified, (DateTime)oldestFile.server_modified) < 0)
	{
		oldestFile = fileInfo;
	}
}

// Save the oldest file in case there are more entries to retrieve
context.Properties["oldestFile"] = oldestFile;
context.Properties["fileToDownload"] = oldestFile.path_display;

// Set the hasMore property used by the While step
context.Properties["hasMore"] = (bool)folderItems["has_more"];

// Set the cursor for the next call
context.Properties["cursor"] = (string)folderItems["cursor"];
    Make sure you click the Apply button in the code editor after you’ve added the code!

  22. Let’s recap what we’ve built so far.  First, you create a request to get a list of files from a specific Dropbox folder. Then we parse the response to get the oldest file from the list returned. If the response’s “has_more” property is true, then we loop to get the next batch of files from the folder, also parsing the response to find the oldest one. The loop continues until “has_more” is false. Once this step is completed, we will have our oldest file and can download it.
  23. Add the following steps immediately after the While step: Http Client Utility, Adapter Endpoint and Trace:



  24. Double-click the Http Client Utility step and set the Method drop-down list to POST and the path to /files/download. On the Headers tab, add the following two Http Headers:

    Content-Type – application/octet-stream
    Dropbox-API-Arg – { “path”: “{#context(fileToDownload)}” }

    The use of #context(fileToDownload) tells the Http Client Utility to use the value of the context property “fileToDownload”, what was set in the earlier C# steps:



  25. Click on the Body tab and select the Raw radio button and check the box for Clear ESB Message Body. Since you are calling the content API, you cannot have any data in the request body:



    Click the Save button!

  26. Configure the Adapter Endpoint step to use the Dropbox Content API adapter endpoint:



  27. The final step, Trace, doesn’t require any configuration. It just outputs the content of the received file.

    Make sure to Apply and Save your changes!

Congrats! You are now ready to fully test the Business Process. If you want to make sure you’ve built the process correctly, the entire process flow can be found in the appendix.

Testing the Dropbox in API Mode

You can now test the above process using the Process Tester.

  1. Open the process tester by clicking the Test Process button in the process designer toolbar:



  2. The Edit Test Message dialog will appear. You do not need to enter or change the message body:



  3. Click the OK button, and you will see each step in the designer highlight as it is executed.
  4. The output of the test will be displayed at the bottom of the designer:

Appendix

Get Oldest File Process



About the Author

Author's Name
Joe Klug

Solution Architect, Peregrine Connect

Joe Klug is a Solution Architect for Peregrine Connect, responsible for pre-sales engineering, post-sales support, training, architectural reviews, product development and consulting. Prior to joining the team, he spent a number of years at Microsoft.

Read more about Peregrine Connect

articles

  • Rabbit MQ Topics

    Introduction Due to the open-source nature of RabbitMQ and constant updates, it is...

  • Port Sharing

    One of Neuron ESB’s scalability features is the ability to install multiple...

See All
whitepapers

  • The Integration Journey to...

    The Integration Journey to Digital Transformation with Peregrine Connect

  • Saving Time and Money by...

    Neuron ESB Application Integration and Web Service Platform: A Real-World Example...

See All
casestudies

  • Loomis Case Study

    Loomis Chooses Peregrine Connect as Their No/Low-Code Integration Platform:...

  • Elektro Gorenjska

    Peregrine Connect Eliminates Over 30% of Point-to-Point Integrations and reduces...

See All
video
  • video-icons-wrapper

    Decision Test Data Mapping

    - Use decisions to drive the execution of...

  • video-icons-wrapper

    Map Testing

    Learn how to utilize FlightPath's testing functions...

See All
© 2024 PEREGRINE CONNECT. ALL RIGHTS RESERVED. | Privacy Policy | Cookie Settings