Date: June 8, 2011

Last Updated: April 17, 2012

Contributors:

Table Of Contents

Objective/Purpose

This document will outline the steps necessary to get your platform integrated with the Connector platform, which will 'connect' your platform with multiple other 3rd-party platforms with no additional effort.
This document assumes you know what the Connector is and does not include an overview of it (please see “Connector – Overview.pdf”)

Notes/Questions

Currently (April 2012) there is no security (i.e. username/password) on the web service calls. This will obviously change soon but for now it is simply ‘security through obscurity’ in the sense that the GUIDs provide a level of security because they effectively cannot be guessed
Currently (April 2012) SSL/HTTPS is not supported. This will be added shortly

Introduction

In order to get your platform integrated with the Connector the following steps will occur

Agreement between InTouch and you on what level of functionality will be provided. Note that in order for the Connector to support sending information to your system, it must support the necessary API calls, and work must be done to add support to the Connector to make those web service calls.
Support for the following options is available in the Connector
- Data In (i.e. Your system making web service calls to the Connector)
  - Contacts (prospects and members) - the Connector has one call to save both prospects and members. There is a user_type field which is used to differentiate between the two.
  - Staff
  - Lead sources
- Data Out (i.e. Connector making web services calls to your API)
  - Contacts
    - Creation of a prospect/member in your system when a prospect/member is added to the Connector from another system
    - Update of a prospect/member in your system when a prospect/member is updated in the Connector by another system
    - Note: Conversion of a prospect to a member is handled on a case-by-case basis
  - Staff - Note: Please see the section below on the staff synchronization process
  - Lead Sources - Note: Please see the section below on the lead source synchronization process
Connector is built using ReST web services and currently supports XML payloads.
- Note: When calling your web services the Connector will obviously use whatever technology is required
A Java library is available to communicate with Connector to ease your development should you be a Java shop
Our QA environment which you can use to develop against is http://qa.intouchfollowup.com/connector/api/2011-11/user
- Note: Before actual web service calls can be made, work must be done in order to support your platform as per the details above.
- Email cpeters@intouchfollowup.com to get set up. The process is that you will need to give us the club/location IDs on your side and we will match them to a test club/location in the InTouch system. Once that information has been entered into InTouch you can start making web service calls

Technical Discussion

Connector -> Your System

This section is about the requirements for the Connector to send data to your system. First off, your system MUST provide some type of API that the Connector can call. The required calls in order to support integration are listed below. Once baseline features are agreed upon, work will need to be completed in order to add support to the Connector to make API calls to your system. Note that the Connector is a Java application and ideally you will provide a Java library which implements your API.

Getting Started

In order to get your system integrated with the Connector, the following features must be discussed between us, and agreement reached on which of these features will be supported

Prospects - Your API must implement the following methods in order to allow the Connector to create prospects
1. Create prospect
2. Update prospect
3. Note: A single 'Save prospect' method is also acceptable
Members - Your API must implement the following methods in order to allow the Connector to create members
1. Create member
2. Update member
3. Note: A single 'Save member' method is also acceptable
4. Note: The process of converting a prospect to a member is unique per system.
Staff Owner for prospects - When receiving prospects, the staff owner can optionally be included.
1. Your API must implement the following methods in order for the Connector to sync staff
  1. Fetch list of staff - The email address must be accessible in order for the Connector to associate certain records together
2. See below for notes on staff synchronization.
3. Note the Connector does NOT attempt to create or update staff in any system due to the high level of complexity and overhead of creating staff (i.e. permissions, etc...)
Lead Sources - When receiving prospects, the lead source can optionally be included.
1. Your API must implement the following methods in order for the Connector to sync lead sources
  1. Fetch list of lead sources
  2. Create lead source
  3. Update lead source
2. See below for notes on lead source synchronization

Your System -> Connector

General Info

