Example Spec

XML Actions Specification - illustrative

 

Please note: this page is illustrative and is not maintained and therefore does not represent a full specification. For the current specification, refer to the user interface for editing action descriptors.

For further documentation, or to check exact syntax in the current version of Omniscope, use an installed Server+ version and, from the Main Toolbar, choose Settings > Server> Edit Enterprise Action Descriptor. The Omniscope dialog for configuring the action has full and accurate documentation fro that version.  More info 

 


 

Below is an illustration of the Enterprise Actions XML sytax structure as used to automate actions in Visokio Omniscope. Most elements apply to both products; where this is not the case they are documented. Instead of using an XML schema (XSD), the elements are described in a more freeform style in the "STRUCTURE" section below, which is more readable at source level than XSD. See the "EXAMPLES" section for some brief examples of use.

All path values allow local file paths (C:\MyFile.txt), FTP paths (ftp://user:pass@host/folder/file.csv') and HTTP URLs (http://mysite.com/file.iok'). You can use FTP paths as targets, so you can, for example, use SchedulerResourceAction to download or upload a file. Most attributes are optional and this is usually clear (e.g. email bcc field).

Structure

Types of "Action" elements:

  <!-- Opens an IOK/FFC file and does things with it -->
<schedulerFileAction
source="[path to file to open, e.g. C:\MyFile.IOK]">
<subActions>
[1 or more "File Sub Action" elements]
</subActions>
</schedulerFileAction>

<!-- Executes a native OS command -->
<schedulerExecAction
command="[OS command]"
waitUntilTerminated="[true/false]"
ignoreError="[true/false - relevant only if waitUntilTerminated is true]" />

<!-- Copies or moves a file or folder of files -->
<schedulerResourceAction
source="[path to source file to process, e.g. C:\MyFile.IOK]"
destination="[target path]"
eraseFirst="[true/false - do you want to silently erase the destination
(recursively) before beginning the copy/move operation?]"
move="[true/false - are we moving or copying?]"
replace="[true/false - do you want to silently replace destination files
(folders will be merged)?]"
ignoreError="[true/false]" />

<!-- Deletes a file or folder of files -->
<schedulerDeleteAction
path="[path to file to delete, e.g. C:\MyTemporaryFile.CSV]"
allowRecursive="[true/false]"
ignoreError="[true/false]" />

<!-- Sends an email -->
<schedulerSendEmailAction
mailServerHost="[text]"
mailServerPort="[number]"
username="[text]"
password="[text]"
from="[emails separated by commas]"
to="[emails separated by commas]"
cc="[emails separated by commas]"
bcc="[emails separated by commas]"
subject="[text]"
messageText="[text]"
attachment="[path to file to attach]" />

<!-- Creates a timestamp string (second accuracy, formatted like "2005-10-19_16-35-42")
and does things with that string -->
<schedulerCreateTimestampAction>
<actions>
[1 or more "Timestamp Action" elements]
</actions>
</schedulerCreateTimestampAction>

<!-- Executes a sequence of actions, and catches errors, aborting the chain,
executing an optional failure action, then returning to enclosing action successfully. -->
<schedulerChainAction title="Text">
<actions>
[1 or more "Action" elements]
</actions>
<failureAction><!-- optional -->
[one "Action" elements]
</failureAction>
</schedulerChainAction>

Types of "Dataset Source" elements:

  <!-- Describes an external data source file such as a CSV file. Normally 
you would only need to specify the location attribute. -->
<datasetfile
locale="[optional locale code]"
autoRecogniseDates="[true/false]"
autoRecogniseNumbers="[true/false]"
separatorChar="[e.g. comma character for CSV files]"
skipFirstRowsCount="[number of rows to skip before field names row is expected]"
xslLocation="[only specified if an XML file needing an XSL translation; path to XSL file]"
location="[path to external file, e.g. C:\MySource.CSV]" />

<!-- Describes a JDBC database external data source -->
<jdbc
tableName="[name of table to retrieve from; optional and mostly irrelevant
for JDBC; only used in database wizard]"
humanName="[arbitrary name to summarise this query]"
userName="[username, if authenticated]"
password="[password, if authenticated]"
sqlCount="[optional sql query to count rows ahead of query, only used
for progress display in UI app]"
sqlRetrieve="[sql query to retrieve data, such as SELECT * FROM MyTable]"
driverClass="[fully-qualified java classname of JDBC driver]"
jdbcUrl="[full JDBC url; syntax is specific to the JDBC driver you are using]"
jarFile="[jar file containing JDBC driver; list multiple files separated by semicolons]">
<mappings><!-- Optional field mappings. If present, only columns present will be
imported, optionally renamed. If mappings element is missing, all are imported. -->
<field source="[original field name]" dest="[renamed field name, optional]" />
</mappings>
</jdbc>

<!-- Describes a Microsoft Sql Server 2000 database external data source -->
<sqlserver2k
tableName="[see jdbc]"
humanName="[see jdbc]"
userName="[see jdbc]"
password="[see jdbc]"
sqlCount="[see jdbc]"
sqlRetrieve="[see jdbc]"
hostName="[hostname of database server]"
hostPort="[TCP/IP port number of database server, default 1433]">
</sqlserver2k>

<!-- Describes an ODBC database external data source -->
<odbc
tableName="[see jdbc]"
humanName="[see jdbc]"
userName="[see jdbc]"
password="[see jdbc]"
sqlCount="[see jdbc]"
sqlRetrieve="[see jdbc]"
odbcName="[Name of ODBC data source]">
</odbc>

