Appboard/2.5/builder/data sources/web service

There are several web service data adapters available to choose from in AppBoard: CSV Web, JSON Web, and XML XSLT Web. 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 Web

This data source adapter is for web services that provide Comma Separated Value (CSV) formatted responses.

Connecting with CSV Web

The Data Source Wizard begins with the "Connect" step. Here you must fill in the necessary information to connect AppBoard to your CSV Web 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. Sample CSV files have been included with this distribution and are located within various folders under ${application.home}/data/. On a Windows server, these can be accessed using a URL like file:///${application.home}/data/path_to_CSV (on UNIX, the URL would start as file://). Please see http://en.wikipedia.org/wiki/File_URI_scheme for more details on using file:/// (or file://) URLs. Alternatively, the sample CSV files can be copied to a custom folder in the enportal directory and accessed via http://host:port/enportal/custom_folder/path_to_CSV. Example URL: file:///${application.home}/data/examples/training/timeline_sample_data.csv
HTTP Auth Username	Username to use for HTTP Auth (Basic, Digest, etc.). Ignored if HTTP Auth is not needed.
HTTP Auth Password	Password to use for HTTP Auth (Basic, Digest, etc.). Ignored if HTTP Auth is not needed.
HTTP Headers	Optional HTTP headers to set on request.
HTTP Post Body	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.
Cache Timeout	Time limit before reloading results from the database.
Data Delimiter	Whether the data includes a delimiter to define the columns/field names.
Contains Header Line	Defines whether the response contains a header line, which should be the first row. If no header is present the first row returned in discovery will be used to define the initial field names. Note: in order for query SHIMs to work then a header line is required.
Header Meta Delimiter	Whether the header includes a delimiter.
String Boundaries	Whether the data fields should be written within quotes.
Proxy URL	Optional URL for web proxy.
Use NTLM Authentication	Optional Use NTLM Auth for Proxy.
Proxy Domain	Optional Proxy NT Domain.
Proxy Username	Optional Proxy Username.
Proxy Password	Optional Proxy Password.

JSON Web

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

Connecting with JSON Web

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. The distribution contains sample JSON files located within ${application.home}/data/examples/json/. The following section in the documentation also includes links to copies of these sample JSON files which demonstrate valid formatting. Any JSON files placed on the AppBoard server can go either within ${application.home}/data/ or within a custom folder in the enportal directory. Just like with the CSV files, these can be accessed using URLs like file:///${application.home}/data/path_to_JSON or http://host:port/enportal/custom/path_to_JSON. Example URL: file:///${application.home}/data/examples/json/data.json
HTTP Auth Username	Username to use for HTTP Auth (Basic, Digest, etc.). Ignored if HTTP Auth is not needed.
HTTP Auth Password	Password to use for HTTP Auth (Basic, Digest, etc.). Ignored if HTTP Auth is not needed.
HTTP Headers	Optional HTTP headers to set on request.
HTTP Post Body	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.
Cache Timeout	Time limit before reloading results from the database.
Proxy URL	Optional URL for web proxy.
Use NTLM Authentication	Optional Use NTLM Auth for Proxy.
Proxy Domain	Optional Proxy NT Domain.
Proxy Username	Optional Proxy Username.
Proxy Password	Optional Proxy Password.

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 as a separate entity, so it's important that each of these named objects have a consistent set of keys.

XML XSLT Web

The XML Web Service Adapter supports data retrieval from HTTP REST services. XML data returned from the REST service is transformed to the AppBoard internal data structure using XSLT. Hierarchical relationships between XML data elements can be represented within AppBoard through associations within the AppBoard data model.

This adapter can also be used to access some SOAP web service calls where there is a single call and response.

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 file:/// (on Windows) or file:// (on UNIX) URL. For example, on Windows it would look like file:///${application.home}/data/examples/xml/atlas_global_attacks.xml and on UNIX it would look like file://${application.home}/data/examples/xml/atlas_global_attacks.xml. As with the CSV and JSON adapters, XML files can also be placed within a custom folder in the enportal directory and accessed via http://host:port/enportal/custom_folder/path_to_XML. Normally you will be using http:// to reference the RESTful Web service. Example URL: file:///${application.home}/data/examples/xml/atlas_global_attacks.xml Example Stylesheet: ${application.home}/stylesheets/sample/atlas-to-adapter.xsl
Style Sheet Path	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. Note that the stylesheet must be on the AppBoard server as importing stylesheets from foreign servers is not currently supported. AppBoard includes a number of samples in the ${application.home}/stylesheets/samples directory, such as for transforming RSS feeds.
HTTP Auth Username	Username to use for HTTP Auth (Basic, Digest, etc.). Ignored if HTTP Auth is not required.
HTTP Auth Password	Password to use for HTTP Auth (Basic, Digest, etc.). Ignored if HTTP Auth is not required.
HTTP Headers	Optional HTTP headers to set on request.
HTTP Post Body	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.
Cache Timeout	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.
Proxy URL	Optional URL for web proxy.
Use NTLM Authentication	Optional Use NTLM Auth for Proxy.
Proxy Domain	Optional Proxy NT Domain.
Proxy Username	Optional Proxy Username.
Proxy Password	Optional Proxy Password.

Additional Resources

• XSLT Tutorial
• Accessing SOAP web services