Connect to Web Services – a technical view

This is a technical walk through of “things to know” when you are setting up a web service connection for use with Cacidi Extreme and LiveMerge.  In this tutorial we will be using a php based web page, that can be download a long with a simple data dump HERE. The output from the web service is expected to be in the JSON form of data encoding.

JSON
The web services connection expect data to be in the form of JSON. A data format that can be serialized just like xml, but in a much more compact form.

One record:
{userid:”1001, “firstname:”Richard”, surname:”Andersen”}

More record:
[{userid:”1001, “firstname:”Richard”, surname:”Andersen”},{userid:”1002 “firstname:”Mona”, surname:”Andersen”}]

For those familiar with the way Cacidi Extreme and LiveMerge normally displays data, nothing is changed – and all normal functionality of these two plugins works like connection to a file, ODBC or mySQL database.

Preconditions
A database, in this tutorial a mySQL, PHP must be installed/enabled and the sql dump imported/created on the mySQL server. The login information stated in the testconnect.php must be corrected to match your setup.

The project
WebserviceProject

To setup the project, create a new project using the “Select a base setting”.. or modify and existing project setting, by selecting the “WebService” in the connection popup menu. The UI change to show and IP number, Port, User Name and Password. Enter the right information for your setup. Mine is Localhost/CacidiDynamicWeb/testconnect.php – the connect file is on my local machine in a sub folder named CacidiDynamicWeb. Remember to enable php to have this to work. Press the “Refresh” button, to make the connection

Technical description of the Call Methods
There are five different methods that the web service will use to call the web service page, these methods is used to fetch or send data to the web services, the web page the services is running on will react in different ways depending on which Call Methods is used.

fetchRecordList
The fetchRecordList request a list of records to put in the popup menu of LiveMerge to choose a record to drag to the page

Parameters must be select is the idname field and the listname fields, in addition a search info can be set, and if grouping is used the groupbyname must be provided.

http://localhost/CacidiDynamicWeb/testconnect.php?connecttype=fetchRecordList&idname=ID&listname=Navn&groupbyname=Navn&search=stof

Example of return answer:
[{“ID”:”109″,”Navn”:”Bern”},{“ID”:”114″,”Navn”:”Bjarnum”},{“ID”:”37″,”Navn”:”Buffalo”},{“ID”:”65″,”Navn”:”Carolina”},{“ID”:”42″,”Navn”:”Eldorado”},{“ID”:”127″,”Navn”:”Kent”},{“ID”:”69″,”Navn”:”Laredo”},{“ID”:”47″,”Navn”:”Lucera”},{“ID”:”132″,”Navn”:”Metro”},{“ID”:”123″,”Navn”:”Molly”},{“ID”:”137″,”Navn”:”Nardo”},{“ID”:”164″,”Navn”:”Nr. 2″},{“ID”:”169″,”Navn”:”Nr. 5″},{“ID”:”174″,”Navn”:”Nr. 6″},{“ID”:”178″,”Navn”:”Nr. 9″},{“ID”:”51″,”Navn”:”Orlando”},{“ID”:”141″,”Navn”:”Pedro”},{“ID”:”55″,”Navn”:”Pireus”},{“ID”:”60″,”Navn”:”Valencia”},{“ID”:”119″,”Navn”:”Zorro”}]

fetchColumnList
The fetchColumnList is asking for a list of field names for used for merging data to text, or image fields.

http://localhost/CacidiDynamicWeb/testconnect.php?connecttype=fetchColumnList

Example of return answer:
[“ID”,”Art”,”Varenr”,”Navn”,”Color”,”H”,”L”,”D”,”Price”,”Description”,”ItemDesign”,”Path”,”TimeStamp”]

fetchSpecificRecord
The fetchSpecicRecord is used for updating and when dragging a single record using LiveMerge.

Parameters must be select is the idname field and the id value field, if grouping is used the groupbyname must be provided.

http://localhost/CacidiDynamicWeb/testconnect.php?connecttype=fetchSpecificRecord&idname=ID&id=42&groupbyname=Navn