<!-- Describes an Oracle database external data source -->
<oracle
tableName="[see jdbc]"
humanName="[see jdbc]"
userName="[see jdbc]"
password="[see jdbc]"
sqlCount="[see jdbc]"
sqlRetrieve="[see jdbc]"
hostName="[see sqlserver2k]"
hostPort="[TCP/IP port number of database server, default 1521]"
sid="[oracle database SID]">
</oracle>

Types of "File Sub Action" elements

(These all apply to the .IOK/.FFC opened by the enclosing "schedulerFileAction" element)

 
<!-- Refreshes from the linked source -->
<schedulerFileActionRefreshFromSource />

<!-- Re-links to a new external data source, then refreshes, which can be
used to replace with entirely new data.
It's recommended that the new source be of a compatible/similar field structure. -->
<schedulerFileActionUpdateWithFileDataSource>
<newSource>
[1 "Dataset Source" element]
</newSource>
</schedulerFileActionUpdateWithFileDataSource>

<!-- Removes the link to an external source -->
<schedulerFileActionUnlinkFromSource />

<!-- Updates the cover page. Only applicable to Omniscope. -->
<schedulerFileActionUpdateCoverPage
replaceBodyText="[text; if set, the cover page text is replaced with this]"
addTimeStamp="[true/false; if true, a timestamp is appended to the cover page text]" />

<!-- Applies security settings to the file. Only applicable to Omniscope. -->
<schedulerFileActionSecureFile
lockData="[true/false - if true, file cannot be edited, saved or copied out of,
by others]">
<restrictToDomains><!-- optional; lists domain suffixes that the file must be opened
directly from -->
<schedulerFileActionDomainEntry
domainName="[domain suffix to restrict to, e.g. visokio.com]" />
</restrictToDomains>
</schedulerFileActionSecureFile>

<!-- Sets an expiry to be a period of time from time of execution.
Only applicable to Omniscope. -->
<schedulerFileActionSetExpiry
amount="[number]" unit="[minutes|hours|days|weeks|months|years]"
allowWithWarning="[true/false - if true file can still be opened beyond expiry]"
message="[text to show on opening expired file]" />

<!-- Saves as an IOK file to a specific location. Only applicable to Omniscope. -->
<schedulerFileActionSaveIok location="[path to save to]" />

<!-- Saves as an FFC file to a specific location. Only applicable to FeatureFinder. -->
<schedulerFileActionSaveFfc location="[path to save to]" />

<!-- Creates and saves a SWF file for the opened FFC file.
Only applicable to FeatureFinder. -->
<schedulerFileActionSaveFfSwf location="[path to save to]" />

Types of "Timestamp Action" elements

(These all do things with a timestamp string created by the enclosing "schedulerCreateTimestampAction" action)

 
<!-- Copies a file, creating a new file whose name comprises the timestamp with a
prefix and suffix. -->
<schedulerCopyTsRes
sourceFile="[path]"
destinationFolder="[path]"
filenamePrefix="[text]"
filenameSuffix="[text]"
ignoreError="[true/false]" />

<!-- Emails a file, using the timestamp in the name of the attachment -->
<schedulerEmailTsRes
sourceFile="[path to file to attach]"
filenamePrefix="[text]"
filenameSuffix="[text]"
mailServerHost="[text]"
mailServerPort="[number]"
username="[text]"
password="[text]"
from="[emails separated by commas]"
to="[emails separated by commas]"
cc="[emails separated by commas]"
bcc="[emails separated by commas]"
subject="[text]"
messageText="[text]" />

<!-- Copies and filters a web page (or in fact any text file), changing
specified keywords into timestamp text -->
<schedulerFilterWebPage
sourceWebPage="[path to source file with embedded keywords]"
destinationWebPage="[path to destination file]">
<filters>
<schedulerFilterWebPageFilter
searchText="[search keyword]"
replaceOption="[Full filename of last timestamped file|Full filename
of last timestamped file, without extension|Date and time as
web-filename-safe text|Date and time as readable text]" />
</filters>
</schedulerFilterWebPage>

<!-- Only valid following a schedulerCopyTsRes element timestamp action. Saves a
TXT file containing the filename of the last timestamped file. -->
<schedulerPlainTextLink
destination="[path to TXT file to create]" />

<!-- Only valid following a schedulerCopyTsRes element timestamp action.
Creates an Omniscope link file (ILF) in the same folder as the last uploaded timestamp file,
required if you are hosting links to IOK files which use domain locking.
Only applicable to Omniscope.
-->
<schedulerOmniscopeLinkFile
filename="[path to link file to create]" />

Examples

To refresh an IOK file from source and copy to a network share:

  <schedulerFileAction source="C:\MyFile.IOK">
<subActions>

<schedulerFileActionRefreshFromSource />

<schedulerFileActionSaveIok location="Z:\public\LatestFile.IOK" />

</subActions>
</schedulerFileAction>

To open a "master" or "template" IOK file, update with a new client-specific subset dataset from a database, and copy to an FTP site:

  <schedulerFileAction source="C:\MasterReport.iok">
<subActions>

<schedulerFileActionUpdateWithFileDataSource>
<newSource>
<oracle tableName="sales" humanName="Sales" userName="dbuser" password="apples"
sqlCount="SELECT COUNT(*) FROM sales" sqlRetrieve="SELECT * FROM sales"
hostName="officeserver" hostPort="1521" sid="LIVE">
</oracle>
</newSource>
</schedulerFileActionUpdateWithFileDataSource>

<schedulerFileActionSaveIok location="ftp://steve:oranges@ftp.bluechip.com/reports/Report3.iok" />

</subActions>
</schedulerFileAction>