The Connector is built on the concept of one fitness club (i.e. one physical location) belonging to one client. One client may have many clubs (i.e. a 10 location chain). All of the entities that the Connector works with (prospects, members, staff, lead sources) must belong to one client, and one club within that client. It is important to note that all communication with the Connector is done using the IDs from YOUR SYSTEM. While you can track the GUIDs that the Connector returns to you, you should not communicate with the Connector using these GUIDs. Think of this way, when you make a call to the Connector you are saying: I am 'PROVIDER X', here is a prospect record that has the ID 123456 in my system, and it belongs to club 123 within the client 456.

All calls made to the Connector must include

Provider ID - Each 3rd party integrating with the Connector will be given a unique ID which identifies you
Client ID - As this is a multi-tenant system all requests must include the client ID.
Club ID - Each entity must belong to a club and as such the club ID is required
Record ID - The ID within your system that you are working with

Working With User Records

URL: http://<domain>/connector/api/2011-11/user

Fields:

Name	Description	Details
<firstname>	First name	Mandatory TBD - Restrictions (max length, etc..)
<lastname>	Last name	Mandatory TBD - Restrictions (max length, etc..)
<userStatus>	The status of the user	Mandatory Must be ‘ACTIVE’ or ‘INACTIVE’
<userType>	The type of the user	Mandatory Must be ‘PROSPECT’ or ‘MEMBER’
<birthdate>	Date of birth	Must be yyyy-mm-dd format
<gender>	Gender	Must be ‘M’ or ‘F’
<address1>	First address field	TBD - Restrictions (max length, etc..)
<address2>	Second address field (not supported in InTouch)	TBD - Restrictions (max length, etc..) Note: Currently InTouch only has one address field
<city>	City	TBD - Restrictions (max length, etc..)
<zipcode>	Zip Code or Postal Code	TBD - Restrictions (max length, etc..)
<state>	State or Province	TBD - Restrictions (max length, etc..)
<country>	Country (2 digit ISO code)	As per http://en.wikipedia.org/wiki/ISO_country_codes
<mobile>	Mobile number	TBD - Restrictions (max length, etc..)
<email>	Email address	TBD - Restrictions (max length, etc..)
<homePhone>	Home phone number	TBD - Restrictions (max length, etc..)
<workPhone>	Work phone number	TBD - Restrictions (max length, etc..)
<company>	Company	TBD - Restrictions (max length, etc..)

Fetching User Records

Fetching a user record simply requires two attributes included in a GET call to the user web service. Example:

http://<domain>/connector/api/2011-11/user?provider=PROVIDER_ID?client_id=xxxx&club_id=xxxx&recordID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

<user>
   <providerInfo>
      <identifier>PROVIDER_ID</identifier>
      <clientID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</clientID>
      <clubID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</clubID>
      <recordID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</recordID>
   </providerInfo>
   <userInfo>
      <firstname>Foo</firstname>
      <lastname>Bar</lastname>
      <birthdate>1972-03-12</birthdate>
      <gender>M</gender>
      <userStatus>ACTIVE</userStatus>
      <userType>PROSPECT</userType>
      <address1>1234 Fake St</address1>
      <address2>Apartment 1a</address2>
      <city>Spuzzum</city>
      <zipcode>12345</zipcode>
      <state>WA</state>
      <country>US</country>
      <mobile>555-555-5555</mobile>
      <email>foo@bar.com</email>
      <homePhone>555-666-6666</homePhone>
      <workPhone>555-777-7777</workPhone>
      <company>Acme Widgets</company>
      <createdBy>INTOUCH</createdBy>
      <createdDate>2012-04-10T04:11:07.023Z</createdDate>
      <modifiedBy>INTOUCH</modifiedBy>
      <modifiedDate>2012-04-10T04:11:07.023Z</modifiedDate>
   </userInfo>
</user>

Saving User Records

Here is a sample piece of XML which should be POST’ed to the user web service

<user>
   <providerInfo>
      <identifier>PROVIDER_ID</identifier>
      <clientID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</clientID>
      <clubID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</clubID>
      <recordID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</recordID>
   </ providerInfo >
   <userInfo>
      <firstname>Foo</firstname>
      <lastname>Bar</lastname>
      <userStatus>ACTIVE</userStatus>
      <userType>PROSPECT</userType>
   </userInfo>
</user>

Details

