NAME
mxtask - Systems Insight Manager task XML file format
SYNOPSIS
mxtask
DESCRIPTION
The mxtask command supports reading and writing task information in
the eXtensible Markup Language (XML) format. You may use this
capability to create new scheduled tasks in the Systems Insight
Manager environment. Each task XML file may contain definition blocks
for one or more tasks.
The task specific XML format may be generated by the following "list"
type mxtask command option (-lf). This option will list the specified
task data in the task specific XML format (as described in this man
page), to stdout. The output could be redirected to an external file
as shown in the 2nd example. The output file could then be used as
input for the (-cf) command to create a similar task.
mxtask -lf taskname
mxtask -lf taskname > outfilename
The task specific XML format is utilized by the following "create"
type mxtask command option. This option will create a new task based
off the task specifc XML contents (as described in this man page) of
the specified file.
mxtask -cf filename
Document Type Definition
The Document Type Definition (DTD) file defines the constraints for an
XML file. These constraints include the valid element tags,
attributes, and the cardinality of elements in an XML file. The Task
DTD file is named tasklist.dtd and is included in the following
paragraph. Note that due to man page formatting, the following text
may not look the same as the contents of the actual DTD file.
<?xml version="1.0" encoding="UTF-8" ?>
<!-- The task-list is the root element defined for the task
XML DTD and will contain at least one or more task elements,
with each element block containing all required data for
creating a new scheduled task.
-->
<!ELEMENT task-list ( task+ )>
<!-- The task element consists of the following required data
elements: toolname, queryname, scheduleinfo, toolparams.
Note that for some Tasks, 'scheduleinfo' and/or 'toolparams'
may not contains any content, however, the element must
still exist (although empty). Doing this so users will
always be able to see all available elements for the Task
XML format. If required, This DTD design could be changed
so that the existance of the 'scheduleinfo' and 'toolparams'
elements within the XML are optional (implied).
-->
<!ELEMENT task (toolname,queryname,scheduleinfo,toolparams)>
<!-- The task element itself has the following attributes:
-name attribute specifies the task name and is required.
-type attribute specifies the task type and is required.
-owner attribute specifies the task owner and is optional.
-guid attribute specifies the task GUID and is optional.
-->
<!ATTLIST task name CDATA #REQUIRED
owner CDATA #IMPLIED
guid NMTOKEN #IMPLIED >
<!-- As said above, the task element requires an attribute
called 'type' that only allows the following valid values.
(add, remove, manual, schedule)
-->
<!ATTLIST task type (add | remove | manual | schedule) #REQUIRED >
<!-- The toolname element specifies the tool name associated with
specified task and is required.
-->
<!ELEMENT toolname (#PCDATA)>
<!-- The queryname element specifies the query name associated with
specified task and is required.
-->
<!ELEMENT queryname (#PCDATA)>
<!-- The scheduleinfo element specifies the schedule information
associated with the specified task and is required.
-->
<!ELEMENT scheduleinfo (#PCDATA)>
<!-- 4 possible attributes may accompany the scheduleinfo element.
Attribute Req/Opt Valid Values
========= ======= ============
1. interval (optional: required if task type = schedule) minutes,hours,days,weeks,months,daily,runonce,ranonce
2. periodic (optional: depends on interval type) some numeric value
3. time (optional: depends on interval type) HH:MM (24hr clock)
4. day (optional: depends on interval type) interval=weeks: sunday,monday,etc
interval=months: numeric value= 1 thru 31
5. date (optional: depends on interval type) date=mm/dd/yy
-->
<!-- The interval attribute is used to specify the schedule interval type.
Only 7 string values are allowed as defined below.
The 'interval' attribute is required when Task type is 'schedule'.
-->
<!ATTLIST scheduleinfo interval (minutes | hours | days | weeks | months | daily | runonce | ranonce) #IMPLIED >
<!-- The 'periodic' attribute is used to specify the schedule interval value
which is a string value representing some numeric value.
The 'periodic' attribute is NOT required when 'interval' type is
'daily', 'runonce' or 'ranonce'.
-->
<!ATTLIST scheduleinfo periodic CDATA #IMPLIED >
<!-- The 'time' attribute is used to specify a schedule time indicating
when the Task is to run. The string format for time is in 24hr
format - HH:MM
The 'time' attribute is NOT required when 'interval' type is
'minutes', 'hours', 'runonce' or 'ranonce'.
-->
<!ATTLIST scheduleinfo time CDATA #IMPLIED >
<!-- The 'day' attribute is used to specify the day a scheduled task
is set to run. If the 'interval' attribute is 'weeks', then
this attribute must be in the form of 'sunday', 'monday', etc.
If the 'interval' attribute is 'months', then this attribute
must be in the form of '1' to '31'.
The 'day' attribute is NOT required when 'interval' type is
'minutes', 'hours', 'days', 'daily', 'runonce' or 'ranonce'.
-->
<!ATTLIST scheduleinfo day CDATA #IMPLIED >
<!-- The 'date' attribute is used to specify the date a scheduled task
is set to run. If the 'interval' attribute is 'runonce' or 'ranonce',
then this attribute must be in the form of 'mm/dd/yy'.
The 'date' attribute is NOT required when 'interval' type is
'minutes', 'hours', 'weeks', 'months', 'days' or 'daily'.
The 'date' attribute IS required when the 'interval' type
is 'runonce' or 'ranonce'.
The 'periodic', 'day' and 'time' attributes are NOT required
when the 'interval' type is 'runonce' or 'ranonce',
-->
<!ATTLIST scheduleinfo date CDATA #IMPLIED >
<!-- The toolparams element specifies the Tool parameters that may be
required for the associated Tool. Some Tools require parameters,
some don't. This element is required to exist within the XML,
although at times, the element may not contain any content.
NOTE: The content stored within this element may be XML data. If
so, then the special XML chars 'less-than' and 'greater-than'
can NOT exist in their literal format - they must be expressed
as their 'character reference' or 'predefined entity reference'.
For example, a 'less-than' char must be expressed as either
"<" or "<". A 'greater-than' char as: ">" or ">".
-->
<!ELEMENT toolparams (#PCDATA) >
Elements
As defined in the DTD, the Task XML file must adhere to the following
general format:
<?xml version="1.0" encoding="UTF-8"?>
<task-list>
<task name="task name" type="schedule" owner="machine/user">
<toolname>tool name</toolname>
<queryname>query name</queryname>
<scheduleinfo interval="x" periodic="x" time="x" day="x" date="x"/>
<toolparams />
</task>
</task-list>
As defined in the DTD, the Task XML file must contain the following
elements.
The first line of a Task XML file should always be the following:
<?xml version="1.0" encoding="UTF-8" ?>
The "task-list" element must appear once in a user XML file and wraps
the list of Task information. The "task-list" element must contain one
or more "task" elements. Note if the "task-list" element contains no
"task" elements, the associated mxtask command will fail.
The "task" element must appear one or more times in a user XML file
and has the following format.
<task name="taskname" type="tasktype" owner="taskowner">
The "task" element has two required attributes - "name" and "type".
The "name" attribute is mandatory and specifies the task name. The
name specified must be unique and must not already exist in the
Systems Insight Manager repository.
The "type" attribute is mandatory and specifies the type of task.
Valid values for the task type are "add", "remove", "manual" and
"schedule" and are described below.
The "task" element has one optional attribute - "owner".
The "owner" attribute specifies the owner of the task. If no owner is
specified, the current logged in user will be assigned as the task
owner.
add -task runs when systems or events meet the list criteria.
remove -task runs when systems or events no longer meet the list
criteria.
manual -task runs only when manually invoked.
schedule -task runs based off a defined schedule. When this task type
is specified, then the scheduleinfo element must contain the required
attributes that actually define the schedule.
The "task" element must contain several additional elements. Each of
these elements must appear once in each "task" element. Each element
must appear in the order they are defined in the DTD.
<toolname>tool name here</toolname>
<queryname>query name here</toolname>
<scheduleinfo interval="x" periodic="x" time="x" day="x" date="x"/>
The "toolname" element specifies an existing tool (by name) to
associate with the task and an assigned value is required. The tool
name specified must already exist in the Systems Insight Manager
repository.
<toolname>tool name here</toolname>
The "queryname" element specifies an existing query (by name) to
associate with the task and an assigned value is required. The query
name specified must already exist in the Systems Insight Manager
repository.
<queryname>query name here</toolname>
The "sheduleinfo" element defines schedule information (when the task
will run) for the task. Attributes for this element are only required
if the task "type" attribute is defined as "schedule" (task types
"add", "remove" and "manual" do not require schedule information).
The "scheduleinfo" element can contain five various attributes that
define the schedule. They are: "interval", "periodic", "time", "day"
and "date".
The "scheduleinfo" element has the following format by which a
complete run schedule can be defined for any task.
<scheduleinfo interval="x" periodic="x" time="x" day="x" date="x"/>
The "interval" attribute specifies the type of interval for the new
task. Valid values for the 'interval' attribute are as follows.
minutes - task will run every X minutes.
hours - task will run every X hours.
days - task will run every X days at specified time.
weeks - task will run every X weeks on specified day/time.
months - task will run every X months on specified day/time.
daily - task will run every day at specified time.
runonce - task will run once on specified date/time.
ranonce - task had already run on specified date/time.
The "perodic" attribute is a numeric value and specifies how often the
task will run. Valid values for the the "periodic attribute include
any numeric value greater than zero.
The "day" attribute specifies a day value and is required only when
the "interval" attribute is either "weeks" or "months". Valid "day"
attribute values are dependant on the "interval" attribute value
specified. If "interval" attribute value defined as "weeks", then the
valid "day" attribute values are "sunday", "monday", etc. If the
"interval" attribute value is defined as "months", then the valid
"day" attribute value is a numeric value in the range of 1-31.
The "date" attribute specifies a date value and is required only when
the "interval" attribute is "runonce" or "ranonce". Valid "date"
attribute values are in the form of mm/dd/yy.
The "time" attribute specifies a time value and is required for all
"interval" attribute types, excluding "minutes" and "hours". This
attribute defines the time at which the task will run and must be
specified in 24hr format - time="HH:MM"
The "toolparams" element specifies the parameters for specified
Systems Insight Manager tool. Not all Systems Insight Manager tools
require parameters. Contents for this element are only required if the
tool specified in the "toolname" element does indeed require
additional parameters to run properly.
<toolparams />
Note1: If the content for the 'toolparams' element is stored as XML
data, then the tool parameter data must not contain the literal less-
than (<) or greater-than (>) characters. Instead, all less-than
characters must be replaced by the corresponding entity reference
"<", and all greater-than characters must be represented by the
corresponding entity reference ">".
Note2: The output generated from the "mxtask -lf taskname" command
will display any possible XML type tool parameter data in the proper
format (as described above) whereby any less-than and greater-than
characters are replaced by their corresponding entity references. The
output from the '-lf' command can therefore be used as input for
creating new tasks.
Below is a sample content for the "toolparams" element for the actual
Systems Insight Manager tool called "Hardware Status Polling".
<toolparams><?xml version="1.0"?> <XeObject
className="com.hp.mx.core.tools.polling.HardwareStatusPollingTaskModel"
classVersion="2.0"> <Property name="pollingTimeout">
<Simple>4</Simple> </Property> <Property
name="pollingRetries"> <Simple>1</Simple>
</Property> <Property name="pollingProtocols"> <Vector
size="0"> </Vector> </Property> </XeObject>
</toolparams>
Commenting
Comments may be included in XML files. The comment must begin with
the characters "<!--" and end with the characters "-->". Comments may
span multiple lines within the beginning and ending character tags.
Examples
This section contains some examples of "task" specific XML format.
This example defines a new task named task1 of type "add" (task runs
when systems or events meet the list criteria) that is associated with
an existing Systems Insight Manager query called "query1" and an
existing Systems Insight Manager tool called "tool1". Since the task
type is not of type "schedule", the scheduleinfo element is empty.
Also, we're assuming the specified tool (tool1) does not require any
additional parameters, thus the toolparams element is empty.
<?xml version="1.0" encoding="UTF-8"?>
<task-list>
<task name="task1" type="add">
<toolname>tool1</toolname>
<queryname>query1</queryname>
<scheduleinfo />
<toolparams />
</task>
</task-list>
This example defines a new task named task1 of type "add" (task runs
when systems or events meet the list criteria) that is associated with
an existing Systems Insight Manager query called "query1" and an
existing Systems Insight Manager tool called "tool1". Since the task
type is not of type "schedule", the scheduleinfo element is empty.
Also, we're assuming the specified tool (tool1) does not require any
additional parameters, thus the toolparams element is empty. A task
owner is also being specified.
<?xml version="1.0" encoding="UTF-8"?>
<task-list>
<task name="task1" type="add" owner="machineName/userName">
<toolname>tool1</toolname>
<queryname>query1</queryname>
<scheduleinfo />
<toolparams />
</task>
</task-list>
This example defines a new task named task1 of type "remove" (task
runs when systems or events no longer meet the list criteria) that is
associated with an existing Systems Insight Manager query called
"query1" and an existing Systems Insight Manager tool called "tool1".
Since the task type is not of type "schedule", the scheduleinfo
element is empty. Also, we're assuming the specified tool (tool1)
does not require any additional parameters, thus the toolparams
element is empty.
<?xml version="1.0" encoding="UTF-8"?>
<task-list>
<task name="task1" type="remove">
<toolname>tool1</toolname>
<queryname>query1</queryname>
<scheduleinfo />
<toolparams />
</task>
</task-list>
This example defines a new task named task1 of type "manual" (task
runs only when manually invoked) that is associated with an existing
Systems Insight Manager query called "query1" and an existing Systems
Insight Manager tool called "tool1". Since the task type is not of
type "schedule", the scheduleinfo element is empty. Also, we're
assuming the specified tool (tool1) does not require any additional
parameters, thus the toolparams element is empty.
<?xml version="1.0" encoding="UTF-8"?>
<task-list>
<task name="task1" type="manual">
<toolname>tool1</toolname>
<queryname>query1</queryname>
<scheduleinfo />
<toolparams />
</task>
</task-list>
This example defines a new task named task1 of type "schedule" (task
runs based off a periodic/day/time schedule) that is associated with
an existing Systems Insight Manager query called "query1" and an
existing Systems Insight Manager tool called "tool1". Since the task
type is of type "schedule", the scheduleinfo element must contain the
schedule information. In this case, the task schedule specifies the
task will run every 30 minutes. We're also specifying the specified
tool (tool1) does not require any additional parameters, thus the
toolparams element is empty.
<?xml version="1.0" encoding="UTF-8"?>
<task-list>
<task name="task1" type="schedule">
<toolname>tool1</toolname>
<queryname>query1</queryname>
<scheduleinfo interval="minutes" periodic="30" />
<toolparams />
</task>
</task-list>
This example defines a new task named task1 of type "schedule" (task
runs based off a periodic/day/time schedule) that is associated with
an existing Systems Insight Manager query called "query1" and an
existing Systems Insight Manager tool called "tool1". Since the task
type is of type "schedule", the scheduleinfo element must contain the
schedule information. In this case, the task schedule specifies the
task will run every 7 days at 1:00 AM. We're also specifying the
specified tool (tool1) does not require any additional parameters,
thus the toolparams element is empty.
<?xml version="1.0" encoding="UTF-8"?>
<task-list>
<task name="task1" type="schedule">
<toolname>tool1</toolname>
<queryname>query1</queryname>
<scheduleinfo interval="days" periodic="7" time="1:00"/>
<toolparams />
</task>
</task-list>
This example defines a new task named task1 of type "schedule" (task
runs based off a periodic/day/time schedule) that is associated with
an existing Systems Insight Manager query called "query1" and an
existing Systems Insight Manager tool called "tool1". Since the task
type is of type "schedule", the scheduleinfo element must contain the
schedule information. In this case, the task schedule specifies the
task will run every 2 weeks on Friday at 6:00 PM. We're also
specifying the specified tool (tool1) does not require any additional
parameters, thus the toolparams element is empty.
<?xml version="1.0" encoding="UTF-8"?>
<task-list>
<task name="task1" type="schedule">
<toolname>tool1</toolname>
<queryname>query1</queryname>
<scheduleinfo interval="weeks" periodic="2" day="friday" time="18:00"/>
<toolparams />
</task>
</task-list>
This example defines a new task named task1 of type "schedule" (task
runs based off a periodic/day/time schedule) that is associated with
an existing Systems Insight Manager query called "query1" and an
existing Systems Insight Manager tool called "tool1". Since the task
type is of type "schedule", the scheduleinfo element must contain the
schedule information. In this case, the task schedule specifies the
task will run every month on the 15th at 2:00 AM. We're also
specifying the specified tool (tool1) does not require any additional
parameters, thus the toolparams element is empty.
<?xml version="1.0" encoding="UTF-8"?>
<task-list>
<task name="task1" type="schedule">
<toolname>tool1</toolname>
<queryname>query1</queryname>
<scheduleinfo interval="months" periodic="1" day="15" time="2:00"/>
<toolparams />
</task>
</task-list>
This example defines a new task named task1 of type "schedule" (task
runs based off a periodic/day/time schedule) that is associated with
an existing Systems Insight Manager query called "query1" and an
existing Systems Insight Manager tool called "tool1". Since the task
type is of type "schedule", the scheduleinfo element must contain the
schedule information. In this case, the task schedule specifies the
task will run every day at 5:00 AM. We're also specifying the
specified tool (tool1) does not require any additional parameters,
thus the toolparams element is empty.
<?xml version="1.0" encoding="UTF-8"?>
<task-list>
<task name="task1" type="schedule">
<toolname>tool1</toolname>
<queryname>query1</queryname>
<scheduleinfo interval="daily" time="5:00"/>
<toolparams />
</task>
</task-list>
This example defines a new task named task1 of type "schedule" (task
runs based off a periodic/day/time schedule) that is associated with
an existing Systems Insight Manager query called "query1" and an
existing Systems Insight Manager tool called "tool1". Since the task
type is of type "schedule", the scheduleinfo element must contain the
schedule information. In this case, the task schedule specifies the
task will run once at 5:00 AM on January 1, 2004. We're also
specifying the specified tool (tool1) does not require any additional
parameters, thus the toolparams element is empty.
<?xml version="1.0" encoding="UTF-8"?>
<task-list>
<task name="task1" type="schedule">
<toolname>tool1</toolname>
<queryname>query1</queryname>
<scheduleinfo interval="runonce" time="5:00" date="01/01/04"/>
<toolparams />
</task>
</task-list>
This example defines a new task named "Hardware Status Polling 2" of
type "schedule" (task runs based off a periodic/day/time schedule)
that is associated with an existing Systems Insight Manager query
called "All Servers" and an existing Systems Insight Manager tool
called "Hardware Status Polling". Since the task type is of type
"schedule", the scheduleinfo element must contain the schedule
information. In this case, the task schedule specifies the task will
run every week on Sunday at 1:00 AM. We must also specify the tool
parameters for the specified tool. Note that the parameters for the
"Hardware Status Polling" tool may be obtained via the mxtask -lf
"Hardware Status Polling" command.
<?xml version="1.0" encoding="UTF-8"?>
<task-list>
<task name="Hardware Status Polling 2" type="schedule">
<toolname>Hardware Status Polling</toolname>
<queryname>All Servers</queryname>
<scheduleinfo interval="weeks" periodic="1" day="sunday" time="1:00"/>
<toolparams><?xml version="1.0"?>
<XeObject
className="com.hp.mx.core.tools.polling.HardwareStatusPollingTaskModel"
classVersion="2.0">
<Property name="pollingTimeout">
<Simple>4</Simple>
</Property>
<Property name="pollingRetries">
<Simple>1</Simple>
</Property>
<Property name="pollingProtocols">
<Vector size="0">
</Vector>
</Property>
</XeObject>
</toolparams>
</task>
</task-list>
Note that the above parameters for the "Hardware Status Polling" tool
may be viewed on the screen via the following mxtask command option:
mxtask -lf "Task Name"
Use redirection to save the screen output to an external Task XML
file. The file could be modifed and then used to create a similar
task via the -cf command option.
mxtask -lf "Task Name" > "Task Name.xml"
LIMITATIONS
This command may only be run on the CMS.
AUTHOR
mxtask was developed by the Hewlett-Packard Company.
SEE ALSO for HP-UX
mxtask(1M)
SEE ALSO for Linux
mxtask(8)