mule-module-gmail

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:gmail="http://www.mulesoft.org/schema/mule/gmail"
      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/gmail
               http://www.mulesoft.org/schema/mule/gmail/current/mule-gmail.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 with automatic saving and restoring of access tokens. Every message processor in this connector has an extra attribute entitled accessTokenId which is an identification of the user authorizing the conenctor. In order to obtain an access token identification you need to first call the authroize message processor.

Authorizing the connector is a simple process of calling:

    <gmail: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"/>
        <gmail: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 redirect back once the user has been authenticated and properly authorized the connector. Once the callback gets called then the connector will automatically issue an access token identifier that you need to save as either a cookie or a database record for any subsequent calls.

The authorize message processor also supports the following attributes:

After Authorization

The authorize message processor is an intercepting one. If the connector is not authorized yet, it will 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. Continuing execution means 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"/>
      <gmail: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.

The following is an example of the authorize message processor, after which it will print the access token identifier to the log:

    <flow name="authorizationAndAuthenticationFlow">
        <http:inbound-endpoint host="localhost" port="8080" path="oauth-authorize"/>
        <gmail:authorize/>
		<log level="INFO" message="The connector has been properly authorized. The access token identifier is #[flowVars['OAuthAccessTokenId']]"/>
    </flow>

The OAuthAccessTokenId flow variable is a special variable available to all the message processors executing after the authorize call. The following snippet shows how you can save it as a HTTP protocol cookie:

    <flow name="authorizationAndAuthenticationFlow">
        <http:inbound-endpoint host="localhost" port="8080" path="oauth-authorize"/>
        <gmail:authorize/>
        <http:response-builder status="200">
            <http:set-cookie name="accessTokenId" value="#[flowVars['OAuthAccessTokenId']]"/>
            <set-payload value="You have successfully authorized the connector. You access token id is #[flowVars['OAuthAccessTokenId']]"/>
        </http:response-builder>
    </flow>

The access token identifier is unique per user and therefore the connector can be authorized for many users. If the user authorizes the connector twice it will have the same access token identifier both times.

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"/>
      <gmail: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:

    <gmail: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:

    <gmail:config>
        <gmail:oauth-callback-config domain="${fullDomain}" localPort="${http.port}" remotePort="80"/>
    </gmail: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

    <gmail:config>
        <gmail:oauth-store-config objectStore-ref="my-object-store"/>
    </gmail: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.

Message Processors

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

Message Sources

Transformers