• Introduction
• Source code
• Test the channel
• Debugging RESTful services

Introduction

This example uses RESTful calls to connect to Highrise CRM using their web service API. We use the Iguana Network API to read Contact information, and to insert new Contacts.

The insert process creates a Contact and returns a header message containing their unique id and a url in the Location field (picture below code). To add further information (contact details, tags etc) you need to update the person using this id.

Use net.http.get for reading contact details:

Use net.http.post to create new contacts:

I took a snap of an Iguana annotation showing the returned Header message (return H in code above). The Id of the new Contact is highlighted

Source code [top]

Here is the source code for the highrise module. To use it:

1. Create the channel using a From LLP component and a To Translator component
2. Paste the code for main() into the To Translator script
3. Create a new shared module called “highrise” and paste in the highrise module code.
4. Test using sample data.

Code for main():

require 'highrise'

URL_p='https://interfaceware.highrisehq.com/people.xml' -- url for people (create or read all)
URL_fs='https://interfaceware.highrisehq.com/people/70421633-fred-smith.xml' --individual example url for read

function main(Data)
   print(highrise,_G)
   local msg, name = hl7.parse({vmd = 'demo.vmd', data = Data})
   local T = highrise.InsertTemplate()
   T=mapPatientData(T,msg,name)

   -- read an individual contact from highrise
   local R,C,H = net.http.get{url=URL_fs,live=true,
      auth={username='Your Highrise API Token here', password='X'}}
   print(C,R,H)
   -- read all contacts (only change is the URL)
   R,C,H = net.http.get{url=URL_p,live=true,
       auth={username='Your Highrise API Token goes here', password='X'}}
   print(C,R,H)

   -- create a new contact in highrise
   R,C,H=net.http.post{url=URL_p,live=false,  -- live=true, -- for testing
      auth={username='Your Highrise API Token goes here', password='X'},
      headers={['Content-Type']='application/xml'},
      body=T:S()
   }
   print(C,R,H) -- code 201 (c=201) is a successful insert
end

function mapPatientData(Xml,Msg,Name)
   if Name=='ADT' then
      Xml.person["first-name"][1]=Msg.PID[5][1][2]
      Xml.person["last-name"][1]=Msg.PID[5][1][1][1]
   end
   return Xml
end

, 'fIncludeLineNumbers

Code for highrise module:

highrise={}

function highrise.InsertTemplate()
   return xml.parse
   {data=
      '<person>'..
      '  <first-name>#</first-name>'..
      '  <last-name>#</last-name>'..
--      '  <background>#</background>'..
--      '  <title>#</title>'..
--      '  <company-name>#</company-name>'..
      '</person>'
   }
end

function node.S(ANode)
   return tostring(ANode)
end

Possible modifications interesting notes etc:

• You need to use the API token from your own Highrise account to logon (replace “Your Highrise API Token here” on lines 14, 18 and 23 of main)
• Gotcha: you need placeholders like # in the XML template (highrise module), deleting them causes errors in mapPatientData() – try it and see if you want.
• There are three other Contact fields you can include in the insert <background>, <title> and <company-name>
• Adding personal details to contacts

• When I tried an insert including contact data (email, phone, address etc) the <contact-data> segment was ignored
• When I tried an insert with a <tag> segment the insert failed
• Try an update using the Contact Id in the returned Header Message (the H return in the code)
• The XML formats on the highrise API reference page are not 100% clear, I suggest using Highrise to update a contact , and looking at the returned XML.

Test the channel [top]

Follow these steps to test a channel with sample data:

1. Get some sample data, or use the standard Iguana sample.txt
2. Find the port number for the channel (see below)
3. Set the HL7 Simulator to the same port (below)
4. To slow down message transmission change the delay setting (below)
5. Run the channel

To test interactively and view annotations:

1. Import the sample data into Iguana
2. Use the message buttons in the script pane to step through the data

Hover over the LLP component in the dashboard, to find the port number:

Match the port number and change delay settings in the HL7 Simulator:

Debugging RESTful services [top]

One of the things that makes RESTful APIs so wonderful for inter-operability is the ease with which they can be debugged. Since most of them use HTTP basic authentication over HTTPS if you are wondering what is going on under the hood one can use a standard web browser. That’s one of the many beautiful aspects of RESTful APIs a means of integration.

That’s the reason why everyone in the industry that has an incentive to be easy to integrate with is headed in this direction. This is screen shot showing using Chrome to look at a person record for Highrise. Notice that schemas are not required.