org.mule.modules

mule-module-google-contacts

config-with-oauth

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

Module Overview

Cloud connector for the Google Contacts API v3 using OAuth2 for initialization. Uses OAuth2 for authentication

Summary

Configuration
<google-contacts:config-with-oauth>
Configure an instance of this module
Message Processors
<google-contacts:add-group>
Adds a group to a given contact
<google-contacts:batch-contacts>
This tag encloses a series of nested processors that perform operations on contacts entities
<google-contacts:batch-delete>
The function of this sub processor is to add updated operations into the current batch for the given entries This processor is intended to be used nested inside batch-contacts or batch-groups, although there's no syntactic validation inside the connector's XSD enforcing that.
<google-contacts:batch-groups>
This tag encloses a series of nested processors that perform operations on group entities.
<google-contacts:batch-insert>
The function of this sub processor is to add insert operations into the current batch for the given entries This processor is intended to be used nested inside batch-contacts or batch-groups, although there's no syntactic validation inside the connector's XSD enforcing that.
<google-contacts:batch-update>
The function of this sub processor is to add updated operations into the current batch for the given entries This processor is intended to be used nested inside batch-contacts or batch-groups, although there's no syntactic validation inside the connector's XSD enforcing that.
<google-contacts:create-group>
Inserts a new group
<google-contacts:delete-contact>
Deletes a given contact
<google-contacts:delete-contact-by-id>
Deletes a contact signaled by its id
<google-contacts:delete-contact-photo>
Deletes the photo associated to a given contact
<google-contacts:delete-contact-photo-by-id>
Deletes the photo of a contact signaled by its id
<google-contacts:delete-group>
Deletes the given group
<google-contacts:delete-group-by-id>
Deletes a group signaled by its id
<google-contacts:download-photo>
Downloads the photo of a given contact
<google-contacts:download-photo-by-id>
Downloads the photo of a contact signaled by its id contact and returns it as an input stream
<google-contacts:get-contact-by-id>
Retrieves a contact by id
<google-contacts:get-contacts>
Retrieves all the contacts matching the given criterias.
<google-contacts:get-group-by-id>
Retrieves a group by id
<google-contacts:get-group-by-name>
Retrieves a group with the given name
<google-contacts:get-groups>
Returns all the groups the authenticated user has access to
<google-contacts:insert-contact>
Inserts a new contact
<google-contacts:update-contact>
Updates a contact entry
<google-contacts:update-contact-photo>
Updates the photo of a contact signaled by its id taken a java.io.InputStream as an input
<google-contacts:update-group>
Updates the state of a group

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-contacts="http://www.mulesoft.org/schema/mule/google-contacts"
      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-contacts
               http://www.mulesoft.org/schema/mule/google-contacts/current/mule-google-contacts.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-GoogleContactsConnector/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.google.com/m8/feeds Optional. The OAuth2 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-contacts: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-contacts: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-contacts: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-contacts: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-contacts:config name="google-contactss" consumerKey="${consumerKey}" consumerSecret="${consumerSecret}" onNoToken="[STOP_FLOW|EXCEPTION]">
    <google-contacts: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-contacts: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-contacts:config>
        <google-contacts:oauth-callback-config domain="${fullDomain}" localPort="${http.port}" remotePort="80" defaultAccessTokenId="#[message.inboundProperties['tenantId']]" />
    </google-contacts: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-contacts:config>
        <google-contacts:oauth-store-config objectStore-ref="my-object-store"/>
    </google-contacts: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-contacts:add-group>

Adds a group to a given contact

