org.mule.modules

mule-module-google-tasks

config-with-oauth

Namespacehttp://www.mulesoft.org/schema/mule/google-tasks
Schema Locationhttp://www.mulesoft.org/schema/mule/google-tasks/current/mule-google-tasks.xsd  (View Schema)
Schema Version1.0
Minimum Mule Version3.5

Module Overview

Google Tasks Cloud connector. This connector covers almost all the Google Tasks API v3 using OAuth2 for authentication.

Summary

Configuration
<google-tasks:config-with-oauth>
Configure an instance of this module
Message Processors
<google-tasks:clear-tasks>
Clears all completed tasks from the specified task list.
<google-tasks:delete-task>
Deletes the specified task from the task list.
<google-tasks:delete-task-list>
Deletes the authenticated user's specified task list.
<google-tasks:get-task-by-id>
Returns the specified task.
<google-tasks:get-task-list-by-id>
Returns the authenticated user's specified task list
<google-tasks:get-task-lists>
Returns all the authenticated user's task lists.
<google-tasks:get-tasks>
Returns all tasks in the specified task list.
<google-tasks:insert-task>
Creates a new task on the specified task list
<google-tasks:insert-task-list>
Creates a new task list and adds it to the authenticated user's task lists.
<google-tasks:move>
Moves the specified task to another position in the task list.
<google-tasks:update-task>
Updates the specified task.
<google-tasks:update-task-list>
Updates the authenticated user's specified task list.

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

Attributes
TypeNameDefault ValueDescriptionJava TypeMIME TypeEncoding
xs:string name Optional. Give a name to this configuration so it can be later referenced.
xs:string applicationName Mule-GoogleTasksConnector/1.0 Optional. Application name registered on Google API console
xs:string consumerKey The OAuth2 consumer key
xs:string consumerSecret The OAuth2 consumer secret
xs:string scope https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/tasks Optional. The OAuth scopes you want to request
xs:string authorizationUrl https://accounts.google.com/o/oauth2/auth Optional. The URL defined by the Service Provider where the resource owner will be redirected to grant authorization to the connector
xs:string accessTokenUrl https://accounts.google.com/o/oauth2/token Optional. The URL defined by the Service Provider to obtain an access token

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

Authorize Attributes
NameDefault ValueDescription
access_type online Optional. Indicates if your application needs to access a Google API when the user is not present at the browser. Use offline to get a refresh token and use that when the user is not at the browser. Default is online
force_prompt auto Optional. Indicates if google should remember that an app has been authorized or if each should ask authorization every time. Use force to request authorization every time or auto to only do it the first time. Default is auto
authorizationUrl https://accounts.google.com/o/oauth2/auth Optional. The URL defined by the Service Provider where the resource owner will be redirected to grant authorization to the connector
accessTokenUrl https://accounts.google.com/o/oauth2/token Optional. The URL defined by the Service Provider to obtain an access token
accessTokenId   Optional. The Id with which the obtained access token will be stored. If not provided, then it will be the config name

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-tasks: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-tasks: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-tasks:config name="google-taskss" consumerKey="${consumerKey}" consumerSecret="${consumerSecret}" onNoToken="[STOP_FLOW|EXCEPTION]">
    <google-tasks: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:

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

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