Example of return answer if using the groupbyname:
[{“ID”:”42″,”Art”:”Stofsofa”,”Varenr”:”09580″,”Navn”:”Eldorado”,”Color”:”Sort”,”H”:”75″,”L”:”195″,”D”:”90″,”Price”:”22.150,-“,”Description”:”Venis nulput nostrud dit ex esequam quisl iusto digna facidunt la feu feu feu facin utpatie facilla con erostrud et lum vel er aliquamet iure molum del ut utat. Ut lore eugue er adit lan eriure dipiscil utpat, vent am alismod.\r”,”ItemDesign”:null,”Path”:null,”TimeStamp”:”2015-05-26 15:17:59″},{“ID”:”43″,”Art”:”Stofsofa”,”Varenr”:”09581″,”Navn”:”Eldorado”,”Color”:”Brun”,”H”:”75″,”L”:”195″,”D”:”90″,”Price”:”18.450,-“,”Description”:”Venis nulput nostrud dit ex esequam quisl iusto digna facidunt la feu feu feu facin utpatie facilla con erostrud et lum vel er aliquamet iure molum del ut utat. Ut lore eugue er adit lan eriure dipiscil utpat, vent am alismod.\r”,”ItemDesign”:null,”Path”:null,”TimeStamp”:”2015-05-26 15:17:59″}]

Multiple records is send back and parsed

No Grouping

http://localhost/CacidiDynamicWeb/testconnect.php?connecttype=fetchSpecificRecord&idname=ID&id=42

Example of return answer with no grouping:
[{“ID”:”42″,”Art”:”Stofsofa”,”Varenr”:”09580″,”Navn”:”Eldorado”,”Color”:”Sort”,”H”:”75″,”L”:”195″,”D”:”90″,”Price”:”22.150,-“,”Description”:”Venis nulput nostrud dit ex esequam quisl iusto digna facidunt la feu feu feu facin utpatie facilla con erostrud et lum vel er aliquamet iure molum del ut utat. Ut lore eugue er adit lan eriure dipiscil utpat, vent am alismod.\r”,”ItemDesign”:null,”Path”:null,”TimeStamp”:”2015-05-26 15:17:59″}]

fetchRecordGroupLoop
Use of fetchGroupLoop is mainly issued from Extreme. The function will drag all data for a complete run in Extreme, e.g. for use on many, many pages. The search is a way of limit the number of records.

Parameters must be select is the groupbyname must be provided.

http://localhost/CacidiDynamicWeb/testconnect.php?connecttype=fetchRecordGroupLoop&groupbyname=Navn&search=

Example of return answer:
[{“ID”:”3″,”Art”:”Lædersofa”,”Varenr”:”10B452″,”Navn”:”Bugatti”,”Color”:”BrCun”,”H”:”70″,”L”:”210″,”D”:”90″,”Price”:”229.350,-“,”Description”:”Venis nulput nostrud dit ex esequam quisl iusto”,”ItemDesign”:”AHListeTop.inds”,”Path”:”XXXX”,”TimeStamp”:”2015-05-26 15:17:59″},{“ID”:”4″,”Art”:”Lædersofa”,”Varenr”:”10453″,”Navn”:”Bugatti”,”Color”:”Hvid”,”H”:”70″,”L”:”210″,”D”:”90″,”Price”:”22.400,-“,”Description”:”Venis nulput nostrud dit ex esequam quisl iusto digna “,”ItemDesign”:null,”Path”:null,”TimeStamp”:”2015-05-26 15:17:59″},{“ID”:”5″,”Art”:”Lædersofa”,”Varenr”:”10454″,”Navn”:”Bugatti”,”Color”:”Aubergine”,”H”:”70″,”L”:”210″,”D”:”90″,”Price”:”18.500,-“,”Description”:”Venis nulput nostrud dit ex esequam q”,”ItemDesign”:null,”Path”:null,”TimeStamp”:”2015-05-26 15:17:59″},{“ID”:”6″,”Art”:”Lædersofa”,”Varenr”:”10455″,… and many more..

updateSpecificRecord
When a e.g.. text field is changed in a text frame in InDesign, the user can select the frame and in the palette fly-out menu choose “Update Base”, the data of the fields used in the text frame is send to the web service page.

http://localhost/CacidiDynamicWeb/testconnect.php?connecttype=updateSpecificRecord&idname=ID&id=42&fieldtoupdate=price&fielddata=100

No return data is expected or parsed.

PHP web page At-a-Glance
The php page has three parts

1) Receiving the web arguments, like connection type, id name, group information etc.
Just getting the vars, using $_GET[].

2) Creating the querying  string
Creating the string used for the query to collect data.

3) Collection the data and pack them in the son format
The received data objects is encoded as JSON using the standard php functions

Totally number of lines in the example is 150 lines

Added feature February 2024
Some web services can be very slow to deliver data, and for that purpose we have created the ability to adjust the standard 10 second timeout to what you need. Simply to add a file in the preference folder with the name of webserviceTimeOut.txt, and the contents of e.g. 60 for 60 second timeout.

Leave a Reply