The <user> tag needs to wrap the entire record
Note: Though shown as GUID/UUIDs, the values for the IDs (identifiers) can effectively be anything; it does not have to be a real GUID/UUID.
- Reminder: The value of the <recordID> tag is YOUR identifier. ALL communication with the Connector is done using your identifier.
The <providerInfo>tag provides all the information necessary for Connector to process the record. This includes
- <clientID>: The ID number of the client for this user record in the source provider (i.e. your system)
- <clubID>: The ID number of the location for this user record in the source provider.
- <recordID>: The ID number of the user in the source provider
- <identifier>: This is a set identifier which will be used to know who sent the record (i.e. the provider). This value will be given to you and must be sent for every web service call
The <userInfo> tag provides all the details for the actual user. Please see the user fields table for full details.

Result

The following XML is returned from a save call

<response xmlns="http://www.intouchfollowup.com/api/2011-11">
   <uuid>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</uuid>
</response>

The return value contains a <response> element which contains the UUID of the record within the Connector. Note: Though you may save this ID in your system it is not necessary as all communication with the Connector is done using your own identifiers

Saving Lead/Opportunity Data

For prospects, the Connector allows you to pass in a lead (aka opportunity) owner, as well as a lead source. The request looks like

<user>
   <providerInfo ... snipped for brevity />
   <userInfo ... snipped for brevity />
   <leadInfo>
      <leadSource>FACEBOOK</leadSource>
      <ownerID>6b85b27e-5028-4b23-a1e2-f3aa5bf3909b</ownerID>
   </leadInfo>
</user>

Note that the <leadInfo> section is optional, and that the <leadSource> and <ownerID> fields can either both be set, or just one of them can be set. If your system does not support staff, or lead sources, then these can be ignored
The ID values for the staff owner and lead source are again, the ID values from your system.

Staff Are Users Too

The Connector supports the saving of staff as well. The staff web service has a different URL but is syntactically identical to the user web service with the exception that the <userType> element must be STAFF.

http://<domain>/connector/api/2011-11/staff

Synchronizing Staff

When a new client is launched on the Connector, it is more than likely that they have been using one or more of the systems being integrated for awhile. This means that each system may already have staff in it. This presents a problem for systems that support assigning a staff owner to a prospect or a member. The question is, how do we synchronize the staff list so that the staff in system A are mapped to the staff in system B. Note that the Connector does not attempt to create staff in any remote system. It only tries to associate existing staff records with each. The reason for this is the complexity, overhead, and restrictions surrounding staff. For example, in most system the process of creating staff is not simple and requires setting attributes that the Connector knows nothing about (for example, roles or permissions)

The Connector attempts to associate existing staff records as follows:

Your API MUST provide a call to get a list of staff. If your system does not provide this call, we cannot support staff synchronization with your system
The Connector will make a call to fetch the list of all staff, and then attempt to make a match on the email address.
- Note: If your system provides the ability to look for a specific staff by email address then we can use that as well
If the Connector cannot make a match on email address, then the look up fails. At this point, any leads created that are assigned to the failed staff will be sent to your system with no staff assigned. Your system must be able to handle receiving leads that do not have an owner and assign them correctly as you desire
If the Connector can make a match on the email address, then the staff synchronization is complete, and prospect records can be sent to your system with the correct staff ID

Lead Sources

The Connector supports lead sources as well.

http://<domain>/connector/api/2011-11/leadsource

Synchronizing Lead Sources

Synchronizing lead sources is very similar to synchronizing staff except if there is the ability to create a lead source, the Connector will use it.

Your API must provide a call to get a list of lead sources.
- If this is not provided, and only a create call is provided, then InTouch will need to be considered the 'master' of the lead source list and all lead sources will be defined there and sent to your system
The Connector will make a call to fetch the list of all lead sources, and then attempt to make a match on the lead source name.
- Note: The comparison will be case in-sensitive.
If the Connector cannot make a match on name, then the look up fails.
- If your API provides a method to create a lead source, the Connector will then make a call to create the lead source in your system
- If your API does not provide a method to create a lead source, then any leads created that are assigned to that failed lead source will be sent to your system with no lead source assigned. Your system must be able to handle receiving leads that do not have a lead source

