Versions Compared

Version Old Version 33 New Version Current
Changes made by

Collin Peters (Unlicensed)

Caitlin Tupper

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Date:               June 8, 2011

Last Updated: May 7, 2012

Contributors:          

Contributors
modelist
showCounttrue

Table Of Contents

Table of Contents

...


Section


Column
width80%


Panel
borderColor#01ACEC
bgColor#01ACEC
borderWidth2

HOME > SET UP > INTEGRATIONS & PARTNER PAGES > DEVELOPER GUIDE


 


About

This document will outline the steps necessary to get your platform integrated with the Connector platform, which will 'connect' your platform with InTouch and 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

...

Integration Options

the Overview page for that.

The first step in getting integrated is to talk to us so we can discuss the various options for integration. After discussion we can agree on what features will be supported and how the integration will work.

There are two main sub-documents within this guide.  Based on the features of the integration that are agreed upon, you will require either one or both

  • Connector Partner Integration Guide - This guide is required if you plan on receiving data from the Connector.  This is the most common use case (i.e. users created in InTouch are sent to your system)
  • Connector API Guide - This guide is required only if you plan on sending data to the Connector (i.e. users created in your system are sent to InTouch)

Integration Options

 

Info
titleIMPORTANT

Before any technical details can be discussed, there needs be agreement on what level of functionality will be provided in the integration between InTouch and your system via the Connector.   This

...

is extremely

...

 important as it has large implications on what the technical requirements will be.  You should not proceed further without a detailed work plan of what is to be built

 

The main questions that

...

require an answer

  1. Is the integration going be a two way synchronization, or one way?

...

  1.  i.e. will you be receiving data, sending data, or both.  The most common and simple integration is usually one-way where users created in InTouch are automatically created in your system.

...

Incoming (Your System -> Connector)

Important: This section is only required if your system will be sending data to InTouch via the Connector.

Notes

  • Currently (April 2012) there is no security (i.e. username/password) on the web service calls made to the Connector. 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 does not exist on the Connector web service API calls.  This will be added in the next release of the Connector
  • 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 that before actual web service calls can be made, work must be done by InTouch in order to make it aware of your platform

General Info

  1.  
    1. If you will be receiving data, then you will need the 'Conenctor Partner Integration Guide'
    2. If you will be sending data, then you will need the 'Connector API Guide'
  2. What data is going to be included?
    1. Prospects (a.k.a. leads) 
    2. Members

...

 

Technical Discussion

Outgoing (Connector -> Your System)

This section is about the requirements for the Connector to send data to your system.  If your system is NOT going to be receiving data from the Connector then this section does NOT apply.

First off, your system MUST provide some type of web services via an 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 by InTouch in order to add support to the Connector to make API calls to your system.  When calling your web services the Connector will obviously use whatever technology is required (e.g. soap, rest, etc...).  Note that the Connector is a Java application, if you have a Java library already prepared that you can provide to InTouch it will greatly simply the work required on our part to make calls to your web service

Web Service Calls Required By Your API

The Connector sending data to your system by making web services calls to your API

  1. Prospects - API calls required
    1. Create a prospect
    2. Update a prospect
    3. Note: A single 'Save prospect' method is also acceptable
  2. Members - API calls required
    1. Create a member
    2. Update a 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. 
  3. Staff Owner for prospects - API calls required
    1. Fetch list of staff - The email address must be accessible in order for the Connector to associate certain records together
    2. Notes
      1. Staff owner is optional. If staff owner for prospects is not supported then it is up to your system to handle this scenario  
      2. See below for details on staff synchronization.  
      3. 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, existing staff, etc...)
  4. Lead Sources - When receiving prospects, the lead source can optionally be included.  
    1. API calls required
      1. Fetch list of lead sources
      2. Create lead source
      3. Update lead source
    2. Note: See below for details on lead source synchronization
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.

General 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
    1. Ex/Former members
  2. If prospects, is any additional data to be included?
    1. Staff Owner of Lead
    2. Lead Source of Lead
    3. Trial information

Depending on your answers to steps 2 and 3, various requirements will need to be met. For example, if you wish to receive prospects with a staff owner, your web service must provide a method for the Connector to get a list of staff.  The details of these requirements are outlined in the companion documents

General Information

This section outlines some common information about the Connector.

Clubs

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)

...

within

...

it

...

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

Web Service API Calls

  • Users (prospects and members) - the Connector has one call to save all types of users (i.e. both prospects and members). There is a user_type field which is used to differentiate between the two.
  • Staff
  • Lead sources

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)

<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:

Code Block
titleRequest using GET
http://<domain>/connector/api/2011-11/user?provider=PROVIDER_ID?client_id=xxxx&club_id=xxxx&recordID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Code Block
languagehtml/xml
titleResponse
<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

Code Block
languagehtml/xml
titleRequest
<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

Code Block
languagehtml/xml
titleResponse
<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 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

Code Block
<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.

Code Block
titleStaff Web Service URL
http://<domain>/connector/api/2011-11/staff

Synchronizing Staff

.  

Synchronizing Staff

Info

This information only applies if your integration with the Connector is going to support including a staff owner for new prospects. Please see the sub-documents within the guide for additional staff notes when sending, or receiving, prospects

When a new client is launched on the Connector, it is more than likely that they have already been using one or more of the systems

...

for awhile.  This means that each system may already have staff in it.  This presents a problem for

...

integrations that will support assigning a staff owner to a prospect or a member.

...

 Namely, how do we synchronize the staff list so that the staff in system A are mapped to the staff in system B

...

?  

Note: the Connector does not attempt to create staff in any

...

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

...

systems 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:

...

  • To support staff, 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

...

Synchronizing Lead Sources

...

The Connector supports lead sources as well.  

Code Block
titleLead Web Service URL
http://<domain>/connector/api/2011-11/leadsource

...

Info

This information only applies if your integration with the Connector is going to support including a lead source for new prospects. Please see the sub-documents within the guide for additional lead source notes when sending, or receiving, prospects

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.

...

  • To support lead sources, your API MUST provide a call to get a list of lead sources. 

...

    • Note that 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.
    • Note: If your system provides the ability to look for a specific lead source by name then we can use that as well
  • 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
Code Block
languagehtml/xml
titleRequest
<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>
Code Block
languagehtml/xml
titleResponse
<response xmlns="http://www.intouchfollowup.com/api/2011-11">
   <uuid>cf912bbd-7d10-41a5-b37e-1e11beff4e0c</uuid>
</response>
Fetch Single Lead Source
Code Block
titleRequest
http://<domain>/connector/api/2011-11/leadsource?provider=INTOUCH&client_id=1111&club_id=11111111-1111-1111-1111-111111111111&identifier=FACEBOOK
Code Block
languagehtml/xml
titleResponse
<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
Code Block
titleSample URL
http://<domain>/connector/api/2011-11/leadsource?provider=INTOUCH&client_id=1111&club_id=11111111-1111-1111-1111-111111111111
Code Block
languagehtml/xml
titleResponse
 <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

Code Block
languagehtml/xml
titleSample error XML
<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

...