Metadata web services provide the programming interface to enable interaction between CXAIR and third-party software applications.

The web services offer open, platform-independent APIs which allow applications to access metadata relating to the core Search Engine and Index structures, while exposing interfaces that allow these applications to construct queries. These then initiate CXAIR queries or reports in a secure and non-invasive manner.

Calling CXAIR Web Services

The user must be logged into CXAIR to call the web services. This is performed by calling the Authenticate web service, and then returning a SessionID used to call all subsequent web services.

All of the web services operate over SSL connections and will only return data that the authenticated user is allowed access to.

All URL parameters are mandatory.

Web Service Tests Page

The Web Service Tests page can be accessed at the following URL:

http://<hostname>:<port>/<application name>/test/index.jsp

Click on the appropriate link to load a page where the parameters associated with each web service can be entered and tested.

Authenticate

This web services authenticates a user against an instance of CXAIR by silently logging into the system and returning a session identifier.

URL

/rest/authenticate

Parameters

The following parameters must be passed as POST:

Returns

SessionID as a string.

Example Output

58252c341fe49f57_e88015ad_0000013d4525b24c_8001

Search Engines

This web service lists all available search engines for the authenticated user.

URL

/rest/metadata/searchengines/<SessionID>

Parameters

Returns

Returns an array of JSON objects in the following format:

[{
name: String,
displayName: String,
indexes: [{
 name: String,
 displayName: String
 }]
}]

Example Output

[{"name":"1b5ff460-bde3-102f-8c00-6d1c97ab8273","displayName":"pipeline12072012.csv"},{"name":"1fd380f0-87c6-102f-bf08-9f703c3eed74","displayName":"Hospitality"},{"name":"36284080-ae5d-102f-8f1e-938050e9d02e","displayName":"Connexica"},{"name":"3f37b830-f517-102f-b64d-533b47feef0c","displayName":"Clearview"},{"name":"8f3d48f0-5f42-1030-ad70-0d332ae60bc8","displayName":"2012 New Features"},{"name":"9739a510-d4d9-102f-a0fd-dfa273b3291f","displayName":"Google"},{"name":"af08bca0-51b4-1030-9da3-91f3afeb2948","displayName":"Nebular"},{"name":"be02d350-b4b4-102f-82f9-5ba617ac9ccf","displayName":"pipeline12072012.csv"},{"name":"default","displayName":"default"},{"name":"e3646190-bc6b-102f-b770-4bdd12a0c006","displayName":"pipeline12072012.csv"},{"name":"fc72ab10-5e41-1030-b01c-bb95c52da156","displayName":"Multitenanted"},{"name":"HealthWare","displayName":"Health Demo Search Engine"},{"name":"Screenshots","displayName":"Standard Demo"}]

Indexes

This web service lists all indexes across all search engines, or for a specific search engine.

URL

/rest/indexes/<SessionID>

Parameters

Returns

Returns an array of JSON objects in the following format:

[{
name: String,
displayName: String
}]

Example Output

[{"name":"7e12fa20-4913-102f-9af2-5fd4716c636b","displayName":"NHS Finance"},{"name":"994f9ec0-5ccb-1030-8416-d132a8f71a3a","displayName":"Data Warehouse"},{"name":"ab772fb0-0a05-102f-8d90-7fa5e9235aca","displayName":"Docs 2011"},{"name":"Card Holder Details and Attendance","displayName":"Card Holder Details and Attendance"},{"name":"cxairaudit","displayName":"CXAIR Audit"},{"name":"Demo Seasons","displayName":"Demo Seasons"},{"name":"Health Theatres","displayName":"Theatres"},{"name":"MEFCO","displayName":"MEFCO"},{"name":"MidEssex","displayName":"Finance"},{"name":"NI14","displayName":"NI14"},{"name":"Personnel","displayName":"Personnel"}]

Data Source Groups

This web service lists all data source groups, either for all indexes or for those linked to a specific index.

URL

/rest/datasourcegroups/<SessionID>

Parameters

Returns

Returns an array of JSON objects in the following format:

[{
name: String,
displayName: String
}]

Example Output