Save Lead Source

<leadSource>
   <providerInfo>
      <identifier>PROVIDER_ID</identifier>
      <clientID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</clientID>
      <clubID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</clubID>
      <recordID>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</recordID>
   </providerInfo>
   <leadInfo>
      <name>Facebook</name>
      <active>true</active>
   </leadInfo>
</leadSource>

<response xmlns="http://www.intouchfollowup.com/api/2011-11">
   <uuid>cf912bbd-7d10-41a5-b37e-1e11beff4e0c</uuid>
</response>

Fetch Single Lead Source

http://<domain>/connector/api/2011-11/leadsource?provider=INTOUCH&client_id=1111&club_id=11111111-1111-1111-1111-111111111111&identifier=FACEBOOK

<leadSource>
   <providerInfo>
      <identifier>INTOUCH</identifier>
      <clientID>1111</clientID>
      <clubID>11111111-1111-1111-1111-111111111111</clubID>
      <recordID>FACEBOOK</recordID>
   </providerInfo>
   <leadInfo>
      <createdBy>INTOUCH</createdBy>
      <createdDate>2012-04-17T21:58:47.758Z</createdDate>
      <modifiedBy>INTOUCH</modifiedBy>
      <modifiedDate>2012-04-17T21:59:29.673Z</modifiedDate>
      <name>Facebook</name>
      <active>true</active>
   </leadInfo>
</leadSource>

Fetch Lead Sources

http://<domain>/connector/api/2011-11/leadsource?provider=INTOUCH&client_id=1111&club_id=11111111-1111-1111-1111-111111111111

 <leadSources>
   <leadSource>
      <createdBy>INTOUCH</createdBy>
      <createdDate>2012-04-17T21:58:47.758Z</createdDate>
      <modifiedBy>INTOUCH</modifiedBy>
      <modifiedDate>2012-04-17T21:59:29.673Z</modifiedDate>
      <name>Facebook</name>
      <active>true</active>
   </leadSource>
   <leadSource>
      <createdBy>INTOUCH</createdBy>
      <createdDate>2012-04-17T21:58:47.758Z</createdDate>
      <modifiedBy>INTOUCH</modifiedBy>
      <modifiedDate>2012-04-17T21:59:29.673Z</modifiedDate>
      <name>Corporate</name>
      <active>true</active>
   </leadSource>
</leadSources>

Errors

The Connector is build using ReSTful style web services, which is simply regular old HTTP. This means that if you make a request to fetch a user and that user isn’t found you will actually get an HTTP response status of 404 'Not Found'. Similarly, if any type of error occurrs in the backend, an HTTP response code in the 400-599 range will be returned (these are the error codes).

In regards to real errors: from a high level this type of error should be returned depending on what has happened

<error xmlns="http://www.intouchfollowup.com/api/2011-11">
   <reason>UNKNOWN</reason>
   <errorUUID>cecfeef8-24ef-4107-8d8b-534ce6a999b8</errorUUID>
   <message>additional error details</message>
</error>

Details

<reason>: will be an identifier that will try to narrow down the type of error. Will show ‘UNKNOWN’ if the error type isn’t known. Current examples are: ‘VALIDATION’, ‘DATABASE’
<errorUUID>: This is a regular old UUID which you can pass on to InTouch support which will simply let us have an easy way to find the error in the Connector logs
<message>: the actual details of the error. Note that currently this is just the stack trace from the real error in the backend so some errors might be cryptic

Appendix

Turnup

This section details what is necessary to get a new client turned-up on the Connector. The turn-up process for your system may vary slightly from other systems if there are any custom configuration options.

Information required

The client ID number in your system
The club ID numbers in your system (1 for every club)
Connection information (not required for full SaaS platforms)
- IP
- Username/Password
- Scheme (http/s)
Any custom configuration options built into the Connector for your platform

Security

Additional security features will be built into each version of the Connector. Future features will include

Security token - each system integrating will have to provide a security token so that we know its really you
Username & password - each system making calls to the Connector will require a username & password
Per club access - in order to make calls to a particular client or club, access will have to be enabled