DropBox Connector - Source Code

<?xml version="1.0" encoding="utf-8"?>
<ApiConfig Name="DropBox"
           Slug="dropbox-connector"
           Id="4D4D2932-C955-4A3A-AB78-F7A3A70B2797"
		 Version="1"
           EngineVersion="4"
           Desc="Read / write DropBox data inside your app; perform many DropBox operations without coding, just use easy to use high performance API Connector for DropBox"
           Logo="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAMAAABHPGVmAAAAAXNSR0IArs4c6QAAAWhQTFRFAAAAAAD/AICAAID/AKr/AID/AG3bAIDfAHHjAHToAIvoAIDVAIDqAHbrAIDtAHfuAIDvAHjhAIDjAIDmAHnnAIDqAHrgAHrrAIDrAHvlAH/mAITmAIDpAIDjAIDqAIDkAH3hAIDoAH3jAIDpAH3kAIDqAIDmAIDnAH7kAIDmAH7nAH7lAH3nAH7lAIDmAH7nAH3lAH7lAIDoAH3kAH7mAIDmAH3lAH7lAHzmAH3mAH3lAH3nAH7nAH7lAH3mAH/mAH7mAH/mAH3lAH3lAH/nAH7nAH/mAH3lAH/nAH7lAH7nAH3mAH7mAH3mAH7mAH7nAH3mAH7mAH7mAH7mAH7mAH7mAH7mAH7mAH7lAH7lAH7lAH7mAH7mAH7mAH7mAH7mAH7mAH7mAH7lAH7mAH7mAH7nAH7mAH7mAH7lAH7lAH7mAH7mAH7nAH3mAH7mAH7mAH3lAH3mAH7nAH7mAH3mAH7mAH7mAH7miZZsagAAAHd0Uk5TAAECAgMGBwgJCwsMDA0ODxAREhQVGBkZGh0eHyIkJCYrLC0uLzA0QEFIS09eY2hrbG1ucHFydnd7fH5+f4CDg4SHi5GTlJmdnZ6go6SvsLK1trrAwcLDxcbHyM7P1dnd3+Di4uPm6ezt7+/x8fLy9/j6+vv8/P7DVvC6AAACPUlEQVQYGe3B66MUcwCA4VdS5BROwukinByXEKIbIbcIRyRFopQISdf33292z7a7szO/y8zufpvnodPpdDodJEqm95b6KGHqS0zJvo8JeMI+pvG1A3eodcSBo7TmGGpcd4R2TllChSVf0oKTFihzEk39YdWHjHnYql9pxFrXGHrTWuT7zxAG/jbgCnk2G0GfERvIYNyDgHGkPGPK/nWmPEmUaS9gGmE7TbpC4QOTlgkzgQETnibGmLcZWjSGBMMouWgQSZ9bjwrr/UKGBWucpsZr1thJHisIsIJslq0QtN4yGvjJkb+IOunIBRp5yvtI8r7naMq+Q2TYYx8tWCDTvyqtnH+AfJdoR8mmtLHLwidkOWjhDRo75xoyuOYaDTlCwnWHaMRxrxCx5DjyPe4EgpzwMpl+sOIitVat+JMs1lqiylpkMIQJhpCyYNhXjHnVsBeJOm4UQ0ZdJsIk+n43hTDTXodHTPqfGGeChMsmwF3jfiPNmBsUPjWGLGcN+gzYDksGnSGXAYvwrH4DGEADh60D/GwPYJ1jNGMV4ABgFY3ttewW4BDwvWX7aMNxHwGO2Q3PO46Wtjm0AbZZ8h3g0DLtOQCccBLgAFN5yB7gplWAPUtMQQqX/AewFnDa2xSu0pZ+yxoDdtC3VWnLAoWNBn1BwQJt2XOe94xhxR7asgFaO2kupmEWprTFpPeZ3qpRd5kNI5iZRQMOMEs/WodZs4I52GTJO8zHOUeYHweYq8csvMu8nZFOp9PpdCbcAxbhkwz5LUNBAAAAAElFTkSuQmCC"
           TrustedDomains="content.dropboxapi.com"
           >

    <VersionHistory>
        <Change Date="2024-12-04" Type="New">Added images in OAuth authentication instructions</Change>      
        <Change Date="2021-11-26">Initial version</Change>
    </VersionHistory>
    <ServiceUrls>
    <ServiceUrl Name="Version 2" Url="https://api.dropboxapi.com/2/" />
  </ServiceUrls>
    <Auths>
    <Auth Name="OAuth" Label="User Account" HelpLink="https://zappysys.com/links/?id=10002"
          Type="OAuth" ConnStr="Provider=DropBox;ExtraAttributesForAuthRequest=token_access_type=offline;ScopeSeparator={space};ReturnUrl=[$ReturnUrl$]"
          TestEndPoint="make_test"
      >
      <Notes>
        <![CDATA[
<p>To use OAuth authentication, firstly, you need to create OAuth application:</p>
<ol>
    <li>Log into your DropBox account.</li>
    <li>Go to DropBox <a target="_blank" href="https://www.dropbox.com/developers/apps">My Apps</a>.</li>    
    <li>
        Then press <strong>Create app</strong> button to create a new app:    
        
        <img src="https://cdn.zappysys.com/api/images/authentication/dropbox/OAuth/my-oauth-apps-in-dropbox.png"
             loading="lazy"
             decoding="async"
             class="img-thumbnail block"
             alt="My OAuth apps in Dropbox"
             title="My OAuth Apps in Dropbox"
             width="900"
             height="1300" />                        
    </li>
    
    <li>
        Once a new page opens, select <strong>Scoped access</strong> option:
    
        <img src="https://cdn.zappysys.com/api/images/authentication/dropbox/OAuth/create-oauth-app-to-get-dropbox-rest-api-data.png"
             loading="lazy"
             decoding="async"
             class="img-thumbnail block"
             alt="Create OAuth app to get Dropbox REST API data"
             title="Creating OAuth app to get Dropbox REST API data"
             width="900"
             height="1000" />        
    </li>
    
    <li>
        Next, select <strong>Full Dropbox</strong> to access all files and folders or <strong>App folder</strong> to access specific folder's files and folders option.
    </li>
    <li>
        Continue by giving your app a name.
    </li>
    <li>
        Then check <strong>I agree to Dropbox API Terms and Conditions</strong> checkbox.
    </li>
    <li>
        Click <strong>Create app</strong> button.
    </li>            
    <li>
        Once a new page opens, click <strong>Enable additional teams</strong> and <strong>Enable additional users</strong> buttons:
        
        <img src="https://cdn.zappysys.com/api/images/authentication/dropbox/OAuth/configure-oauth-app-in-dropbox.png"
             loading="lazy"
             decoding="async"
             class="img-thumbnail block"
             alt="Configure OAuth app in Dropbox"
             title="Configuring OAuth app in Dropbox"
             width="900"
             height="1130" />
    </li>    
    <li>
        Then copy <strong>App key</strong> and <strong>App secret</strong> and copy paste them into your favorite text editor (you will need them later).
    </li>    
    <li>
        Proceed by setting a <strong>Redirect URI</strong> and clicking <strong>Add</strong> button. 
        <p>
            <strong>NOTE:</strong>
            If you don't have a working Redirect URI, you can use <code>https://zappysys.com/oauth</code> (it's safe).
        </p>
    </li>    
    <li>
        Then click on <strong>Permissions</strong> tab and select application scopes:
        
        <img src="https://cdn.zappysys.com/api/images/authentication/dropbox/OAuth/set-oauth-app-permissions-in-dropbox.png"
             loading="lazy"
             decoding="async"
             class="img-thumbnail block"
             alt="Set OAuth app permissions in Dropbox"
             title="Setting OAuth app permissions in Dropbox"
             width="900"
             height="1300" />        
    </li>            
    <li>
        Select all <strong>Individual Scopes</strong> and <strong>Team Scopes</strong> if you want to manage team data.
    </li>       
    <li>
        Click <strong>Submit</strong> button.
    </li>
    <li>
        Now go to SSIS package or ODBC data source and in <strong>User Account</strong> authentication set these parameters:</ol>
        <ol>
            <li>For <strong>ClientId</strong> field use <strong>App key</strong> value.</li>
            <li>For <strong>ClientSecret</strong> field use <strong>App secret</strong> value.</li>
            <li>For <strong>ReturnUrl</strong> field use <strong>Redirect URI</strong>   value.</li>
        </ol>
    </li>    
    <li>
        Done! Now you are ready to use Dropbox Connector!
    </li>    
</ol>

<div style="background-color: #f5f2c4; border-style: solid; border-color: #000000; border-width: 1px; margin-top: 3px; margin-bottom: 6px; padding: 6px;">
    <strong>NOTE:</strong>
    
    If you are planning to use your current data connection/token for automated processes, 
    we recommend that you use a generic account for token generation when the login box appears (e.g. sales_automation@mycompany.com instead of bob_smith@mycompany.com). 
    When you use a personal account which is tied to a specific employee profile and that employee leaves the company, 
    the token may become invalid and any automated processes using that token will fail. 
    Another potentially unwanted effect of using a personal token is incorrect logging; 
    the API calls (e.g. Read, Edit, Delete, Upload) made with that token will record the specific user as performing the calls instead of an automated process.
</div>
        ]]>
		
      </Notes>
      <Params>
        <Param Name="UseCustomApp" Value="True" Required="True" Hidden="False" Desc="Use your own app credentials or inbuilt app provided by ZappySys for ease of use. If you choose UseCustomApp=true then make sure to obtain your own ClientId and Secret using steps provided (Click [Steps to Configure] link found next to Authentication Type dropdown)" />
        <Param Name="ClientId" VisibleIf="UseCustomApp" RequiredIf="UseCustomApp"/>
        <Param Name="ClientSecret" Secret="True" VisibleIf="UseCustomApp" RequiredIf="UseCustomApp" />
        <Param Name="Scope" Value=""/>
        <Param Name="ReturnUrl" Value="https://zappysys.com/oauth" Required="True"/>
        <Param Name="RetryMode" Value="RetryWhenStatusCodeMatch" Options="None;RetryAny;RetryWhenStatusCodeMatch;" Hidden="True" />
        <Param Name="RetryStatusCodeList" Value="429" Hidden="True" />
        <Param Name="RetryCountMax" Value="5" Hidden="True" />
        <Param Name="RetryMultiplyWaitTime" Value="True" Hidden="True" />   		
      </Params>
    </Auth>
  </Auths>


  <Template>
  </Template>

  <EndPoints>
    <!--=====================================
        =============== TEST ================
        =====================================-->
    <EndPoint Name="make_test" Label="Make connection test" Desc="Makes a connection test"
	            Url="/check/user" Method="POST" ContentType="application/json"
              >
      <Body>
        { "query": "Test successful!"}
      </Body>
      <OutputColumns>
        <Column Name="result" Label="Result" DataType="DT_WSTR" Length="4000"/>
      </OutputColumns>
    </EndPoint>

    <!--=====================================
        ============ LIST FOLDER ============
        =====================================-->
    <EndPoint Name="list_folder" Label="List folder" Desc="Lists folder"
	            Url="/files/list_folder[$tag$]" Method="POST" ContentType="application/json" Filter="$.entries[*]"
    >
      <Params>
        <Param Name="Path" Value="" />
        <Param Name="Recursive" Value="false" Options="true;false" />
        <Param Name="FirstPageBodyPart" Type="Property" Value="{}" ValueTemplate="{ &quot;path&quot;: &quot;[$Path$]&quot;, &quot;recursive&quot;: [$Recursive$], &quot;limit&quot;: 200 }" />
        <Param Name="NextPageBodyPart" Type="Property" Value="{}" ValueTemplate="{ &quot;cursor&quot;: &quot;[$pagetoken$]&quot; }" />
        <Param Name="Filter" Type="Property" Value="$.entries[*]" Required="true" Options="All types=$.entries[*];
                                                                                           Files=$.entries[?(@['.tag']=='file')];
                                                                                           Folders=$.entries[?(@['.tag']=='folder')]" />
        <Param Name="NextUrlAttributeOrExpr" Type="Property" Value="$.cursor" />
        <Param Name="StopIndicatorAttributeOrExpr" Type="Property" Value="$.has_more" />
        <Param Name="NextUrlEndIndicator" Type="Property" Value="false" />
        <Param Name="EnablePageTokenForBody" Type="Property" Value="True" />
        <Param Name="HasDifferentNextPageInfo" Type="Property" Value="True" />
        <Param Name="PagePlaceholders" Type="Property" Value="url=|/continue" />
      </Params>
      <Body>[$tag$]</Body>
      <OutputColumns>
        <Column Name="id" Label="Id" DataType="DT_WSTR" Length="4000"/>
        <Column Name="name" Label="Name" DataType="DT_WSTR" Length="4000"/>
        <Column Name=".tag" Label="Type" DataType="DT_WSTR" Length="4000"/>
        <Column Name="path_lower" Label="PathLower" DataType="DT_WSTR" Length="4000"/>
        <Column Name="path_display" Label="PathDisplay" DataType="DT_WSTR" Length="4000"/>
        <Column Name="client_modified" Label="ClientModified" DataType="DT_DBTIMESTAMP"/>
        <Column Name="server_modified" Label="ServerModified" DataType="DT_DBTIMESTAMP"/>
        <Column Name="rev" Label="Revision" DataType="DT_WSTR" Length="4000"/>
        <Column Name="size" Label="Size" DataType="DT_I8"/>
        <Column Name="is_downloadable" Label="IsDownloadable" DataType="DT_BOOL"/>
        <Column Name="content_hash" Label="ContentHash" DataType="DT_WSTR" Length="4000"/>
      </OutputColumns>
    </EndPoint>

    <!--=====================================
        ========== DOWNLOAD FILE ============
        =====================================-->
    <EndPoint Name="download_file" Label="Download a file" Desc="Downloads a file"
	            Url="https://content.dropboxapi.com/2/files/download" Method="POST" ContentType="text/plain" Filter="$"
    >
      <Params>
        <Param Type="Header"
               Key="Dropbox-API-Arg"
               Name="SourceFilePath"
               Value=""
               ValueTemplate="{ &quot;path&quot;: &quot;{$value$}&quot; }"
               OptionsEndPoint="list_folder"
               OptionsEndPointValueColumn="Id"
               OptionsEndPointLabelColumn="Name"
               OptionEndPointParameters="Path=;Recursive=true;Filter=$.entries[?(@['.tag']=='file')]"
               Required="True"
               />
        <Param Name="SaveContentAsBinary"
               Required="True"
               Type="Property"
               Hidden="True"
               Value="True"
              />
        <Param Name="RequestTimeoutMs"
               Type="Property"
               Desc="Timeout in milliseconds after which download stops"
               Value="7200000"
              />
        <Param Name="FileOverwriteMode" Type="Property" Value="AlwaysOverwrite" Required="True"/>
        <Param Name="ResponseDataFile" Desc="Specify a disk file path to save file as" Required="True"
               Type="Property" Value="c:\ParentFolder\Subfolder\file.dat" Editor="FileSave" />
        <Param Name="RawOutputDataRowTemplate" Type="Property" Value="{Status:'Downloaded'}" />
        <Param Name="EnableRawOutputModeSingleRow" Type="Property" Value="True" />
      </Params>
      <OutputColumns>
        <Column Name="Status" DataType="DT_WSTR" />
      </OutputColumns>
    </EndPoint>

    <!--======================================
        ========== DOWNLOAD FOLDER ===========
        ======================================-->
    <EndPoint Name="download_folder" Label="Download a folder and folders/files within as ZIP archive" Desc="Downloads a folder with all the files and folders it contains as ZIP file"
	            Url="https://content.dropboxapi.com/2/files/download_zip" Method="POST" ContentType="text/plain" Filter="$"
    >
      <Params>
        <Param Type="Header"
               Key="Dropbox-API-Arg"
               Name="SourcePath"
               Value=""
               ValueTemplate="{ &quot;path&quot;: &quot;{$value$}&quot; }"
               OptionsEndPoint="list_folder"
               OptionsEndPointValueColumn="Id"
               OptionsEndPointLabelColumn="Name"
               OptionEndPointParameters="Path=;Recursive=true;Filter=$.entries[?(@['.tag']=='folder')]"
               Required="True"
               />
        <Param Name="SaveContentAsBinary"
               Required="True"
               Type="Property"
               Hidden="True"
               Value="True"
              />
        <Param Name="RequestTimeoutMs"
               Type="Property"
               Desc="Timeout in milliseconds after which download stops"
               Value="7200000"
              />
        <Param Name="FileOverwriteMode" Type="Property" Value="AlwaysOverwrite" Required="True"/>
        <Param Name="ResponseDataFile" Desc="Specify a disk file path to save file as" Required="True" Type="Property" Value="c:\ParentFolder\Subfolder\file.zip" Editor="FileSave" />
        <Param Name="RawOutputDataRowTemplate" Type="Property" Value="{Status:'Downloaded'}" />
        <Param Name="EnableRawOutputModeSingleRow" Type="Property" Value="True" />
      </Params>
      <OutputColumns>
        <Column Name="Status" DataType="DT_WSTR" />
      </OutputColumns>
    </EndPoint>

    <!--=====================================
        ============ UPLOAD FILE ============
        =====================================-->
    <EndPoint Name="upload_file" Label="Upload a file" Desc="Upload a file"
	            Url="https://content.dropboxapi.com/2/files/upload" Method="POST" ContentType="application/octet-stream" Filter="$"
    >
      <Params>
        <Param Type="Header"
               Key="Dropbox-API-Arg"
               Name="TargetFilePath"
               Desc="Specify a file path in DropBox to save file to"
               Value=""
               ValueTemplate="{ &quot;path&quot;: &quot;{$value$}&quot; }"
               Required="True"
               />
        <Param Name="SourceFilePath"
               Required="True"
               Type="Placeholder"
               Desc="Specify a disk file path to upload"
               Example="C:\MyParentFolder\Subfolder\file.txt"
               Editor="FileOpen"
               Value=""
              />
        <Param Name="IsMultiPart"
               Required="True"
               Type="Property"
               Hidden="True"
               Desc="Must be set to 'True'"
               Value="True"
        />
      </Params>
      <Body>
        <![CDATA[@[$SourceFilePath$]]]>
      </Body>
      <OutputColumns>
        <Column Name="id" Label="Id" DataType="DT_WSTR" Length="4000"/>
        <Column Name="name" Label="Name" DataType="DT_WSTR" Length="4000"/>
        <Column Name="path_lower" Label="PathLower" DataType="DT_WSTR" Length="4000"/>
        <Column Name="path_display" Label="PathDisplay" DataType="DT_WSTR" Length="4000"/>
        <Column Name="client_modified" Label="ClientModified" DataType="DT_DBTIMESTAMP"/>
        <Column Name="server_modified" Label="ServerModified" DataType="DT_DBTIMESTAMP"/>
        <Column Name="rev" Label="Revision" DataType="DT_WSTR" Length="4000"/>
        <Column Name="size" Label="Size" DataType="DT_I8"/>
        <Column Name="is_downloadable" Label="IsDownloadable" DataType="DT_BOOL"/>
        <Column Name="content_hash" Label="ContentHash" DataType="DT_WSTR" Length="4000"/>
      </OutputColumns>
    </EndPoint>

    <!--===========================================
        ============== CREATE FOLDER ==============
        ===========================================-->
    <EndPoint Name="create_folder" Label="Create folder" Desc="Creates folder"
	            Url="/files/create_folder_v2" Method="POST" ContentType="application/json" Filter="$.metadata"
    >
      <Params>
        <Param Name="Path" Value="" />
      </Params>
      <Body>
        { "path": "[$Path$]" }
      </Body>
      <OutputColumns>
        <Column Name="id" Label="Id" DataType="DT_WSTR" Length="4000"/>
        <Column Name="name" Label="Name" DataType="DT_WSTR" Length="4000"/>
        <Column Name="path_lower" Label="PathLower" DataType="DT_WSTR" Length="4000"/>
        <Column Name="path_display" Label="PathDisplay" DataType="DT_WSTR" Length="4000"/>
      </OutputColumns>
    </EndPoint>

    <!--=====================================
        ============== DELETE ===============
        =====================================-->
    <EndPoint Name="delete" Label="Delete" Desc="Deletes file or folder"
	            Url="/files/delete_v2" Method="POST" ContentType="application/json" Filter="$.metadata"
    >
      <Params>
        <Param Name="Path" Value="" />
      </Params>
      <Body>
        { "path": "[$Path$]" }
      </Body>
      <OutputColumns>
        <Column Name="id" Label="Id" DataType="DT_WSTR" Length="4000"/>
        <Column Name="name" Label="Name" DataType="DT_WSTR" Length="4000"/>
        <Column Name="path_lower" Label="PathLower" DataType="DT_WSTR" Length="4000"/>
        <Column Name="path_display" Label="PathDisplay" DataType="DT_WSTR" Length="4000"/>
        <Column Name="client_modified" Label="ClientModified" DataType="DT_DBTIMESTAMP"/>
        <Column Name="server_modified" Label="ServerModified" DataType="DT_DBTIMESTAMP"/>
        <Column Name="rev" Label="Revision" DataType="DT_WSTR" Length="4000"/>
        <Column Name="size" Label="Size" DataType="DT_I8"/>
        <Column Name="is_downloadable" Label="IsDownloadable" DataType="DT_BOOL"/>
        <Column Name="content_hash" Label="ContentHash" DataType="DT_WSTR" Length="4000"/>
      </OutputColumns>
    </EndPoint>
  </EndPoints>

  <!--=====================================
      ============ EXAMPLES ===============
      =====================================-->
  <Examples>
    <!-- TEST CONNECTION -->
    <Example Group="ODBC" Label="Test connection" Desc="Tests connection">
      <Code>
        <![CDATA[SELECT *
  FROM make_test]]>
      </Code>
    </Example>

    <!-- LIST FOLDER -->
    <Example Group="ODBC" Label="List folder #1" Desc="Lists all files and folders within a folder">
      <Code>
        <![CDATA[SELECT *
  FROM list_folder]]>
      </Code>
    </Example>
    <Example Group="ODBC" Label="List folder #2" Desc="Lists all files and folders within a folder">
      <Code>
        <![CDATA[SELECT *
  FROM list_folder
  WITH (Path='/MySubfolder'
       ,Recursive='true')]]>
      </Code>
    </Example>

    <!-- DOWNLOAD FILE -->
    <Example Group="ODBC" Label="Download file" Desc="Downloads a file">
      <Code>
        <![CDATA[SELECT *
  FROM download_file
  WITH (SourceFilePath='/file-I-want-to-download.dat'
        ,ResponseDataFile='C:\path\I\want\to\save\my\file\to.dat'
      )]]>
      </Code>
    </Example>

    <!-- DOWNLOAD FOLDER -->
    <Example Group="ODBC" Label="Download folder as ZIP file" Desc="Downloads a folder with all files and folders within it as ZIP file">
      <Code>
        <![CDATA[SELECT *
  FROM download_folder
  WITH (SourcePath='/folder-I-want-to-download'
        ,ResponseDataFile='C:\path\I\want\to\save\my\folder\to.zip'
      )]]>
      </Code>
    </Example>

    <!-- UPLOAD FILE -->
    <Example Group="ODBC" Label="Upload a file" Desc="Uploads a file">
      <Code>
        <![CDATA[SELECT *
  FROM upload_file
  WITH (TargetFilePath='/MySubfolder/file-I-want-to-upload-to-dropbox.dat'
        ,DiskFilePath='C:\file\I\want\to\upload.dat'
      )]]>
      </Code>
    </Example>

    <!-- DELETE FILE/FOLDER -->
    <Example Group="ODBC" Label="Delete a file or a folder" Desc="Deletes a file or a folder">
      <Code>
        <![CDATA[SELECT *
  FROM delete
  WITH (Path='/path/to/file/in/dropbox/I/want/to/delete.dat')]]>
      </Code>
    </Example>

    <!-- CREATE FOLDER -->
    <Example Group="ODBC" Label="Create a folder" Desc="Creates a folder">
      <Code>
        <![CDATA[SELECT *
  FROM create_folder
  WITH (Path='/folder/in/dropbox/I/want/to/create')]]>
      </Code>
    </Example>
  </Examples>
</ApiConfig>