Appboard/old/XMLWebServiceAdapter

Introduction

The AppBoard 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.

Using the XML Web Service Adapter

The following is an overview of how to use the XML Web Service Adapter to retrieve XML data from REST services and make it available in AppBoard.

REST URL and XML data validation

Prior to configuring the AppBoard Data Adapter, you should configure and validate the request URL being used to retrieve the XML data in your browser. Once the URL request is returning the data you require, you will need to write an XSLT stylesheet to transform the returned XML data into AppBoard XML data format.

Writing an XSLT Stylesheet

XSLT (Extensible Stylesheet Language Transformations) is a declarative, XML-based language used for the transformation of XML. The original XML is not changed; rather, a new set of XML is created based on the content of an existing one using the XSLT. The XML Bible contains a tutorial on XSLT authoring that can be used as a reference.

In this section, ${application.home} is [APPBOARD_HOME]/webapps/enportal/WEB-INF/

The incoming XSLT is transformed into the AppBoard internal XML structure as defined by the xml-adapter-data.dtd located in the ${application.home}/stylesheets/ directory. Hierarchical relationships within the XML can be captured by using associations in the AppBoard data model as described below.

There are several sample XSLT files that can also be used as a reference. The files are located in ${application.home}/stylesheets/sample/ directory:

Example transformation for a RSS XML source

${application.home}/stylesheets/sample/rss-1.0-to-adapter.xsl

Example transformation for a VPM Connex XML source

${application.home}/stylesheets/sample/fluke-to-adapter.xsl

Example transformation for an Atlas XML source

${application.home}/stylesheets/sample/atlas-to-adapter.xsl

Also available are several XML sample data files for each XSLT:

Sample RSS feed:

${application.home}/data/pkg/sample/nist-cve/cve.xml

Sample Atlas Global Attacks Summary:

${application.home}/data/pkg/sample/atlas/atlas.xml

Sample Fluke VPM Connex XML data:

${application.home}/data/pkg/sample/fluke/top-n.xml

${application.home}/data/pkg/sample/fluke/topSitesByEurt.xml

${application.home}/data/pkg/sample/fluke/trend.xml

${application.home}/data/pkg/sample/fluke/trendForApp.xml

${application.home}/data/pkg/sample/fluke/trendForAppSite.xml

Representing Hierarchical XML Relationships Using Associations

Hierarchical parent/child relationships are accomplished by defining an association on the parent entity and setting a parent id attribute on the child records. The association then uses a key value in the parent as the "fromKey" and the corresponding value set on each child record as the "toKey". It is usually convenient to define the association via the XSLT, but the association can also be defined in the builder.

Example data with a parent/child relationship between nodes and NICs:

${application.home}/data/pkg/sample/hierarchy/hierarchy.xml

Transform for that data:

${application.home}/stylesheets/sample/hierarchy-to-adapter.xsl

Configuring an AppBoard XML Data Source in AppBoard Builder

The Data Source Wizard within the AppBoard Builder is used to retrieve data from REST Web Services. The following steps outline the process of connecting to a Data Source using the AppBoard Builder:

1. Click "Data Sources" in the left tool palette.
2. Click on the “Add” button.
3. Enter the name of the Data Source in the “Name” field.
4. Select the “Web Services” category
5. Select the XML REST Adapter
6. In the url field enter the URL of the REST service with parameters.
7. In the styleSheetPath field enter the file path of the sytle sheet on the AppBoard server.
8. Select "next"
9. Enter the "primary keys" of the data source if it has not been defined within the XSLT.
10. Select "next"
11. Create associations between the XML REST data source and other data sources if the associations have not been defined within the XSLT.

Inspect the data in an AppBoard Data Collection

The data that has been retrieved by the new Data Source can be viewed as a Data Collection in the Data Collection Wizard.

1. Click "Data Collections" in the left tool palette.
2. Click on the "i" or “preview” button at the far right side of the row for your Data Collection.

Incorporating Dynamic Variables into a URL Query

AppBoard Data Source queries can incorporate system and custom variables into the URL string using portal SHIM variables. The values of these variables are dynamically inserted into the URL prior to making the request. For example, if you would like a query with a variable to incorporate the current date / time you can do so as follows:

http://192.10.0.23/Portal/Portal/Services/ConnexDataAccess.ashx?domain=VpmConnex&username=user&password=password&report=EurtTrend&startTime=January%2012,2011%2017:30&endTime=${shim:utility.cryptor.url.encode('${shim:now.format('MMMMMMMdd,yyyy HH:mm')}')}

Where ${shim:now.format('MMMMMMMdd,yyyy HH:mm')} will be substituted for the current data / time in the MMMMMMMdd,yyyy HH:mm format. The “now” shim expression is wrapped within the ${shim:utility.cryptor.url.encode('')} call to apply URL encoding to the result.

Inserting the users current “Role” into the query can be accomplished by inserting the ${shim:session.actor.role.name} expression into the URL string. For example, Customer='${shim:session.actor.role.name}'"