[{"name":"994f9ec0-5ccb-1030-8416-d132a8f71a3a","displayName":"Data Warehouse"}]

Data Sources

This web service lists all data sources for either all data source groups or those linked to a specific data source group.

URL

/rest/datasources/<SessionID>

Parameters

Returns

Returns an array of JSON objects in the following format:

[{
name: String,
type: String <string, number, date>
format: (number or date format)
}]

Example Output

[{"name":"TPK","indexFields":[{"name":"TPK","type":"number"}]},{"name":"Transaction ID","indexFields":[{"name":"Transaction_ID","type":"string"}]},{"name":"Area Name","indexFields":[{"name":"Area_Name","type":"string"}]},{"name":"Region Name","indexFields":[{"name":"Region_Name","type":"string"}]},{"name":"Product Description","indexFields":[{"name":"Product_Description","type":"string"}]},{"name":"Sale Price","indexFields":[{"name":"Sale_Price","type":"number"}]},{"name":"MOP","indexFields":[{"name":"MOP","type":"string"}]},{"name":"Employee Name","indexFields":[{"name":"Employee_Name","type":"string"}]},{"name":"Day of Week","indexFields":[{"name":"Day_of_Week","type":"number"}]},{"name":"Quantity","indexFields":[{"name":"Quantity","type":"number"}]},{"name":"Loyalty Points","indexFields":[{"name":"Loyalty_Points","type":"number"}]},{"name":"Cost Price","indexFields":[{"name":"Cost_Price","type":"number"}]},{"name":"Loyalty Card","indexFields":[{"name":"Loyalty_Card","type":"string"}]},{"name":"Transaction Price","indexFields":[{"name":"Transaction_Price","type":"number"}]},{"name":"Branch Address","indexFields":[{"name":"Branch_Address","type":"string"}]},{"name":"Branch Code","indexFields":[{"name":"Branch_Code","type":"string"}]},{"name":"Branch Email","indexFields":[{"name":"Branch_Email","type":"string"}]}

Reports

This web service lists all folders and their contents for a specified user session.

URL

/rest/reports/<sessionID>

Returns

Returns an array of JSON objects in the following format:

[{
name: String,
folders: [{
name: String,
folders: …
reports: ...
}],
reports: [{
name: String,
description: String,
type: String,
searchEngine: String,
index: String
}]
]}

Example Output

[{"name":"admin","folders":[{"name":"Bug Testing","folders":[],"reports":[{"guid":"32dacd90-ae39-102f-86ac-bf50257fe4a1","name":"bug test 2","description":"","type":"crosstab"},{"guid":"d3469cf0-ae39-102f-86ac-bf50257fe4a1","name":"bug test 3","description":"","type":"crosstab"},{"guid":"fa649c20-ae38-102f-86ac-bf50257fe4a1","name":"bug test 1","description":"","type":"crosstab"}]},{"name":"Food Queries","folders":[],"reports":[{"guid":"1f9c16b0-a756-102f-abeb-5b4773419498","name":"beef","description":"all beef products","type":"query"},{"guid":"43cc9d70-a756-102f-abeb-5b4773419498","name":"lamb","description":"all lamb products","type":"query"},{"guid":"64dd87f0-a746-102f-abeb-5b4773419498","name":"chicken","description":"all chicken products","type":"query"}]},{"name":"Miscellaneous Folder","folders":[{"name":"ad73fc00-a8b4-102f-b7e2-3313a9eaf745","folders":[],"reports":[]},{"name":"de415ec0-a8d4-102f-b7e2-3313a9eaf745","folders":[],"reports":[]}],"reports":[{"guid":"164b3200-ae34-102f-86ac-bf50257fe4a1","name":"crosstab new function","description":"continuous data lines","type":"crosstab"},{"guid":"2db612d0-acc6-102f-b9f1-774661c27f84","name":"lancashire branches","description":"all branches in lancashire, wildcard query","type":"query"},{"guid":"5f0a4130-ae38-102f-86ac-bf50257fe4a1","name":"bug","description":"","type":"crosstab"},{"guid":"9f8dbe30-a8e3-102f-b7e2-3313a9eaf745","name":"Monthly Financial Overview","description":"","type":"venn"},{"guid":"ad73fc00-a8b4-102f-b7e2-3313a9eaf745","name":"demo dashboard","type":"dashboard"},{"guid":"de415ec0-a8d4-102f-b7e2-3313a9eaf745","name":"cross database dashboard","description":"","type":"dashboard"},{"guid":"fda79040-acc6-102f-b9f1-774661c27f84","name":"Sausage and Mash Sales","description":"","type":"venn"},{"guid":"fdc7be50-a8af-102f-b7e2-3313a9eaf745","name":"loyalty points","description":"average","type":"crosstab"}]},"reports":[]}]

Run Report

This web service runs a saved query or Crosstab and returns the results in JSON format.

URL

/rest/run/<SessionID>/<searchEngineName>/<reportGUID>

Parameters

Returns

Returns the results of the Query or Crosstab execution in the following format:

Query:

{
hits: Integer,
  headers: [{
       name: String,
       type: String,format: String
    }],
  documents: [{
       values: [String]
      }]
}

Crosstab:

{
  filters: [Name -> Value],
  filterLabels: [Name -> Value],
  rowCount: Integer,
  columnCount: Integer,
  rowLabels: [String],
  columnLabels: [String],
  aggregationLabels: [String],
  conditionalFormat: [Name -> Value],
  values: {
     [Key -> Value  <Key is "Row, Column">
   }
}

Example Output

Query:

{"hits":165001,"headers":[{"name":"Region Name","type":"string"},{"name":"Area Name","type":"string"},{"name":"Branch Name","type":"string"},{"name":"Transaction ID","type":"string"},{"name":"Transaction Day Description","type":"string"},{"name":"Transaction Date","type":"date","format":"dd/MM/yyyy HH:mm:ss"},{"name":"Day of Week","type":"number","format":"#0"},{"name":"Product Description","type":"string"},{"name":"Sale Price","type":"number","format":"#0.00"},{"name":"Quantity","type":"number","format":"#,0"},{"name":"Transaction Price","type":"number","format":"#0.00"},{"name":"Cost Price","type":"number","format":"#0.00"},{"name":"Employee Name","type":"string"},{"name":"Loyalty Card","type":"string"},{"name":"Loyalty Points","type":"number","format":"#,0"},{"name":"MOP","type":"string"},{"name":"Override Amount","type":"number","format":"#0.00"},{"name":"Branch Code","type":"string"},{"name":"Branch Email","type":"string"},{"name":"Branch Fax","type":"string"},{"name":"Branch Telephone","type":"string"},{"name":"Branch Town","type":"string"},{"name":"Till","type":"number","format":"#,0"},{"name":"TPK","type":"number","format":"#0"},{"name":"Transaction Day","type":"date","format":"dd"},{"name":"Transaction Month Description","type":"string"},{"name":"Transaction Year","type":"date","format":"yyyy"}],"documents":[{"values":["Northern England and Ireland","Newcastle and Middlesborough","Sunderland","1520839","Friday","09/01/2009 14:46:20","5","12 Mini ChickenBBQ Bites","1.99","5","9.95","1.37","CHRIS BIRRANE","N","994","Credit Card","0.00","48","Branch048@Acuma.co.uk","01915 234567","01915 123456","Sunderland","1","8","09","January","2009"]},{"values":["Southern England and Wales","South West England","Bristol","1527895","Tuesday","03/04/2007 00:08:36","2","Smart Chicken Fajita wrap","2.99","5","14.95","2.24","HANNAH WALLACE","Y","1,495","Cash","0.00","3","Branch003@Acuma.co.uk","01179 234567","01179 123456","Bristol","1","17","03","April","2007"]},{"values":["Midlands and East","Birmingham and North Midlands","Tamworth","1528766","Thursday","04/06/2009 18:55:19","4","Barbecue Chicken 30g","2.29","2","4.58","1.58","ANN WINTERS","N","458","Store Card","0.00","26","Branch026@Acuma.co.uk","01827 234567","01827 123456","Tamworth","6","36","04","June","2009"]},{"values":["Midlands and East","East Midlands","Newark","1528769","Monday","12/11/2007 10:55:26","1","Chicken Tikka Kebab","5.99","1","5.99","3.71","MARK BOWNES","Y","599","Debit Card","0.00","43","Branch043@Acuma.co.uk","01636 234567","01636 123456","Newark","2","39","12","November","2007"]},{"values":["Southern England and Wales","South East England","Bracknell","1532700","Thursday","05/02/2009 13:36:33","4","Smart Chicken Fajita wrap","2.99","1","2.99","2.24","TONYA HOING","N","299","Credit Card","0.00","30","Branch030@Acuma.co.uk","01344 234567","01344 123456","Bracknell","1","58","05","February","2009"]},{"values":["Southern England and Wales","North Wales","Oswestry","1538583","Thursday","12/04/2007 22:00:49","4","BBQ Chicken and Wedges 450g","5.19","1","5.19","3.68","JOHN FOWLER","N","519","Debit Card","0.00","34","Branch034@Acuma.co.uk","01691 234567","01691 123456","Oswestry","4","74","12","April","2007"]},{"values":["Scotland","Glasgow and SouthWest","Glasgow","1538586","Tuesday","11/12/2007 19:34:42","2","Pasta with Chicken,Smoked Bacon Sweetcorn380g","3.89","4","15.56","2.76","ROBERT CROFTS","N","1,556","Debit Card","0.00","10","Branch010@Acuma.co.uk","01413 234567","01413 123456","Glasgow","3","77","11","December","2007"]},{"values":["Northern England and Ireland","Manchester and Liverpool","Queenstown","1933200","Tuesday","10/07/2007 15:02:10","2","Choice BBQ Chicken and Potato wedges 40g","1.59","1","1.59","0.98","CHARLOTTE FARMER","Y","159","Store Card","0.00","22","Branch022@Acuma.co.uk","02380 234567","02380 123456","Queenstown","4","82","10","July","2007"]},{"values":["Midlands and East","East Anglia","Colchester","1933201","Thursday","12/04/2007 00:13:52","4","Healthy ChickenHotpot 40g","1.19","2","2.38","0.78","DARREN COCKING","N","238","Cash","0.00","32","Branch032@Acuma.co.uk","01206 234567","01206 123456","Colchester","1","83","12","April","2007"]},{"values":["Southern England and Wales","South West England","Bath","1933206","Saturday","08/07/2006 04:48:02","6","Chinese sliced chickenbreast 240g","7.49","4","29.96","4.64","GAVIN SHARP","Y","2,996","Debit Card","0.00","27","Branch027@Acuma.co.uk","01225 234567","01225 123456","Bath","6","88","08","July","2006"]},{"values":["Southern England and Wales","South West England","Falmouth","1933230","Wednesday","05/11/2008 20:28:22","3","Smart Chicken Fajita wrap","2.99","3","8.97","2.24","LEE WALKER","N","897","Debit Card","0.00","35","Branch035@Acuma.co.uk","01320 234567","01320 123456","Falmouth","5","96","05","November","2008"]},{"values":["Southern England and Wales","South East England","Bracknell","1933238","Wednesday","05/11/2008 21:18:49","3","Smart Chicken Fajita wrap","2.99","3","8.97","2.24","ALLISON COWEN","N","897","Cash","0.00","30","Branch030@Acuma.co.uk","01344 234567","01344 123456","Bracknell","2","104","05","November","2008"]},{"values":["Northern England and Ireland","Newcastle and Middlesborough","Sunderland","1933262","Sunday","02/11/2008 15:36:09","7","Dijonaise Chicken Steam Cuisine","4.29","5","21.45","2.83","ANTHONY MURPHY","N","2,145","Cash","0.00","48","Branch048@Acuma.co.uk","01915 234567","01915 123456","Sunderland","2","111","02","November","2008"]},"t":"query"}

Crosstab:

[{"name":"994f9ec0-5ccb-1030-8416-d132a8f71a3a","displayName":"Data Warehouse"}]
{"filters":{},"filterLabels":{},"rowCount":1,"columnCount":12,"rowLabels":["2010"],"columnLabels":["January","February","March","April","May","June","July","August","September","October","November","December"],"aggregationLabels":["Revenue"],"conditionalFormat":{},"values":{"[0,8]":["140548"],",10":["134899"],"[0,7]":["139758"],",11":["138651"],"[0,5]":["132704"],"[0,6]":["139609"],"0,":["1675321"],",":["1675321"],"[0,11]":["138651"],"[0,1]":["138275"],",3":["132966"],"[0,2]":["141675"],",2":["141675"],"[0,3]":["132966"],",1":["138275"],"[0,0]":["155377"],"[0,10]":["134899"],",0":["155377"],",7":["139758"],",6":["139609"],",5":["132704"],"[0,9]":["141859"],",4":["138998"],"[0,4]":["138998"],",9":["141859"],",8":["140548"]},"valueLabels":{"[0,8]":["140,548"],",10":["134,899"],"[0,7]":["139,758"],",11":["138,651"],"[0,5]":["132,704"],"[0,6]":["139,609"],"0,":["1,675,321"],",":["1,675,321"],"[0,11]":["138,651"],"[0,1]":["138,275"],",3":["132,966"],"[0,2]":["141,675"],",2":["141,675"],"[0,3]":["132,966"],",1":["138,275"],"[0,0]":["155,377"],"[0,10]":["134,899"],",0":["155,377"],",7":["139,758"],",6":["139,609"],",5":["132,704"],"[0,9]":["141,859"],",4":["138,998"],"[0,4]":["138,998"],",9":["141,859"],",8":["140,548"]}}

Run Query

This web service runs a Query, returning the results in a JSON format.

URL

/rest/runQuery/<SessionID>/<SearchEngine>/<Index>

Parameters

Returns

Returns the query execution in the following format:

{
hits: Integer,
 headers: [{
     name: String,
     type: String,format: String
  }],
 documents: [{
     values: [String]
    }]
}

Example Output

{"t":"query","j":{"hits":139492,"headers":[{"name":"Area Name","type":"string"},{"name":"Branch Address","type":"string"},{"name":"Branch Code","type":"string"},{"name":"Branch Email","type":"string"},{"name":"Branch Fax","type":"string"},{"name":"Branch Name","type":"string"},{"name":"Branch Postcode","type":"string"},{"name":"Branch Telephone","type":"string"},{"name":"Branch Town","type":"string"},{"name":"Cost Price","type":"number","format":"#0.000"},{"name":"Currency Sale Price","type":"number","format":"#0.000"},{"name":"Day of Week","type":"number","format":"#0"},{"name":"Employee Name","type":"string"},{"name":"Has Discounts","type":"string"},{"name":"Has Overrides","type":"string"},{"name":"Has Returns","type":"string"},{"name":"Is Return","type":"string"},{"name":"Loyalty Card","type":"string"},{"name":"Loyalty Points","type":"number","format":"#0"},{"name":"MOP","type":"string"},{"name":"Override Amount","type":"number","format":"#0.000"},{"name":"Product Description","type":"string"},{"name":"Profit","type":"number","format":"#0.000"},{"name":"Quantity","type":"number","format":"#0"},{"name":"Region Name","type":"string"},{"name":"Sale Price","type":"number","format":"#0.00"},{"name":"Sale Price 4","type":"number","format":"#0.00"},{"name":"Till","type":"number","format":"#0"},{"name":"Time","type":"date","format":"HH:mm:ss"},{"name":"TPK","type":"number","format":"#0"},{"name":"Transaction Date","type":"date","format":"dd/MM/yyyy"},{"name":"Transaction Date Time","type":"date","format":"dd/MM/yyyy HH:mm:ss"},{"name":"Transaction Hour","type":"date","format":"HH"},{"name":"Transaction ID","type":"string"},{"name":"Transaction Month","type":"date","format":"MMM"},{"name":"Transaction Month 2","type":"date","format":"MMMM"},{"name":"Transaction Price","type":"number","format":"#0.00"},{"name":"Transaction Week","type":"date","format":"w"},{"name":"Transaction Date","type":"date","format":"dd/MM/yyyy"},{"name":"Transaction Dateextra","type":"date","format":"(EEE) dd/MM"},{"name":"Transaction Date Month Description","type":"string"},{"name":"New Transaction Date","type":"date","format":"HH"}], 234567","Bristol","BS1 3EZ","01179 123456","Bristol","2.240","2.990","2 Wales","2.99","2.99","1","00:08:00","17","03/04/2009","03/04/2009 00:08:00","00","1527895","Apr","April","14.95","13","03/04/2009","(Fri) 03/04","April","00"]},{"values":["Birmingham and North Midlands","82 Birmingham Rd","26","Branch026@Acuma.co.uk","01827 234567","Tamworth","DE11 1AZ","01827 123456","Tamworth","1.580","2.290","4","ANN WINTERS","0","0","0","0","N","458","Store Card","0.000","Barbecue Chicken 30g","0.710","2","Midlands and East","2.29","2.29","6","18:55:00","36","04/06/2011","04/06/2011 18:55:00","18","1528766","Jun","June","4.58","21","04/06/2011","(Sat) 04/06","June","18"]}],"t":"query"}}

Load Report

This web service allows an application or web page to initialise a CXAIR report by using the currently authenticated session. When the current session is invalid, launching the report will redirect the client to the standard login page, before forwarding them on to the target report.

URL

/jsp/index.jsp?loadReport=<GUID>&search=<Search String>

Parameters

Passed in as part of the URL.

Returns

Specific report or Query.

Example Output

[{"name":"994f9ec0-5ccb-1030-8416-d132a8f71a3a","displayName":"Data Warehouse"}]
{"filters":{},"filterLabels":{},"rowCount":1,"columnCount":12,"rowLabels":["2010"],"columnLabels":["January","February","March","April","May","June","July","August","September","October","November","December"],"aggregationLabels":["Revenue"],"conditionalFormat":{},"values":{"[0,8]":["140548"],",10":["134899"],"[0,7]":["139758"],",11":["138651"],"[0,5]":["132704"],"[0,6]":["139609"],"0,":["1675321"],",":["1675321"],"[0,11]":["138651"],"[0,1]":["138275"],",3":["132966"],"[0,2]":["141675"],",2":["141675"],"[0,3]":["132966"],",1":["138275"],"[0,0]":["155377"],"[0,10]":["134899"],",0":["155377"],",7":["139758"],",6":["139609"],",5":["132704"],"[0,9]":["141859"],",4":["138998"],"[0,4]":["138998"],",9":["141859"],",8":["140548"]},"valueLabels":{"[0,8]":["140,548"],",10":["134,899"],"[0,7]":["139,758"],",11":["138,651"],"[0,5]":["132,704"],"[0,6]":["139,609"],"0,":["1,675,321"],",":["1,675,321"],"[0,11]":["138,651"],"[0,1]":["138,275"],",3":["132,966"],"[0,2]":["141,675"],",2":["141,675"],"[0,3]":["132,966"],",1":["138,275"],"[0,0]":["155,377"],"[0,10]":["134,899"],",0":["155,377"],",7":["139,758"],",6":["139,609"],",5":["132,704"],"[0,9]":["141,859"],",4":["138,998"],"[0,4]":["138,998"],",9":["141,859"],",8":["140,548"]}}

Produce JSON from Report

URL

/servlet/secure/JSONServlet?guid=<Report GUID>&from=<From Page>&to=<To Page>

Parameters

Passed in as part of the URL.

Returns

Returns a Crosstab or Query report in JavaScript Object Notation (JSON).

Example Output

{"grandtotals":[46099.14999999886],"suffixes":["",null,null],"data":{"rows":[{"row":{"columns":74000000001,"rownumber":0}}]},"aggregationlabels":["![total]"],"rowsize":1,"rowlabels":["Birmingham"],"columnlabels":["2011","2012","2013","2014","2015"],"aggregationdisplayfields":"Line_Price","queryname":"BirminghamYearlySalesJS","rowtotals":14999999886,"version":"2019.1.058","dataformats":["#,0.00"],"filter":"*:*","prefixes":["£",null,null],"columntotals":74000000001,"columnsize":5,"modified":"Fri Feb 01 09:59:45 GMT 2019","aggregations":1}

Error Codes