org.mule.modules

mule-module-handshake

config

Namespace	http://www.mulesoft.org/schema/mule/handshake
Schema Location	http://www.mulesoft.org/schema/mule/handshake/current/mule-handshake.xsd (View Schema)
Schema Version	1.0-SNAPSHOT
Minimum Mule Version	3.2

Module Overview

Handshake Cloud Connector Note on creation of resources and references Some creation methods allow to specify nested objects either as new or references to existing. Whenever you want to create a object that references an existing one (for example, a new Order for an existing Customer), you just have to specify the resourceUri of the nested object.

 <handshake:create-order>
     <handshake:order>
         <handshake:customer resourceUri="/api/v2/customers/1"/>
     </handshake:create-order>
 </handshake:order>

However, you can also create a nested object alongside the master one.

 <handshake:create-order>
     <handshake:order>
         <handshake:customer id="SOME_ID" name="Some Customer">
             <handshake:bill-to city="Springfiled" stree="742 Evergreen Terrace"/>
         </handshake:customer>
     </handshake:create-order>
 </handshake:order>

When you create a new object through the API, the returned value will always contain a resourceUri attribute, which should be stored in your external system for future use as a reference.

Summary

Configuration
<handshake:config> Configure an instance of this module

Message Processors
<handshake:create-address> Creates a `Address` on Handshake
<handshake:create-category> Creates a `Category` on handshake
<handshake:create-customer> Creates a `Customer` on Handshake Take into account than neither the `CustomerGroup` nor the `UserGroup` can be created alongside the `Customer` You can either let them be the default values for your account (by not specifying them), or use their resourceUri property to reference an existing one
<handshake:create-item> Creates a `Item` on handshake
<handshake:create-items> Creates `Item`s on handshake
<handshake:create-order> Creates a `Order` on handshake
<handshake:find-customers> Find all customers for the connected account that match the filters
<handshake:find-items> Get all items for the connected account that match the filters
<handshake:find-orders> Find all Sales Orders for the connected account that match the filters
<handshake:get-address> Get a `Address`, given its id
<handshake:get-category> Get a `Category`, given its id
<handshake:get-customer> Get a `Customer`, given its resourceUri
<handshake:get-customer-group> Get a `CustomerGroup`, given its id
<handshake:get-item> Get a `Item`, given its resourceUri
<handshake:get-order> Get a `Order`, given its resourceUri
<handshake:get-user-group> Get a `UserGroup`, given its id
<handshake:update-address> Updates a `Address` on Handshake, given its resourceUri
<handshake:update-customer> Updates a `Customer` on Handshake, given her resourceUri Take into account than neither the `CustomerGroup` nor the `UserGroup` can be created alongside the `Customer` You can either let them be the default values for your account (by not specifying them), or use their resourceUri property to reference an existing one
<handshake:update-item> Updates a `Item` on Handshake, given its resourceUri

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:handshake="http://www.mulesoft.org/schema/mule/handshake"
      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/handshake
               http://www.mulesoft.org/schema/mule/handshake/current/mule-handshake.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
Type	Name	Default Value	Description	Java Type	MIME Type	Encoding
xs:string	name		Optional. Give a name to this configuration so it can be later referenced.
xs:string	antiThrottleKey		Optional. Secret key provided by Handshake to by-pass throttling checks.
xs:string	endpoint	https://app.handshake-app.com/api/v2/	Optional. Endpoint to which the Connector should connect and call API methods

Connection Pool

This connector offers automatic connection management via the use of a connection pool. The pool will act a storage mechanism for all the connections that are in-use by the user of this connector.

Prior to execution of a processor, the connector will attempt to lookup an already established connection and if one doesn't exists it will create one. That lookup mechanism is done in the connection pool via the use of connection variables declared as keys.

The user of the connector can configure the pool by adding a connection-pooling-profile to the connector configuration like this:

    <handshake:connection-pooling-profile maxActive="10" maxIdle="10"
                             exhaustedAction="WHEN_EXHAUSTED_GROW" maxWait="120" minEvictionMillis="60000" evictionCheckIntervalMillis="30000"/>

The following is a list of connection attributes, each connection attribute can be configured at the config element level or they can also be added to each processor. If they are used at the processor level they get the benefit of full expression resolution.

Connection Attributes
Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
apiKey		The API key for the user	String	/	UTF-8
securityToken		Optional. Used for sensitive data encryption. Please refer to http://www.handshake-app.com/help/kb/api/api-authentication	String	/	UTF-8

