Page Comparison

...

<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.
  • 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.  

...

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

...

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

Errors

For those unfamiliar with ReSTful style web services, it is actually built on top of 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 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