XML Sample
<google-contacts:add-group groupId="#[map-payload:id]" config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
contact #[payload:] Optional. An instance of com.google.gdata.data.contacts.ContactEntry representing the contact to be updated GoogleContactEntry */*
groupId The id of the group String */* UTF-8
Returns
Return Type Description
GoogleContactEntry an instance of com.google.gdata.data.contacts.ContactEntry representing the contact's updated state
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers
ServiceException if the operation raises an error on google's end

<google-contacts:batch-contacts>

This tag encloses a series of nested processors that perform operations on contacts entities

XML Sample
<google-contacts:batch-contacts batchId="sample" config-ref="google-contacts">
	<google-contacts:batch-insert operationId="inserts" entries-ref="#[map-payload:inserts]" config-ref="google-contacts" />
	<google-contacts:batch-update operationId="updates" entries-ref="#[map-payload:updates]" config-ref="google-contacts" />
	<google-contacts:batch-delete operationId="deletes" entries-ref="#[map-payload:deletes]" config-ref="google-contacts" />
</google-contacts:batch-contacts>

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
batchId Optional. An id to identify the batch String */* UTF-8
Child Elements
NameDefault ValueDescriptionJava Type
<google-contacts:operations> #[payload:] Optional. A list with instances of org.mule.api.NestedProcessor representing the operations to be performed in the batch List<NestedProcessor>
Returns
Return Type Description
List<BatchResult> a list with instances of org.mule.modules.google.api.domain.BatchResult
Exception Payloads
Payload ClassDescription
Exception if an error is encountered

<google-contacts:batch-delete>

The function of this sub processor is to add updated operations into the current batch for the given entries This processor is intended to be used nested inside batch-contacts or batch-groups, although there's no syntactic validation inside the connector's XSD enforcing that. However, if you don't use it that way, then it's most likely to throw a java.lang.IllegalStateException

XML Sample
<google-contacts:batch-delete operationId="deletes" entries-ref="#[map-payload:deletes]" config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
message The current mule message MuleMessage */*
operationId Id to identify this particular operation inside the batch String */* UTF-8
entries #[payload:] Optional. A collection with instances of com.google.gdata.data.BaseEntry to be batch updated Collection<GoogleContactBaseEntity<?>> */*
Exception Payloads
Payload ClassDescription
IllegalStateException if not nested in batch-contact or batch-group

<google-contacts:batch-groups>

This tag encloses a series of nested processors that perform operations on group entities. According to the API's specification the maximum number of operations allowed in one batch is 100. Thus, this processor will automatically group the operations in batches of 100. According to the API's specification the maximum number of operations allowed in one batch is 100. Thus, this processor will automatically group the operations in batches of 100.

XML Sample
<google-contacts:batch-groups batchId="sample" config-ref="google-contacts">
	<google-contacts:batch-insert operationId="inserts" entries-ref="#[map-payload:inserts]" config-ref="google-contacts" />
	<google-contacts:batch-update operationId="updates" entries-ref="#[map-payload:updates]" config-ref="google-contacts" />
	<google-contacts:batch-delete operationId="deletes" entries-ref="#[map-payload:deletes]" config-ref="google-contacts" />
</google-contacts:batch-groups>

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
batchId Optional. An id to identify the batch String */* UTF-8
Child Elements
NameDefault ValueDescriptionJava Type
<google-contacts:operations> #[payload:] Optional. A list with instances of org.mule.api.NestedProcessor representing the operations to be performed in the batch List<NestedProcessor>
Returns
Return Type Description
List<BatchResult> a list with instances of org.mule.modules.google.api.domain.BatchResult
Exception Payloads
Payload ClassDescription
Exception if an error is encountered

<google-contacts:batch-insert>

The function of this sub processor is to add insert operations into the current batch for the given entries This processor is intended to be used nested inside batch-contacts or batch-groups, although there's no syntactic validation inside the connector's XSD enforcing that. However, if you don't use it that way, then it's most likely to throw a java.lang.IllegalStateException

XML Sample
<google-contacts:batch-insert operationId="inserts" entries-ref="#[map-payload:inserts]" config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
message The current mule message MuleMessage */*
operationId Id to identify this particular operation inside the batch String */* UTF-8
entries #[payload:] Optional. A collection with instances of com.google.gdata.data.BaseEntry to be batch inserted Collection<GoogleContactBaseEntity<?>> */*
Exception Payloads
Payload ClassDescription
IllegalStateException if not nested in batch-contact or batch-group

<google-contacts:batch-update>

The function of this sub processor is to add updated operations into the current batch for the given entries This processor is intended to be used nested inside batch-contacts or batch-groups, although there's no syntactic validation inside the connector's XSD enforcing that. However, if you don't use it that way, then it's most likely to throw a java.lang.IllegalStateException

XML Sample
<google-contacts:batch-update operationId="updates" entries-ref="#[map-payload:updates]" config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
message The current mule message MuleMessage */*
operationId Id to identify this particular operation inside the batch String */* UTF-8
entries #[payload:] Optional. A collection with instances of com.google.gdata.data.BaseEntry to be batch updated Collection<GoogleContactBaseEntity<?>> */*
Exception Payloads
Payload ClassDescription
IllegalStateException if not nested in batch-contact or batch-group

