DRAFT

Date:               Nov 28, 2012

Last Updated: Dec 20, 2012

About

The Pull Model is a way for Integration Partners to request records that are new or updated since last time they called. This model is useful in a scenario where the usual real-time synchronization model will not work.

Process

1. The Integration Partner initiates a "pull" from the Connector. Sample URL is: 

   <URL>/connector/api/2011-11/missingusers?provider=XYZ&clientID=123456&clubID=9876

   1. Provider (e.g. XYZ) is the InTouch given ID of your system (e.g. ACME)
   2. clientID (e.g. 123456) is the ID of the client. This is the top level entity. Also known as an enterprise, account, organization, customer.  A client can have many clubs within it.
   3. clubID (e.g. 9876) is the ID of the specific club for this data.  This is the physical health club with a real street address, etc...
2. This will return a list of ALL users in the Connector database that meet one of two conditions
   1. The Connector does not have a user ID for that user and provider (i.e. new user in InTouch which was sent to the Connector, but no user ID yet for the ACME provider)
   2. The record has been modified since the last time the provider fetched (and sync'ed) the user (i.e. updated user in InTouch which was sent to the Connector, so the modified timestamp is newer than the modified timestamp of the last callback for the provider)
3. Note this list is limited to 50 records, last in first out.  Important: It is imperative that this list of returned records is not left so that it grows and grows as this could mean that some data gets orphaned. 
4. How the Integration Partner handles the lookup is up to them. What MUST happen is a callback to the Connector which is an acknowledgement that "I've sync'ed this user". A sample web service call here is a POST to <URL>/connector/api/2011-11/user/callback with the ID from the system making the pull (example below)
5. After this callback is made, the user will not appear in the pull call again (unless the user is updated again in InTouch)

Examples

Example Pull Response

<user>
	<userInfo>
		<connectorUUID>ce507497-992c-4eb8-bc7e-b0d46e7aa53f</connectorUUID>
		<createdBy>INTOUCH</createdBy>
		<createdDate>2012-06-28T18:26:29.101Z</createdDate>
		<modifiedBy>INTOUCH</modifiedBy>
		<modifiedDate>2012-07-03T23:55:49.937Z</modifiedDate>
		<firstname>John</firstname>
		<lastname>Doe</lastname>
		<userStatus>ACTIVE</userStatus>
		<userType>PROSPECT</userType>
		<address1/>
		<city/>
		<zipcode/>
		<country>US</country>
		<mobile>(555) 555-5555</mobile>
		<email>jdoe@email.com</email>
		<homePhone/>
		<workPhone>(213) 688-1441</workPhone>
		<company/>
	</userInfo>
	<userInfo>
		snip... repeat userInfo segments here
	</userInfo>
</user>

Callback Example

<user>
	<providerInfo>
		<identifier>XYZ</identifier>
		<clientID>123456</clientID>
		<clubID>9876</clubID>
		<recordID>1001</recordID>
	</providerInfo>
	<userInfo>
		<connectorUUID>ce507497-992c-4eb8-bc7e-b0d46e7aa53f</connectorUUID>
	</userInfo>
</user>