Omniscope Server Editions can create and consume XML Actions files that permit programmatic guidance of Scheduler Actions, either chronological or event-driven, starting from model XML Action Descriptors. These XML files are used to automate the steps involved in refreshing, manipulating and distributing/publishing Omniscope files..
Although you can author XML Actions Descriptors manually, at least initially the easiest way to discover the best XML Actions syntax is to use the Server Edition user interface to configure tasks, then export the XML Actions files resulting and inspect the syntax/tagging of the XML files created. This ensures that each action is well-formed, and you can benefit from the hints given in the dialogs.
The Scheduler uses Enterprise Action Descriptor XML files to define task lists for automation. You configure these tasks using the Enterprise Edition user interface, or manually coded XML copied from and based upon XML Actions files previously created using the Scheduler Task List user interface.
A sample documented specification [1] is posted, but this is not always kept up-to-date. Current syntax of XML Actions files for your version can always best be observed by exporting an XML Actions file configured from your current version of Omniscope Server+. Examples of actions which can be automated include:
From the Main Toolbar, go to
(2.6) Settings > Server > Edit Enterprise Action Descriptor
(2.8+) Settings > Server > Edit XML Action
A file dialog will appear. Choose where you will want to save the new file:
The Create new Action dialog will appear. Choose the type of action you want:
Configure using the dialog that appears; then click OK to save the file in the location you chose.
For more help configuring actions, see Using the Scheduler [2]
From the Main Toolbar, go to:
(2.8+) Settings > Server > Edit XML Action
The file dialog above will appear. Choose the existing file you want to edit. The action configuration dialog will appear. Make your changes and click OK. The existing file will be overwritten.
(see XML Actions Specification [1] for an in-depth guide to the XML structure with examples)
Once you have created your XML Actions file(s), open command prompt and type cd to this location (C:\Program Files\Visokio Omnisope), execute the following system command (all on one line):
"C:\path\to\Omniscope\OmniscopeEnterprise.exe" -executeAction "C:\Path\To\My action file.xml"
For example in 2.6+ on 64-bit Windows with a system-wide installation:
"C:\Program Files (x86)\Visokio Omniscope\OmniscopeEnterprise.exe" -executeAction "C:\Path\To\My action file.xml"
For example in 2.6+ with a per-user installation:
"C:\Users\[username]\AppData\Local\Visokio Omniscope app\OmniscopeEnterprise.exe" -executeAction "C:\Path\To\My action file.xml"
Using this method, each action is executed in a separate Omniscope instance which is started before and closed after executing the action. This has a startup and shutdown overhead of 10 seconds on a moderately powered server. Alternatively you can use the watch folder [3] function to avoid this overhead.
Other options for OmniscopeEnterprise.exe:
...\OmniscopeEnterprise.exe -streamAction
(expects the XML on the process input stream, e.g. piped from another process)
...\OmniscopeEnterprise.exe -scheduler
(starts the Scheduler)
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 [4].
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 [4]
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).
<!-- 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>
<!-- 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>
(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]" />
(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]" />
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>
Links:
[1] http://kb.visokio.com/node/385
[2] http://kb.visokio.com/node/139
[3] http://kb.visokio.com/kb/watch-folder
[4] http://kb.visokio.com/kb/xml-actions