org.mule.modules

mule-module-google-prediction

config-with-oauth

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

Module Overview

Generic module

Summary

Configuration
<google-prediction:config-with-oauth>
Configure an instance of this module
Message Processors
<google-prediction:analyze>
Updates an existing prediction model with new data.
<google-prediction:create>
Inserts a new calendar associated with the user that owns the current OAuth token

<google-prediction:delete>
Deletes a prediction model using the id of that model.
<google-prediction:get>
Updates an existing prediction model with new data.
<google-prediction:list>
Inserts a new calendar associated with the user that owns the current OAuth token

<google-prediction:predict>
Inserts a new calendar associated with the user that owns the current OAuth token

<google-prediction:training-complete>
Checks if the training of a model is completed or not.
<google-prediction:update>
Updates an existing prediction model with new data.

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-prediction="http://www.mulesoft.org/schema/mule/google-prediction"
      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-prediction
               http://www.mulesoft.org/schema/mule/google-prediction/current/mule-google-prediction.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-GooglePredictionConnector/1.0 Optional. Application name registered on Google API console
xs:string consumerKey The OAuth2 consumer key
xs:string consumerSecret The OAuth2 consumer secret
identifierPolicy EMAIL Optional. This policy represents which id we want to use to represent each google account.
xs:string scope https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/prediction 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

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:

    <google-prediction: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"/>
        <google-prediction: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:

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

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"/>
      <google-prediction: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"/>
        <google-prediction: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"/>
        <google-prediction: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"/>
      <google-prediction: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:

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

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

<google-prediction:analyze>

Updates an existing prediction model with new data.

XML Sample
<google-prediction:analyze config-ref="Googleprediction" modelId="modelId"/>

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
modelId The id of your prediction model. String */* UTF-8
OAuth Parameters
The following values are always required when using OAuth as the authentication mechanism.
accessTokenId Access token identifier used to retrieve an access token from the store
Returns
Return Type Description
Analyze another instance of Prediction.Trainedmodels.Update representing the model that was created
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers

<google-prediction:create>

Inserts a new calendar associated with the user that owns the current OAuth token

XML Sample
<google-prediction:create config-ref="Googleprediction" googleStorageLocation="your/path/to/google/cloudstorage" modelId="modelId" storagePMMLLocation="optionalPMM" storagePMMLModelLocation="optionalPMMModel"/>

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
modelId The id of your prediction model. String */* UTF-8
googleStorageLocation Optional. The id of your google storage that holds the model. String */* UTF-8
storagePMMLLocation Optional. The id of your google storage Location that holds the PMML model. String */* UTF-8
storagePMMLModelLocation Optional. The id of your google storage Location that holds the PMML model. String */* UTF-8
OAuth Parameters
The following values are always required when using OAuth as the authentication mechanism.
accessTokenId Access token identifier used to retrieve an access token from the store
Returns
Return Type Description
Training another instance of Training representing the model that was created
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers

<google-prediction:delete>

Deletes a prediction model using the id of that model.

XML Sample
<google-prediction:delete config-ref="Googleprediction" modelId="modelId"/>

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
modelId The id of your prediction model. String */* UTF-8
OAuth Parameters
The following values are always required when using OAuth as the authentication mechanism.
accessTokenId Access token identifier used to retrieve an access token from the store
Returns
Return Type Description
void another instance of Boolean representing the model that was created
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers

<google-prediction:get>

Updates an existing prediction model with new data.

XML Sample
<google-prediction:analyze config-ref="Googleprediction" modelId="modelId"/>

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
modelId The id of your prediction model. String */* UTF-8
OAuth Parameters
The following values are always required when using OAuth as the authentication mechanism.
accessTokenId Access token identifier used to retrieve an access token from the store
Returns
Return Type Description
Training another instance of Prediction.Trainedmodels.Update representing the model that was created
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers

<google-prediction:list>

Inserts a new calendar associated with the user that owns the current OAuth token

XML Sample
<google-prediction:list config-ref="Googleprediction"/>

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
OAuth Parameters
The following values are always required when using OAuth as the authentication mechanism.
accessTokenId Access token identifier used to retrieve an access token from the store
Returns
Return Type Description
List<Training> another instance of List representing the calendar that was created
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers

<google-prediction:predict>

Inserts a new calendar associated with the user that owns the current OAuth token

XML Sample
<google-prediction:predict config-ref="Googleprediction" modelId="modelName">
    <google-prediction:list ref="#[payload]"/>
</google-prediction:predict>

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
modelId The name of your prediction model. String */* UTF-8
OAuth Parameters
The following values are always required when using OAuth as the authentication mechanism.
accessTokenId Access token identifier used to retrieve an access token from the store
Child Elements
NameDefault ValueDescriptionJava Type
<google-prediction:list> A list containing the query strings that you want to predict. List<Object>
Returns
Return Type Description
Output another instance of Output representing the calendar that was created
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers

<google-prediction:training-complete>

Checks if the training of a model is completed or not.

XML Sample
<google-prediction:training-complete config-ref="Googleprediction" modelId="modelId"/>

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
modelId The id of your prediction model. String */* UTF-8
OAuth Parameters
The following values are always required when using OAuth as the authentication mechanism.
accessTokenId Access token identifier used to retrieve an access token from the store
Returns
Return Type Description
Boolean another instance of Boolean representing the model that was created
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers

<google-prediction:update>

Updates an existing prediction model with new data.

XML Sample
<google-prediction:update config-ref="Googleprediction" label="SampleLabel" modelId="modelId">
    <google-prediction:csv ref="#[payload]"/>
</google-prediction:update>

Attributes
NameDefault ValueDescriptionJava TypeMIME TypeEncoding
config-ref Optional. Specify which configuration to use.
modelId The id of your prediction model. String */* UTF-8
label The label that you want to add more training data to. String */* UTF-8
OAuth Parameters
The following values are always required when using OAuth as the authentication mechanism.
accessTokenId Access token identifier used to retrieve an access token from the store
Child Elements
NameDefault ValueDescriptionJava Type
<google-prediction:csv> A list of CSV strings that you want to update this training model with for one particular label. List<Object>
Returns
Return Type Description
Training another instance of Prediction.Trainedmodels.Update representing the model that was created
Exception Payloads
Payload ClassDescription
IOException if there's a communication error with google's servers

Message Sources

Transformers