Guide to General Import and Export

GIAE functionality overview

This functionality allows export of data from agility to any text based file format (xml, comma separated value, html etc.). The export and import procedures can be run at defined intervals from the background process or manually. Additionally the export function can be defined as a monitor expression that will execute based upon a condition. It is also possible to publish the Import definition as web service and the export definition as a web service client. This functionality allows distribution of Agility data to other systems

Before you start

General Import and Export operates with web services at a very low level. In other words to exchange data you must understand SOAP protocol structure using properly setup http headers.

It is recommended that a ‘RequestTool’ is available for design, configuration and testing.

A Request tool is an application which will help process the test procedure. This tool helps to generate http request, and grabs the request result.

A Request Tool has been included in Agility and is available under the default Agility Admin menu:

System Configuration -> Import Export -> Request Tool

General Export

Simple export example

You can think of and export definition as a sequential program written inside an xml file.

This Simple example showing a CSV export work order data where the work order start date is within the last 6 months will help to understand how it works.

<?xml version="1.0" encoding="utf-8"?> <export> <contents>

<const> "JobCode" + Separator() + "Desc" + Separator() + "StartDate"+ Separator() + "Due" + NewLine() </const>

<foreach table="woJob" datacontext="database" classname="DataBO.ProcessMngt.JobBO"> <dbfilter> woJob.StartDate >= DATEADD(NOW(), 'MONTH', -6) order by woJob.StartDate </dbfilter>

CsvEncode( JobCode, FullDescription, StartDate, DueDate ) + NewLine() </foreach>

</contents> </export>

The ‘Const’ and ‘data’ sections hold string expressions which will be output to file after processing. The difference in those sections is only logical. The Const section is evaluated without context and is simply output ‘as is’, and the data is evaluated in the context of the foreach element. The key to understanding export is to understanding the foreach element.

This element is responsible for:

• the context and format of data to export • filter and retrieve data to export • loop through retrieved data results and: o evaluate defined variables o evaluate string expressions from all data sections defined inside foreach element, o execute nested foreach elements

The Foreach element can operate on different datacontext instances, all the available options will be explained in next chapter. In above example datacontext is set to database. The database context requires additional parameters: table, classname, and dbfilter.

As you would expect in this context the system will create a query based on the definition in the dbfilter element. The Foreach element will then loop through results of the query contained in the dbfilter element and for each row the system will execute the string expression inside data element and will output to file. The String expression contains a few new functions which will help to produce well formatted xml or csv files.

This is a sample of the output from the above example

The Export Definition

Configuration section

The configuration section contains some parameters relating to formatting and behavior of the output

<export> <configuration> <separator>;</separator> <textquote>"</textquote> <newline>\n</newline> <encoding>UTF8</encoding>

   		<header></header>

</configuration> <contents> ...

The above configuration sample show the default values of the configuration elements. The element names are self-explanatory with the exception of the header element which is explained below.

<export> <configuration> <newline>\n</newline> <encoding>UTF8</encoding> <header> Content-Type: text/xml; SOAPAction: http://www.fastnetasp.com/GeneralImport; </header> </configuration>

This header element is used to build proper request format and response headers when Export is used to communicate over http protocol.