Appboard/2.4/builder/data sources/web service: Difference between revisions

imported>Jason.nicholls
imported>Jason.nicholls
Line 120: Line 120:
* An object containing a variety of "key":value fields, with the fields consisting of strings, numbers, boolean values, arrays, or objects (see [[/glossary_json|glossary.json]], [[/person_json|person.json]], and [[/widget_json|widget.json]]).
* An object containing a variety of "key":value fields, with the fields consisting of strings, numbers, boolean values, arrays, or objects (see [[/glossary_json|glossary.json]], [[/person_json|person.json]], and [[/widget_json|widget.json]]).


Some additional notes:


If the file is an array of objects (e.g. [[/data_json|data.json]]) or an object that contains an array of objects (e.g. [[/services_json|services.json]]), it is recommended that each object within that array have a consistent set of "keys".  Changing the number of keys or using different keys from one object to the next within the array may adversely affect the parsing of the data.
* root level key/value pairs may cause parsing issues.
 
* named objects within objects will be created a separate entity, it's important that each of these named objects have a consistent set of keys.
 
For example, do not do:
 
 
<nowiki>
{ "people" : [
{ "name" : "John Doe",
"height" : "5ft 11in",
"weight" : "150 lbs",
"age" : 22,
"Job" : "Police Officer" }
{ "name" : "Jane Doe",
"height" : "5ft 6in",
"age" : 19,
"Occupation" : "Student" }
]
}</nowiki>
 
 
Notice that "Jane Doe" does not have a "weight" key and has an "Occupation" key instead of "Job".  If certain information cannot be provided for a particular object but it can for another, then it is recommended that for the object without said information, include the key but give it an empty value.  Remember to keep the keys consistent.
 
 
i.e., do the following:
 
 
<nowiki>
{ "people" : [
{ "name" : "John Doe",
"height" : "5ft 11in",
"weight" : "150 lbs",
"age" : 22,
"Job" : "Police Officer" }
{ "name" : "Jane Doe",
"height" : "5ft 6in",
"weight" : "",
"age" : 19,
"Job" : "Student" }
]
}</nowiki>
 
 
Lastly, the following format has been known to cause parsing issues:
 
 
<nowiki>
{ "key1" : value, (string/number/boolean)
"key2" : value, (string/number/boolean)
...
"keyN" : value, (string/number/boolean)
"arrayOrObjectKey" : [ (or "arrayOrObjectKey" : {)
...
] (or })
...
}</nowiki>
 
 
Notice the "key" : value pairs (that are string, number, or boolean) preceding the array or object.  The parser is known to have issues with this style of formatting and it is therefore recommended that the "key" : value pairs are encapsulated within a named object.
 
 
i.e.:
 
 
<nowiki>
{ "namedObject" : {
"key1" : value, (string/number/boolean)
"key2" : value, (string/number/boolean)
...
"keyN" : value, (string/number/boolean)
"arrayOrObjectKey" : [ (or "arrayOrObjectKey" : {)
...
] (or })
...
}
}</nowiki>


==XML XSLT==
==XML XSLT==

Revision as of 09:27, 18 September 2013

There are several web service data adapters available to choose from in AppBoard: CSV WebService, JSON WebService, and XML XSLT. As each type of data adapter will require different information to connect to AppBoard, this page will assist you in understanding some of the specific options associated with web service data adapters.


CSV WebService

This is a web services adapter that uses CSV to communicate with an application server.

Connecting with CSV WebService

The Data Source Wizard begins with the "Connect" step. Here you must fill in the necessary information to connect AppBoard to your CSV WebService data source. These are the possible elements you will need to provide:


Name Description
url Base URL for the web service from which to fetch data. This can also be the complete URL, if you want to include any needed parameters here instead of as separate settings.
httpAuthUsername Username to use for HTTP Auth (Basic, Digest, etc.). Ignored if HTTP Auth is not needed.
httpAuthPassword Password to use for HTTP Auth (Basic, Digest, etc.). Ignored if HTTP Auth is not needed.
cacheTimeout Time limit before reloading results from the database.
httpHeaders Optional HTTP headers to set on request.
httpPostBody Optional POST body to send with request. If set, the request will be made via a POST; if not, the HTTP request will be a GET request.
headerLine Whether the data includes a header to define the columns/field names.
delimiter.data Whether the data includes a delimiter to define the columns/field names.
useQuoteChar Whether the data fields should be written within quotes.
proxyurl Optional URL for web proxy.
proxyuser Optional Proxy Username.
proxypass Optional Proxy Password.
proxyntlm Optional Proxy NT Domain.
proxydomain Optional Use NTLM Auth for Proxy.