Reconnection Strategies

Reconnection Strategies specify how a connector behaves when its connection fails. You can control how Mule attempts to reconnect by specifying a number of criteria:

The type of exception
Number and frequency of reconnection attempts
The notifications generated, and more

With a reconnection strategy, you can better control the behavior of a failed connection, by configuring it, for example, to re-attempt the connection only once every 15 minutes, and to give up after 30 attempts. You can also send an automatic notification to your IT administrator whenever this reconnection strategy goes into effect. You can even define a strategy that attempts to reconnect only during business hours. Such a setting can prove useful if your server is frequently shut down for nightly maintenance.

Configuration

A reconnection strategy that allows the user to configure how many times a reconnection should be attempted and how long to wait between attempts.

    <handshake:config>
         <reconnect count="5" frequency="1000"/>
    </handshake:config>

Reconnect Attributes
Name	Default Value	Description
frequency	2000	Optional. How often (in ms) to reconnect
count	2	Optional. How many reconnection attempts to make

For more information about reconnection strategies in Mule, or even how to write your own custom reconnection strategy please check this section.

Message Processors

<handshake:create-address>

Creates a Address on Handshake

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
address	To create XML Sample INCLUDE_ERROR	Address	/
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
apiKey	Optional. The API key for the user	String	/	UTF-8
securityToken	Optional. Used for sensitive data encryption. Please refer to http://www.handshake-app.com/help/kb/api/api-authentication	String	/	UTF-8

Returns

Return Type	Description
Address	the created address

<handshake:create-category>

Creates a Category on handshake

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
category	To create XML Sample INCLUDE_ERROR	Category	/
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
apiKey	Optional. The API key for the user	String	/	UTF-8
securityToken	Optional. Used for sensitive data encryption. Please refer to http://www.handshake-app.com/help/kb/api/api-authentication	String	/	UTF-8

Returns

Return Type	Description
Category	the created category

<handshake:create-customer>

Creates a Customer on Handshake Take into account than neither the CustomerGroup nor the UserGroup can be created alongside the Customer You can either let them be the default values for your account (by not specifying them), or use their resourceUri property to reference an existing one

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
customer	To create. Mandatory fields are ID, name and billTo (which has to be a new Address, and not a reference) XML Sample INCLUDE_ERROR	Customer	/
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
apiKey	Optional. The API key for the user	String	/	UTF-8
securityToken	Optional. Used for sensitive data encryption. Please refer to http://www.handshake-app.com/help/kb/api/api-authentication	String	/	UTF-8

Returns

Return Type	Description
Customer	the created customer

<handshake:create-item>

Creates a Item on handshake

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
item	To create XML Sample INCLUDE_ERROR	Item	/
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
apiKey	Optional. The API key for the user	String	/	UTF-8
securityToken	Optional. Used for sensitive data encryption. Please refer to http://www.handshake-app.com/help/kb/api/api-authentication	String	/	UTF-8

Returns

Return Type	Description
Item	the created item

<handshake:create-items>

Creates Items on handshake

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
apiKey	Optional. The API key for the user	String	/	UTF-8
securityToken	Optional. Used for sensitive data encryption. Please refer to http://www.handshake-app.com/help/kb/api/api-authentication	String	/	UTF-8

Child Elements

Name	Default Value	Description	Java Type
<handshake:items>		To create XML Sample INCLUDE_ERROR	List<Item>

Returns

Return Type	Description
List<Item>	a list of the items created (if everything is ok, it should match the provided list)

<handshake:create-order>

Creates a Order on handshake

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
order	To create XML Sample INCLUDE_ERROR XML Sample INCLUDE_ERROR	Order	/
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
apiKey	Optional. The API key for the user	String	/	UTF-8
securityToken	Optional. Used for sensitive data encryption. Please refer to http://www.handshake-app.com/help/kb/api/api-authentication	String	/	UTF-8

Returns

Return Type	Description
Order	the created order

<handshake:find-customers>

Find all customers for the connected account that match the filters

XML Sample

INCLUDE_ERROR

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
fetchAllResults	false	Optional. Set to true if you want to get the full result instead of a paged one. WARNING: This could be slow and raise OutOfMemoryError if the result is too long	boolean	/
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
apiKey		Optional. The API key for the user	String	/	UTF-8
securityToken		Optional. Used for sensitive data encryption. Please refer to http://www.handshake-app.com/help/kb/api/api-authentication	String	/	UTF-8

