...
- This document will outline the steps necessary to integrate with the Connector platform
- This document assumes the user knows what Connector is does not include an overview of it (please see or request “Connector – Overview.docx”)
Notes/Questions
- The Connector is currently (as of Oct 14, 2011) considered to be in stage 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. Email me (Collin) if you encounter any issues. Thanks.
- Currently (Oct 14, 2011) 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
About
- Connector is built using ReST web services and currently supports XML payloads. JSON might be supported in the future if requested.
- Currently, the available service is for saving and fetching users, and retrieving a list of staff
- The URL for the user service is http://<domain>/connector/api/2011-11/user. It supports a GET operation to retrieve a user, and a POST operation to save a user
- The URL for the staff service is http://<domain>/connector/api/2011-11/staff. It supports a GET operation to retrieve the list of staff
- Our QA environment which you can use to develop against is http://qa.intouchfollowup.com/connector/api/2011-11/user
- 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
...
About
Technical Discussion
Working With User Records
URL: http://<domain>/connector/api/2011-11/user
Fields:
Name | Description | Details |
<firstname> | First name | Mandatory |
<lastname> | Last name | Mandatory |
<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 |
|
<address2> | Second address field (not supported in InTouch) |
|
<city> | City |
|
<zipcode> | Zip Code or Postal Code |
|
<state> | State or Province |
|
<country> | Country (2 digit ISO code) |
|
<mobile> | Mobile number |
|
<email> | Email address |
|
<homePhone> | Home phone number |
|
<workPhone> | Work phone number |
|
<company> | Company |
|
Fetching User Records
Fetching a user record simply requires two attributes included in a GET call to the user web service. Example:
| Code Block | ||
|---|---|---|
| ||
http://<domain>/connector/api/2011-11/user?uuid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&provider=PROVIDER_ID |
...
Here is a sample piece of XML which will be returned
<user>
<providerInfo>
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
<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>
...
<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>
...
<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 (note: subject to change before launch)
<user>
<providerInfo>
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
<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>
...
>
<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.
- 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.
...