...

• 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

• The Connector is currently (as of April 2012) considered to be in version 1 complete.  This means that the system should be stable, but there will be missing features that are scheduled to be implemented in future stages (see appendix). Email me (Collin) if you encounter any issues. Thanks.
• 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

...

Connector -> Your System

This section is about what it will look like when the Connector makes web service calls to your system

Getting Started

In order to get your system integrated with the Connector the following steps must occur

1. 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
2. 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. 
3. Staff - 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
4. Lead Sources - 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

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. 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. If such a library is not available then additional work will be required on the InTouch side to complete the integration.

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

1. 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
2. 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. 
3. 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...)
4. 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.

...

• 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 you can only request data within your 'sandbox'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

...

• 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.If the lead source or staff owner do not exist in the Connector, the record will be rejected!  Note: This will be changed in an upcoming version of the Connector to not be so draconianthe 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.

...

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.  The  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 system B.  The problem is usually compounded by a few issues

1. Some systems do not have API calls to create or update staff. So how do we synchronize staff if we can't create them?
2. Sometimes staff have already been added to both systems?  Even if both systems have the ability to create staff in the API this doesn't help us.

...

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:

Lead Sources

The Connector supports lead sources as well.  

...

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.The solution of how the Connector attempts to overcome these issues is as follows:

...

 <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

For those unfamiliar with The Connector is build using ReSTful style web services, it is actually built on top of which is simply regular old HTTP. This means that (technically speaking) 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. I say technically speaking because the implementer of a web service doesn’t have to adhere to that. It is perfectly acceptable to give a normal HTTP response status of 200 and just have a different payload. All implementers need to be aware of how each web service works of course. Connector will be implemented in that if any type of real error occurred 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).

...

• 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

Future Phases

Version 2

• Security & SSL