<google-contacts:create-group>

Inserts a new group

XML Sample
<google-contacts:create-group config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
group #[payload:] Optional. An instance of com.google.gdata.data.contacts.ContactGroupEntry representing the group to be inserted GoogleContactGroupEntry */*
Returns
Return Type Description
GoogleContactGroupEntry an instance of com.google.gdata.data.contacts.ContactGroupEntry representing the newly created group
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers
ServiceException if the operation raises an error on google's end

<google-contacts:delete-contact>

Deletes a given contact

XML Sample
<google-contacts:delete-contact config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
entry #[payload:] Optional. The contact to be deleted GoogleContactEntry */*
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers
ServiceException if the operation raises an error on google's end

<google-contacts:delete-contact-by-id>

Deletes a contact signaled by its id

XML Sample
<google-contacts:delete-contact-by-id contactId="#[map-payload:id]" config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
contactId The id of the contact to be deleted String */* UTF-8
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers
ServiceException if the operation raises an error on google's end

<google-contacts:delete-contact-photo>

Deletes the photo associated to a given contact

XML Sample
<google-contacts:delete-contact-photo config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
contact #[payload:] Optional. An instance of com.google.gdata.data.contacts.ContactEntry representing the contact whose photo we want deleted GoogleContactEntry */*
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers
ServiceException if the operation raises an error on google's end

<google-contacts:delete-contact-photo-by-id>

Deletes the photo of a contact signaled by its id

XML Sample
<google-contacts:delete-contact-photo-by-id contactId="#[map-payload:id]" config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
contactId The id of the contact whose photo we want to delete String */* UTF-8
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers
ServiceException if the operation raises an error on google's end

<google-contacts:delete-group>

Deletes the given group

XML Sample
<google-contacts:delete-group config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
group #[payload:] Optional. An instance of com.google.gdata.data.contacts.ContactGroupEntry representing the group to be deleted GoogleContactGroupEntry */*
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers
ServiceException if the operation raises an error on google's end

<google-contacts:delete-group-by-id>

Deletes a group signaled by its id

XML Sample
<google-contacts:delete-group-by-id groupId="#[map-payload:id]" config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
groupId The id of the group to be deleted String */* UTF-8
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers
ServiceException if the operation raises an error on google's end

<google-contacts:download-photo>

Downloads the photo of a given contact

XML Sample
<google-contacts:download-photo config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
contact #[payload:] Optional. The contact whose photo we want GoogleContactEntry */*
Returns
Return Type Description
InputStream an instance of java.io.InputStream
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers
ServiceException if the operation raises an error on google's end

<google-contacts:download-photo-by-id>

Downloads the photo of a contact signaled by its id contact and returns it as an input stream

XML Sample
<google-contacts:download-photo-by-id id="#[map-payload:id]" config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
id The id of the contact whose photo we want String */* UTF-8
Returns
Return Type Description
InputStream an instance of java.io.InputStream
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers
ServiceException if the operation raises an error on google's end

<google-contacts:get-contact-by-id>

Retrieves a contact by id

XML Sample
<google-contacts:get-contact-by-id id="#[map-payload:id]" config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
id The id of the contact String */* UTF-8
Returns
Return Type Description
GoogleContactEntry an instance of com.google.gdata.data.contacts.ContactEntry
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers
ServiceException if the operation raises an error on google's end

<google-contacts:get-contacts>

