mule-module-google-calendar

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-calendars="http://www.mulesoft.org/schema/mule/google-calendars"
      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-calendars
               http://www.mulesoft.org/schema/mule/google-calendars/current/mule-google-calendars.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 with automatic saving and restoring of access tokens. Every message processor in this connector keeps track of an attribute called accessTokenId which identifies each of the users that were authorized by the connector. In order to obtain an access token identification you need to first call the authorize message processor.

Authorizing the connector is a simple process of calling:

    <google-calendars: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-calendars: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. It will also create a callback endpoint so the service provider can redirect the user back once the user has been authenticated and properly authorized. Once the callback gets called the connector will automatically issue an access token identifier that will be stored in an ObjectStore. By default, this ObjectStore's OauthAccessTokenId will be the connector's config name.

The authorize message processor also supports the following attributes:

When dealing with multi-tenant on-premise implementations, leaving the accessTokenId parameter in the authorize message processor to it's default value could lead to token overwriting. This is not a problem when running on CloudHub, but can be a serious issue when running on-premise. In these cases it is recommended to set the parameter to:

    <google-calendars:authorize accessTokenId="#[flowVars['myTenantId']]"/>

If you do this, keep in mind that message processors will still be searching for the default OauthAccessTokenId unless told differently. You must then overwrite this property on message processors as well:

    <google-calendars:get-events accessTokenId="[flowVars['myTenantId']]"/>

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-calendars: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.

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

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

The OAuthAccessTokenId flow variable is stored into an ObjectStore by default. As an alternative, 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"/>
        <google-calendars: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 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-calendars: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-calendars:config-with-oauth name="google-calendars" consumerKey="${google.apiclient}" consumerSecret="${google.apisecret}" onNoToken="[STOP_FLOW|EXCEPTION]">
    <google-calendars: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

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.

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-calendars: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-calendars:config>
        <google-calendars:oauth-callback-config domain="${fullDomain}" localPort="${http.port}" remotePort="80"/>
    </google-calendars: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-calendars:config>
        <google-calendars:oauth-store-config objectStore-ref="my-object-store"/>
    </google-calendars: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

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

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

INCLUDE_ERROR

Message Sources

Transformers