mule-module-google-spreadsheet

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:google-spreadsheets="http://www.mulesoft.org/schema/mule/google-spreadsheets"
      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/google-spreadsheets
               http://www.mulesoft.org/schema/mule/google-spreadsheets/current/mule-google-spreadsheets.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.

OAuth2

This connector uses OAuth2 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:

    <google-spreadsheets:authorize/>

The call to authorize the message processor must be made though 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"/>
        <google-spreadsheets: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 something that requires authentication is requested but the connector is not authorized yet, the authorize message processor will be triggered. It will redirect the user to the service provider so that he can authorize the connector. This is why the authorize message processor needs to be behind an http:inbound-endpoint. Once authentication and authorization are successful, the service provider will respond to the connector with a callback. The connector will extract information from this callback, set its own internal state to authorized, and then move on to executing anything that had been interrupted by the authorization method.

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

In the above example we added the http:response-builder (keep in mind that this element is available only in Mule 3.3.0 and later). If the connector is not yet authorized, the execution of the response builder will be delayed until the callback is received.

On the other hand, if the connector had already been authorized before, then the flow execution will not be delayed; it will 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 error occurs 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"/>
      <google-spreadsheets: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>

What happens if a tenant who is not yet authorized wants to perform an OAuth protected operation? You can set this with the onNoToken property:

<google-spreadsheets:config name="google-spreadsheetss" consumerKey="${consumerKey}" consumerSecret="${consumerSecret}" onNoToken="[STOP_FLOW|EXCEPTION]">
    <google-spreadsheets:oauth-callback-config connector-ref="${oauth.http.connector}" domain="${oauth.url}" localPort="${https.port}" async="false" path="oauth2callback" />
</google-calendars:config-with-oauth>

The onNoToken property can be set to two different values:

• STOP_FLOW: acts as a filter and kills the execution of the flow
• EXCEPTION: throws an exception informing that the token is still not acquired

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 must call:

    <google-spreadsheets: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:

    <google-spreadsheets:config>
        <google-spreadsheets:oauth-callback-config domain="${fullDomain}" localPort="${http.port}" remotePort="80" defaultAccessTokenId="#[message.inboundProperties['tenantId']]" />
    </google-spreadsheets: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.

Access Token Store

This connector has the capability of automatically saving and restoring access tokens. The connector will store in either the default user object store or a user-defined one the acquired access tokens, refresh tokens, and any other pertinent information using the access token identifier as the key.

The object store can be configured as follows

    <google-spreadsheets:config>
        <google-spreadsheets:oauth-store-config objectStore-ref="my-object-store"/>
    </google-spreadsheets:config>

There is only a single attribute entitled objectStore-ref in the oauth-store-config element that allows the user to specify the name of the object store that he wishes to use to save and restore access tokens.

Another important aspect of the token store is the ids. This connector supports multi-tenancy, which means that each instance of this connector is capable of supporting multiple concurrent users. Therefore, each access token is given an id to identify the owning tenant.

By default, the connector's config name is used the access token id. Also, by default, at the time of using a protected operation, it's not mandatory to provide an accessTokenId since the config's name will also be used by default.

This defaults are fine for the single-tenant case or for CloudHub enabled multi-tenancy. If you are running on-premise or you are not using Cloudhub's multi-tenancy mode, there are a couple of ways in which you can easily handle your token ids manually.

First, you can specify a defaultAccessTokenId on the connector's callback element. Each time a callback is received, that expression will get evaluated and the resulting value will be used as the token id. At the same time, when using a protected operation that expression will be evaluated to obtain the id of the access token to fetch.

Another option is to use to provide an accessTokenId expression on the authorize processor. If you do so, the expression's result will be used as the token id instead. Notice that if you choose to force the token id like this, then you also need to provide a matching accessTokenId expression on each protected operation that uses that token.

Message Processors

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

Message Sources

Transformers