Retrieves all the contacts matching the given criterias. If a criteria is not provided then it's not used in the filtering. Thus, providing no criteria equals getting all contacts

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-contacts:get-contacts fullTextQuery="Mulesoft" config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
updatedMin Optional. Sets the minimum updated timestamp used for the query. Only entries with an updated timestamp equal to or later than the specified timestamp will be returned. String */* UTF-8
updatedMax Optional. Sets the maximum updated timestamp used for the query. Only entries with an updated timestamp earlier than the specified timestamp will be returned. String */* UTF-8
datetimeFormat yyyy-MM-dd\'T\'HH:mm:ss\'Z\' Optional. The pattern to be used for parsing updatedMin and updatedMax String */* UTF-8
fullTextQuery Optional. Sets the full text query string that will be used for the query. String */* UTF-8
sortOrder NONE Optional. Valid values are NONE, ASCENDING and DESCENDING ContactQuery.SortOrder */*
showDeleted false Optional. Wether to show deleted entries or not Boolean */*
orderBy NONE Optional. The field to be used when sorting. Valid values are NONE, LAST_MODIFIED and EDITED ContactQuery.OrderBy */*
groupId Optional. Only show contacts from a given group String */* UTF-8
fetchSize 100 Specify the number of objects that will be returned in each iteration int    
Returns
Return Type Description
Iterator < GoogleContactEntry > 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 a communication error with google's servers
ServiceException if the operation raises an error on google's end

<google-contacts:get-group-by-id>

Retrieves a group by id

XML Sample
<google-contacts:get-group-by-id id="#[map-payload:id]" config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
id The id of the group to be returned String */* UTF-8
Returns
Return Type Description
GoogleContactGroupEntry an instance of com.google.gdata.data.contacts.ContactGroupEntry
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers
ServiceException if the operation raises an error on google's end

<google-contacts:get-group-by-name>

Retrieves a group with the given name

XML Sample
<google-contacts:get-group-by-name groupName="my group" config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
groupName The name of the group you want String */* UTF-8
Returns
Return Type Description
GoogleContactGroupEntry an instance of com.google.gdata.data.contacts.ContactGroupEntry or null if the group doesn't exist
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers
ServiceException if the operation raises an error on google's end

<google-contacts:get-groups>

Returns all the groups the authenticated user has access to

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-contacts:delete-contact-photo config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
updatedMin Optional. Sets the minimum updated timestamp used for the query. Only entries with an updated timestamp equal to or later than the specified timestamp will be returned. String */* UTF-8
updatedMax Optional. Sets the maximum updated timestamp used for the query. Only entries with an updated timestamp earlier than the specified timestamp will be returned. String */* UTF-8
datetimeFormat yyyy-MM-dd\'T\'HH:mm:ss\'Z\' Optional. The date pattern used to parse updatedMin and updatedMax String */* UTF-8
fetchSize 100 Specify the number of objects that will be returned in each iteration int    
Returns
Return Type Description
Iterator < GoogleContactGroupEntry > 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 a communication error with google's servers
ServiceException if the operation raises an error on google's end

<google-contacts:insert-contact>

Inserts a new contact

XML Sample
<google-contacts:insert-contact config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
contact #[payload:] Optional. An instance of com.google.gdata.data.contacts.ContactEntry representing the contact to be inserted GoogleContactEntry */*
Returns
Return Type Description
GoogleContactEntry an instance of com.google.gdata.data.contacts.ContactEntry representing the newly inserted contact
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers
ServiceException if the operation raises an error on google's end

<google-contacts:update-contact>

Updates a contact entry

XML Sample
<google-contacts:update-contact config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
contact #[payload:] Optional. An instance of com.google.gdata.data.contacts.ContactEntry representing the contact to be updated GoogleContactEntry */*
Returns
Return Type Description
GoogleContactEntry an instance of com.google.gdata.data.contacts.ContactEntry representing the contact's updated state
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers
ServiceException if the operation raises an error on google's end
URISyntaxException If the generation of the URL for the update endpoint fails
IllegalArgumentException If the generation of the URL for the update endpoint fails

<google-contacts:update-contact-photo>

Updates the photo of a contact signaled by its id taken a java.io.InputStream as an input

XML Sample
<google-contacts:update-contact-photo contactId="#[map-payload:id]" config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
contactId The id of the contact whose photo we want to update String */* UTF-8
in #[payload:] Optional. A java.io.InputStream with the photo's binary content InputStream */*
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers
ServiceException if the operation raises an error on google's end

<google-contacts:update-group>

Updates the state of a group

XML Sample
<google-contacts:update-group config-ref="google-contacts" />

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
group #[payload:] Optional. An instance of com.google.gdata.data.contacts.ContactGroupEntry with the group's new state GoogleContactGroupEntry */*
Returns
Return Type Description
GoogleContactGroupEntry an instance of com.google.gdata.data.contacts.ContactGroupEntry reflecting the group's updated state
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers
ServiceException if the operation raises an error on google's end

Message Sources

Transformers