JSON Web Service

This data source adapter is for web services that provide JavaScript Object Notation (JSON) formatted responses.

Connecting with JSON Web Service

The Data Source Wizard begins with the "Connect" step. Here you must fill in the necessary information to connect AppBoard to your JSON data source. These are the possible elements you will need to provide:

Name Description
url Base URL for the web service from which to fetch data. This can also be the complete URL, if you want to include any needed parameters here instead of as separate settings.
httpAuthUsername Username to use for HTTP Auth (Basic, Digest, etc.). Ignored if HTTP Auth is not needed.
httpAuthPassword Password to use for HTTP Auth (Basic, Digest, etc.). Ignored if HTTP Auth is not needed.
cacheTimeout Time limit before reloading results from the database.
httpHeaders Optional HTTP headers to set on request.
httpPostBody Optional POST body to send with request. If set, the request will be made via a POST, if not, the HTTP request will be a GET request.
proxyurl Optional URL for web proxy.
proxyuser Optional Proxy Username.
proxypass Optional Proxy Password.
proxyntlm Optional Proxy NT Domain.
proxydomain Optional Use NTLM Auth for Proxy.


Valid JSON Formats

JSON can be used to represent complex data structures using a combination of arrays, objects, and key/value pairs. While this flexibility is good in general, for AppBoard the data source adapter needs to understand and convert this into one or more entities with a set number of columns. The following formats deliver the best results:

  • An array of objects (see the example data.json)
  • An object that contains an array of objects (see services.json)
  • An object containing a variety of "key":value fields, with the fields consisting of strings, numbers, boolean values, arrays, or objects (see glossary.json, person.json, and widget.json).

Some additional notes:

  • root level key/value pairs may cause parsing issues.
  • named objects within objects will be created a separate entity, it's important that each of these named objects have a consistent set of keys.

XML XSLT

This adapter lets you get data from an XML web service and transform it into records that are in a format applicable to AppBoard.


Connecting with XML XSLT

The Data Source Wizard begins with the "Connect" step. Here you must fill in the necessary information to connect AppBoard with your XML XSLT data source. These are the possible elements you will need to provide:


Name Description
url This is the location of the information file used for your data source. Included in the distribution are some sample xml files which can be accessed by using the 'file://' url. For example, on windows it would look like 'file://localhost/${application.home}/data/pkg/sample/atlas/atlas.xml' and on UNIX it would look like: 'file://${application.home}/data/pkg/sample/atlas/atlas.xml'. Please see http://en.wikipedia.org/wiki/File_URI_scheme for more details on using file:// urls; although you will normally be using http:// to reference the RESTful WebService.
stylesheetPath The path from '${application.home}/stylesheets/' of the XSL stylesheet to be used to convert the data from the web service into the AppBoard internal XML representation.
httpAuthUsername Username to use for HTTP Auth (Basic, Digest, etc.). Ignored if HTTP Auth is not required.
httpAuthPassword Password to use for HTTP Auth (Basic, Digest, etc.). Ignored if HTTP Auth is not required.
cacheTimeout Time limit before re-loading results from the RESTful web service. Note: if a timeout is not specified, it will calculate the timeout based on the timeout specfied by the response header. If the request should be run on every request, then a value of '0' should be specified.
httpHeaders Optional HTTP headers to set on request.
httpPostBody Optional POST body to send with request. If set, the request will be made via a POST; if not, the HTTP request will be a GET request.
proxyurl Optional URL for web proxy.
proxyuser Optional Proxy Username.
proxypass Optional Proxy Password.
proxyntlm Optional Proxy NT Domain.
proxydomain Optional Use NTLM Auth for Proxy.
Retrieved from "http://ab.edge-technologies.com/docs/index.php?title=Appboard/2.4/builder/data_sources/web_service&oldid=4061"