Child Elements

Name	Default Value	Description	Java Type
<handshake:filters>		Optional. Allowed values are: "customerGroup", "userGroup", "ctime" and "mtime" (for creation and modification times, check operators in http://www.handshake-app.com/help/kb/api/web-services-resources-overview) NOTE: filter values refer to the user-defined IDs, and not to the HandShake id	Map<String, String>

Returns

Return Type	Description
Collection<Customer>	a Collection of all the Customers matching the filters

<handshake:find-items>

Get all items for the connected account that match the filters

XML Sample

INCLUDE_ERROR

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
fetchAllResults	false	Optional. Set to true if you want to get the full result instead of a paged one. WARNING: This could be slow and raise OutOfMemoryError if the result is too long	boolean	/
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
apiKey		Optional. The API key for the user	String	/	UTF-8
securityToken		Optional. Used for sensitive data encryption. Please refer to http://www.handshake-app.com/help/kb/api/api-authentication	String	/	UTF-8

Child Elements

Name	Default Value	Description	Java Type
<handshake:filters>		Optional. To apply. Allowed filters are category (by Handshake id), manufacturer (by Handshake id), order (to get items from a specific Order), search (only items with a sku or name that match will be returned), sku (you'll get either 1 or 0 results)	Map<String, String>

Returns

Return Type	Description
Collection<Item>	A Collection of items for the connected account that match the filters

<handshake:find-orders>

Find all Sales Orders for the connected account that match the filters

XML Sample

INCLUDE_ERROR

XML Sample

INCLUDE_ERROR

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
fetchAllResults	false	Optional. Set to true if you want to get the full result instead of a paged one. WARNING: This could be slow and raise OutOfMemoryError if the result is too long	boolean	/
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
apiKey		Optional. The API key for the user	String	/	UTF-8
securityToken		Optional. Used for sensitive data encryption. Please refer to http://www.handshake-app.com/help/kb/api/api-authentication	String	/	UTF-8

Child Elements

Name	Default Value	Description	Java Type
<handshake:filters>		Optional. Allowed values are: "customerID", "status", "ctime" and "mtime" (for creation and modification times, check operators in http://www.handshake-app.com/help/kb/api/web-services-resources-overview)	Map<String, String>

Returns

Return Type	Description
Collection<Order>	a Collection of all the Sales Orders matching the filters

<handshake:get-address>

Get a Address, given its id

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
resourceUri	Of the Address to get. The uri is Handshake's uid, as returned by the creation method (like '/api/v2/<resource>/<id>') XML Sample INCLUDE_ERROR	String	/	UTF-8
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
apiKey	Optional. The API key for the user	String	/	UTF-8
securityToken	Optional. Used for sensitive data encryption. Please refer to http://www.handshake-app.com/help/kb/api/api-authentication	String	/	UTF-8

Returns

Return Type	Description
Address	the address with the given id or a `HandshakeAPIException`, if the Address doesn't exist

<handshake:get-category>

Get a Category, given its id

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
id	Of the Category to get. The id is the one specified on creation, and not Handshake's uid XML Sample INCLUDE_ERROR	String	/	UTF-8
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
apiKey	Optional. The API key for the user	String	/	UTF-8
securityToken	Optional. Used for sensitive data encryption. Please refer to http://www.handshake-app.com/help/kb/api/api-authentication	String	/	UTF-8

Returns

Return Type	Description
Category	the category with the given id, or null if it doesn't exist

<handshake:get-customer>

Get a Customer, given its resourceUri

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
resourceUri	Of the Customer to get. The resourceUri is Handshake's uid, as returned by the creation method (like '/api/v2/<resource>/<id>') XML Sample INCLUDE_ERROR	String	/	UTF-8
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
apiKey	Optional. The API key for the user	String	/	UTF-8
securityToken	Optional. Used for sensitive data encryption. Please refer to http://www.handshake-app.com/help/kb/api/api-authentication	String	/	UTF-8

Returns

Return Type	Description
Customer	the customer with the given resourceUri, or null if it doesn't exist

<handshake:get-customer-group>

Get a CustomerGroup, given its id

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
id	Of the CustomerGroup to get. The id is the one specified on creation, and not Handshake's uid XML Sample INCLUDE_ERROR	String	/	UTF-8
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
apiKey	Optional. The API key for the user	String	/	UTF-8
securityToken	Optional. Used for sensitive data encryption. Please refer to http://www.handshake-app.com/help/kb/api/api-authentication	String	/	UTF-8

Returns

Return Type	Description
CustomerGroup	the customer group with the given id, or null if it doesn't exist

<handshake:get-item>

Get a Item, given its resourceUri

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
resourceUri	Of the Item to get. The resourceUri is Handshake's uid, as returned by the creation method (like '/api/v2/<resource>/<id>') XML Sample INCLUDE_ERROR	String	/	UTF-8
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
apiKey	Optional. The API key for the user	String	/	UTF-8
securityToken	Optional. Used for sensitive data encryption. Please refer to http://www.handshake-app.com/help/kb/api/api-authentication	String	/	UTF-8

Returns

Return Type	Description
Item	the item with the given resourceUri, or null if it doesn't exist

<handshake:get-order>

Get a Order, given its resourceUri

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
resourceUri	Of the Order to get. The uri is Handshake's uid, as returned by the creation method (like '/api/v2/<resource>/<id>') XML Sample INCLUDE_ERROR	String	/	UTF-8
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
apiKey	Optional. The API key for the user	String	/	UTF-8
securityToken	Optional. Used for sensitive data encryption. Please refer to http://www.handshake-app.com/help/kb/api/api-authentication	String	/	UTF-8

Returns

Return Type	Description
Order	the order with the given id or a `HandshakeAPIException`, if the Order doesn't exist

<handshake:get-user-group>

Get a UserGroup, given its id

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
id	Of the UserGroup to get. The id is the one specified on creation, and not Handshake's uid XML Sample INCLUDE_ERROR	String	/	UTF-8
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
apiKey	Optional. The API key for the user	String	/	UTF-8
securityToken	Optional. Used for sensitive data encryption. Please refer to http://www.handshake-app.com/help/kb/api/api-authentication	String	/	UTF-8

Returns

Return Type	Description
UserGroup	the user group with the given id, or null if it doesn't exist

<handshake:update-address>

Updates a Address on Handshake, given its resourceUri

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
resourceUri	Optional. Of the Address to edit (if you skip this, you should include the resourceUri attribute in the address)	String	/	UTF-8
address	With the changes to update. You should only include those fields that you want to update, specially if referencing existing nested objects XML Sample INCLUDE_ERROR	Address	/
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
apiKey	Optional. The API key for the user	String	/	UTF-8
securityToken	Optional. Used for sensitive data encryption. Please refer to http://www.handshake-app.com/help/kb/api/api-authentication	String	/	UTF-8

Returns

Return Type	Description
Address	the updated address

<handshake:update-customer>

Updates a Customer on Handshake, given her resourceUri Take into account than neither the CustomerGroup nor the UserGroup can be created alongside the Customer You can either let them be the default values for your account (by not specifying them), or use their resourceUri property to reference an existing one

Attributes

Name	Default Value	Description	Java Type	MIME Type	Encoding
config-ref		Optional. Specify which configuration to use.
resourceUri		Optional. Of the Customer to update (if you skip this, you should include the resourceUri attribute in the customer)	String	/	UTF-8
customer	#[payload]	Optional. With the changes to update. You should only include those fields that you want to update, specially if referencing existing nested objects (e.g. try not to include billing address information if it hasn't changed) XML Sample INCLUDE_ERROR	Customer	/
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
apiKey		Optional. The API key for the user	String	/	UTF-8
securityToken		Optional. Used for sensitive data encryption. Please refer to http://www.handshake-app.com/help/kb/api/api-authentication	String	/	UTF-8

Returns

Return Type	Description
Customer	the updated customer

<handshake:update-item>

Updates a Item on Handshake, given its resourceUri

Attributes

Name	Description	Java Type	MIME Type	Encoding
config-ref	Optional. Specify which configuration to use.
resourceUri	Optional. Of the Item to edit (if you skip this, you should include the resourceUri attribute in the item)	String	/	UTF-8
item	With the changes to update. You should only include those fields that you want to update, specially if referencing existing nested objects XML Sample INCLUDE_ERROR	Item	/
Connection Parameters This are only required if you didn't specified them at the configuration element. They are also useful for overriding the values of the configurations or even if you need to extract them from the Mule message since they support expression evaluation.
apiKey	Optional. The API key for the user	String	/	UTF-8
securityToken	Optional. Used for sensitive data encryption. Please refer to http://www.handshake-app.com/help/kb/api/api-authentication	String	/	UTF-8

Returns

Return Type	Description
Item	the updated item