OAuth Callback Config Attributes
NameDescription
connector-ref Optional. Reference to a user-defined HTTP connector.
domain Optional. The domain portion of the callback URL. This is usually something like xxx.cloudhub.io if you are deploying to CloudHub for example.
localPort Optional. The local port number that the endpoint will listen on. Normally 80, in the case of CloudHub you can use the environment variable ${http.port}.
remotePort Optional. This is the port number that we will tell the service provider we are listening on. It is usually the same as localPort but it is separated in case your deployment features port forwarding or a proxy.
path Optional. Path under which the callback should be exposed. If not specified a random path will be generated.
defaultAccessTokenId Optional. A Mule Expression to use as access token id. If provided, this expression will be evaluated for all obtained access tokens and the result will be used as their id (except in the cases in which a specific acessTokenId was provided on the authorize processor

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

<google-tasks:clear-tasks>

Clears all completed tasks from the specified task list. The affected tasks will be marked as 'hidden' and no longer be returned by default when retrieving all tasks for a task list.

XML Sample
<google-tasks:clear-tasks taskListId="someTaskListId" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
taskListId @default Optional. Task list identifier String */* UTF-8
Exception Payloads
Payload ClassDescription
IOException if there's an error in the communication

<google-tasks:delete-task>

Deletes the specified task from the task list.

XML Sample
<google-tasks:delete-task taskId="#[map-payload:id]"/>

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
taskListId @default Optional. Task list identifier String */* UTF-8
taskId Task identifier. String */* UTF-8
Exception Payloads
Payload ClassDescription
IOException if there's an error in the communication

<google-tasks:delete-task-list>

Deletes the authenticated user's specified task list.

XML Sample
<google-tasks:delete-task-list taskListId="#[map-payload:id]"/>

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
taskListId @default Optional. Task list identifier. String */* UTF-8
Exception Payloads
Payload ClassDescription
IOException if there's an error in the communication

<google-tasks:get-task-by-id>

Returns the specified task.

XML Sample
<google-tasks:get-task-by-id taskId="#[map-payload:id]"/>

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
taskListId @default Optional. Task list identifier String */* UTF-8
taskId Task identifier String */* UTF-8
Returns
Return Type Description
Task an instance of Task
Exception Payloads
Payload ClassDescription
IOException if there's an error in the communication

<google-tasks:get-task-list-by-id>

Returns the authenticated user's specified task list

XML Sample
<google-tasks:get-task-list-by-id taskListId="#[map-payload:id]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
taskListId @default Optional. Task list identifier. String */* UTF-8
Returns
Return Type Description
TaskList an instance of TaskList
Exception Payloads
Payload ClassDescription
IOException if there's an error in the communication

<google-tasks:get-task-lists>

Returns all the authenticated user's task lists.

This operation can potentially return a large amount of records that might exceed memory capacity.

To prevent this from being a problem, the output of this operation is automatically paginated into an iterable collection of objects. Regardless of the page-size, the iterator will be pushing out registries one at a time and fetching next pages on demand. If you wish to take advantage of the pagination, you must process the output through elements that can handle collections, such as a ForEach scope or DataMapper. In this way, Mule will execute the entire set of registries one at a time, but processing only a batch at a time and thus keeping memory usage from going over limits.

XML Sample
<google-tasks:get-task-lists />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
fetchSize 100 Specify the number of objects that will be returned in each iteration int    
Returns
Return Type Description
Iterator < TaskList > A collection: each index contains a list of objects, each object with its own set of properties. It is possible to process it in parts thanks to its pagination.
Exception Payloads
Payload ClassDescription
IOException if there's an error in the communication

<google-tasks:get-tasks>

Returns all tasks in the specified task list. This method accepts a number of filtering attributes. The one for which no values is specified will not be used when filtering

This operation can potentially return a large amount of records that might exceed memory capacity.

To prevent this from being a problem, the output of this operation is automatically paginated into an iterable collection of objects. Regardless of the page-size, the iterator will be pushing out registries one at a time and fetching next pages on demand. If you wish to take advantage of the pagination, you must process the output through elements that can handle collections, such as a ForEach scope or DataMapper. In this way, Mule will execute the entire set of registries one at a time, but processing only a batch at a time and thus keeping memory usage from going over limits.

XML Sample
<google-tasks:get-tasks showDeleted="true"/>

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
taskListId @default Optional. Task list identifier String */* UTF-8
completedMin Optional. Lower bound for a task's completion date (as a RFC 3339 timestamp) to filter by String */* UTF-8
completedMax Optional. Upper bound for a task's completion date (as a RFC 3339 timestamp) to filter by String */* UTF-8
dueMin Optional. Lower bound for a task's due date (as a RFC 3339 timestamp) to filter by String */* UTF-8
dueMax Optional. Upper bound for a task's due date (as a RFC 3339 timestamp) to filter by String */* UTF-8
updatedMin Optional. Lower bound for a task's last modification time (as a RFC 3339 timestamp) to filter by String */* UTF-8
showDeleted false Optional. Flag indicating whether deleted tasks are returned in the result boolean */*
showHidden false Optional. Flag indicating whether hidden tasks are returned in the result boolean */*
showcompleted false Optional. Flag indicating whether completed tasks are returned in the result boolean */*
fetchSize 100 Specify the number of objects that will be returned in each iteration int    
Returns
Return Type Description
Iterator < Task > A collection: each index contains a list of objects, each object with its own set of properties. It is possible to process it in parts thanks to its pagination.
Exception Payloads
Payload ClassDescription
IOException if there's an error in the communication

<google-tasks:insert-task>

Creates a new task on the specified task list

XML Sample
<google-tasks:insert-task />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
taskListId @default Optional. Task list identifier String */* UTF-8
task #[payload:] Optional. Instance of Task containing the state of the task to be inserted Task */*
Returns
Return Type Description
Task instance of Task representing the state of the newly inserted task
Exception Payloads
Payload ClassDescription
IOException if there's an error in the communication

<google-tasks:insert-task-list>

Creates a new task list and adds it to the authenticated user's task lists.

XML Sample
<google-tasks:insert-task-list />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
taskList #[payload:] Optional. The taskList to be inserted TaskList */*
Returns
Return Type Description
TaskList an instance of TaskList representing the newly inserted task list
Exception Payloads
Payload ClassDescription
IOException if there's an error in the communication

<google-tasks:move>

Moves the specified task to another position in the task list. This can include putting it as a child task under a new parent and/or move it to a different position among its sibling tasks.

XML Sample
<google-tasks:move parentId="#[map-payload:parentId]" taskId="#[map-payload]" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
taskListId @default Optional. Task list identifier String */* UTF-8
taskId Identifier for the task being moved. String */* UTF-8
parentId Optional. Parent task identifier. If the task is created at the top level, this parameter is omitted String */* UTF-8
previousId Optional. New previous sibling task identifier. If the task is moved to the first position among its siblings, this parameter is omitted String */* UTF-8
Returns
Return Type Description
Task an instance of Task representing the state of the moved task
Exception Payloads
Payload ClassDescription
IOException if there's an error in the communication

<google-tasks:update-task>

Updates the specified task.

XML Sample
<google-tasks:update-task taskListId="someTaskListId" taskId="someTaskId" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
taskListId @default Optional. Task list identifier String */* UTF-8
taskId Task identifier. String */* UTF-8
task #[payload:] Optional. Instance of Task containing the state we want the updated task to have Task */*
Returns
Return Type Description
Task an instance of Task representing the state of the updated task
Exception Payloads
Payload ClassDescription
IOException if there's an error in the communication

<google-tasks:update-task-list>

Updates the authenticated user's specified task list.

XML Sample
<google-tasks:update-task-list />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
taskList #[payload:] Optional. An instance of TaskList with the task list's new state TaskList */*
taskListId @default Optional. Task list identifier String */* UTF-8
Returns
Return Type Description
TaskList an instance of TaskList representing the state of the updated list
Exception Payloads
Payload ClassDescription
IOException if there's an error in the communication

Message Sources

Transformers