mule-module-dropbox

Configuration

To use the this module within a flow the namespace to the module must be included. The resulting flow will look similar to the following:

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:dropbox="http://www.mulesoft.org/schema/mule/dropbox"
      xsi:schemaLocation="
               http://www.mulesoft.org/schema/mule/core
               http://www.mulesoft.org/schema/mule/core/current/mule.xsd
               http://www.mulesoft.org/schema/mule/dropbox
               http://www.mulesoft.org/schema/mule/dropbox/current/mule-dropbox.xsd">

      <!-- here goes your flows and configuration elements -->

</mule>

This module is configured using the config element. This element must be placed outside of your flows and at the root of your Mule application. You can create as many configurations as you deem necessary as long as each carries its own name.

Each message processor, message source or transformer carries a config-ref attribute that allows the invoker to specify which configuration to use.

OAuth

This connector uses OAuth as an authorization and authentication mechanism. All the message processors or sources that require the connector to be authorized by the service provider will throw a NotAuthorizedException until the connector is authorized properly.

Authorizing the connector is a simple process of calling:

    <dropbox:authorize/>

The call to authorize message processor must be made from a message coming from an HTTP inbound endpoint as the authorize process will reply with a redirect to the service provider. The following is an example of how to use it in a flow with an HTTP inbound endpoint:

    <flow name="authorizationAndAuthenticationFlow">
        <http:inbound-endpoint host="localhost" port="8080" path="oauth-authorize"/>
        <dropbox:authorize/>
    </flow>

If you hit that endpoint via a web-browser it will initiate the OAuth dance, redirecting the user to the service provider page and creating a callback endpoint so the service provider can call us back once the user has been authenticated. Once the callback gets called then the connector will switch to an authorized state and any message processor or source that requires authentication can be called.

The authorize message processor supports the following attributes:

After Authorization

The authorize message processor is an intercepting one. If the connector is not authorized yet, it will with a redirect to the service provider so the user can authorize the connector. This is the reason as to why the authorize needs to be behind and http:inbound-endpoint. The service provider upon successful authentication and authorization then will call back the connector. The connector will extract information from that call, set its internal state to authorized, and then continue execution. When we say continue execution we mean executing everything that was after the authorize whose execution got interrupted because the connector was not authorized.

  <flow name="authorizationAndAuthenticationFlow">
      <http:inbound-endpoint host="localhost" port="8080" path="oauth-authorize"/>
      <dropbox:authorize/>
      <http:response-builder status="200">
          <set-payload value="You have successfully authorized the connector"/>
      </http:response-builder>
  </flow>

In the previous example we added the http:response-build (notice that this element is available only in Mule 3.3.0 and later). If the connector is not authorized, the execution of the response builder will be delayed up to the point of the callback execution.

On the other hand if the connector has been authorized and you call authorize again then the flow execution will not stop, it will rather continue and the http:response-builder will get executed right away rather than after the callback.

Error Handling during Authorization

If for any reason, an errors ocurrs while processing the callback, the exception strategy of the flow containing the authorize will be executed. So, if the callback sent the wrong information you can handle that situation by setting up an exception strategy as follows:

  <flow name="authorizationAndAuthenticationFlow">
      <http:inbound-endpoint host="localhost" port="8080" path="oauth-authorize"/>
      <dropbox:authorize/>
      <http:response-builder status="200">
          <set-payload value="You have successfully authorized the connector"/>
      </http:response-builder>
      <catch-exception-strategy>
         <http:response-builder status="404">
             <set-payload value="An error has occurred authorizing the connector"/>
         </http:response-builder>
      </catch-exception-strategy>
  </flow>

Unauthorize

Once this connector has been authorized further calls to the authorize message processor will be no-ops. If you wish to reset the state of the connector back to a non-authorized state you can call:

    <dropbox:unauthorize/>

Keep in mind that after the connector is unauthorized all future calls that attempt to access protected resources will fail until the connector is re-authorized.

Callback Customization

As mentioned earlier once authorize gets called and before we redirect the user to the service provider we create a callback endpoint. The callback endpoint will get called automatically by the service provider once the user is authenticated and he grants authorization to the connector to access his private information.

The callback can be customized in the config element of the this connector as follows:

    <dropbox:config>
        <dropbox:oauth-callback-config domain="${fullDomain}" localPort="${http.port}" remotePort="80"/>
    </dropbox:config>

The oauth-callback-config element can be used to customize the endpoint that gets created for the callback. It features the following attributes:

The example shown above is what the configuration would look like if your app would be deployed to CloudHub.

Saving and Restoring State

Once the service providers hits the callback it will do so in way that state information it is also sent. This state information is later used by the connector on each call made to the service provider to let him know that we have completed the authorization and authentication process.

The state information is currently held in-memory but the connector offers hooks to save/restore this state. The ammount of information that needs to be saved and/or restored varies between version of the OAuth specification. At the bare minimum for OAuth 1.0a that needs to be the OAuth access token and OAuth access token secret.

The following is an example of how to log the access token and access token secret.

    <dropbox:config>
        <dropbox:oauth-save-access-token>
            <logger level="INFO" message="Received access token #[variable:OAuthAccessToken] and #[variable:OAuthAccessTokenSecret]"/>
        </dropbox:oauth-save-access-token>
    </dropbox:config>

The oauth-save-access-token is a message processor chain and you can add inside of it as many message processors as you want. The chain will be called with special inbound properties in the message which the information that needs saved.

Restoring the information is equally simple:

    <dropbox:config>
        <dropbox:oauth-restore-access-token>
            <message-properties-transformer scope="invocation">
                <add-message-property key="OAuthAccessToken" value="123"/>
                <add-message-property key="OAuthAccessTokenSecret" value="567"/>
            </message-properties-transformer>
        </dropbox:oauth-restore-access-token>
    </dropbox:config>

The example above does not do anything useful expect hardcode the access token and the token secret to 123 and 567 respectively. Just like oauth-save-access-token, oauth-restore-access-token is another message processor chain. Once the chain is done executing we will extract the OAuth access token property and OAuth access token secret property values.

The following shows a full example on how to save and restore using Mule ObjectStore Module to store the information inside an object store.

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:dropbox="http://www.mulesoft.org/schema/mule/dropbox"
      xmlns:objectstore="http://www.mulesoft.org/schema/mule/objectstore"
      xsi:schemaLocation="
               http://www.mulesoft.org/schema/mule/core
               http://www.mulesoft.org/schema/mule/core/current/mule.xsd
               http://www.mulesoft.org/schema/mule/objectstore
               http://www.mulesoft.org/schema/mule/objectstore/1.0/mule-objectstore.xsd
               http://www.mulesoft.org/schema/mule/dropbox
               http://www.mulesoft.org/schema/mule/dropbox/current/mule-dropbox.xsd">

    <dropbox:config>
        <dropbox:oauth-save-access-token>
            <objectstore:store key="OAuthAccessToken" value-ref="#[variable:OAuthAccessToken]"/>
            <objectstore:store key="OAuthAccessTokenSecret" value-ref="#[variable:OAuthAccessTokenSecret]"/>
        </dropbox:oauth-save-access-token>
        <dropbox:oauth-restore-access-token>
            <enricher target="#[header:OAuthAccessToken]">
                <objectstore:retrieve key="OAuthAccessToken"/>
            </enricher>
            <enricher target="#[header:OAuthAccessTokenSecret]">
                <objectstore:retrieve key="OAuthAccessTokenSecret"/>
            </enricher>
        </dropbox:oauth-restore-access-token>
    </dropbox:config>

</mule>

Message Processors

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

Message Sources

Transformers