Automic Workload Automation

AE XML schema 

06-01-2018 09:13 AM

This is a community-authored description of the AE XML schema with a focus on making changes to AE objects using off-the-shelf XML tools. This document supersedes the earlier discussion AE XML schema. If you are interested in contributing, contact one of the authors.

 

AE object types

There are several different types of object in the Automation Engine. Object types are identified in the XML schema by a short object type identifier, usually just four characters, but sometimes more, and sometimes including a sub-type. In a few cases, the same type of object is identified differently in different parts of the XML schema.

 

Description

Object type

under uc-export

Object type

under FolderStruct

Notification

CALL

CALL

Documentation

DOCU

DOCU

Console event

EVNT_CONS

EVNT_MVS

DB event

EVNT_DB

EVNT

File event

EVNT_FILE

EVNT_agenttype where agenttype is the type of the agent
( EVNT_UNIX, EVNT_WINDOWS, EVNT_MVS, etc.)

Time event

EVNT_TIME

EVNT_TIME

Output filter

FILTER_OUTPUT

FILTER

File transfer

JOBF

JOBF_agenttype where agenttype is the type of the source agent
(JOBF_UNIX, JOBF_WINDOWS, JOBF_MVS, etc.)

Job include

JOBI

JOBI

Workflow

JOBP

JOBP

RA job

JOBS_CIT

JOBS_CIT

z/OS job

JOBS_MVS

JOBS_MVS

SQL job

JOBS_SQL

JOBS_SQL

UNIX job

JOBS_UNIX

JOBS_UNIX

Windows job

JOBS_WINDOWS

JOBS_WINDOWS

Schedule

JSCH

JSCH

Prompt set

PRPT

PRPT

AE Script

SCRI

SCRI

Sync object

SYNC

SYNC

Variable table

VARA

VARA

 

Object type & name

A particular AE object can be identified by its type and name, using the XPath
/uc-export/object_type/[@name='object_name']
where object_type is one of the AE object types in the table above and object_name is the object name.

 

  1. Identify all executable objects:
    /uc-export/*[local-name()=('JSCH','JOBP','JOBP_IF','JOBP_FOREACH','JOBF','JOBS_UNIX','JOBS_WINDOWS','JOBS_MVS','JOBS_SQL','JOBS_CIT','EVNT_CONS','EVNT_DB','EVNT_FILE','SCRI','CALL')]/@name
  2. Identify the UNIX job UC0.UAT.TEST#1_3.JOBS_UNIX:
    /uc-export/JOBS_UNIX[@name='UC0.UAT.TEST#1_3.JOBS_UNIX']/@name
  3. Or to list the names of all UNIX jobs:
    /uc-export/JOBS_UNIX/@name
  4. Identify all JOBS, JOBF, and EVNT objects whose names start with the string 'UC0.':
    /uc-export/EVNT_CONS[starts-with(@name, 'UC0.')]/@name
    /uc-export/EVNT_DB[starts-with(@name, 'UC0.')]/@name
    /uc-export/EVNT_FILE[starts-with(@name, 'UC0.')]/@name
    /uc-export/EVNT_TIME[starts-with(@name, 'UC0.')]/@name
    /uc-export/JOBS_CIT[starts-with(@name, 'UC0.')]/@name
    /uc-export/JOBS_MVS[starts-with(@name, 'UC0.')]/@name
    /uc-export/JOBS_SQL[starts-with(@name, 'UC0.')]/@name
    /uc-export/JOBS_UNIX[starts-with(@name, 'UC0.')]/@name
    /uc-export/JOBS_WINDOWS[starts-with(@name, 'UC0.')]/@name
    /uc-export/JOBF[starts-with(@name, 'UC0.')]/@name

 

Object references

Objects can be referred to in other places in the XML schema. There are two categories of object reference: object path and object usage.

 

Object path

The FolderStruct element and its children define a hierarchical folder structure, and the locations of objects within it. References to objects that appear under this element define the locations of those objects in the AE system. Specifically, the path to the object reference under the FolderStruct element specifies the absolute path to that object in the AE system (actually, the AEclient).

When an object is renamed, any references to this object in the folder structure must be updated too. E.g.,

  1. Identify all object references under the FolderStruct element:
    /uc-export/FolderStruct//*[@link='0']/@name
    (The link attribute appears only for objects, and not for folders.)
  2. Identify all object references under the FolderStruct element where the referenced object name starts with the string 'UC0.':
    /uc-export/FolderStruct//*[@link='0' and starts-with(@name, 'UC0.')]/@name
  3. Identify folder structure references to JOBS, JOBF, and EVNT objects by name:
    /uc-export/FolderStruct//JOBS_CIT/@name
    /uc-export/FolderStruct//JOBS_MVS/@name
    /uc-export/FolderStruct//JOBF_SQL/@name
    /uc-export/FolderStruct//JOBS_UNIX/@name
    /uc-export/FolderStruct//JOBS_WINDOWS/@name
    /uc-export/FolderStruct//JOBF_MVS/@name
    /uc-export/FolderStruct//JOBF_UNIX/@name
    /uc-export/FolderStruct//JOBF_WINDOWS/@name
    /uc-export/FolderStruct//EVNT/@name

Note that the object types of references appearing under the FolderStruct element sometimes differ from the types used to identify objects themselves directly under the uc-export element. (See the object types in boldface in the table above.)

 

Object usage

Automation Engine objects can also be used in other objects. E.g., a workflow will usually contain several jobs, so under the JOBP element that defines the workflow, there will be references to the corresponding JOBS objects. Object references identify objects by name. Different types of objects can be referred to in different places in the XML schema. For instance, there are some places where any executable AE object may be referenced, and other places where only a SYNC object or only a PRPT object may be specified.

When an object is renamed, the references to that object by name must also be updated. This can be done  using a list of XPaths.

/uc-export/JSCH/JSCH/JschStruct/task/@Object
/uc-export/JSCH/JSCH/JschStruct/task/dynvalues/dyntree/node/@name
/uc-export/JSCH/JSCH/JschStruct/task/dynvalues/dyntree/node/@id

/uc-export/JSCH/JSCH/JschStruct/task/runtime/@MrtExecuteObj
/uc-export/JSCH/JSCH/JschStruct/task/result/@RExecute
/uc-export/JOBP/ATTR_JSCH/RExecute
/uc-export//JobpStruct/task/dynvalues/dyntree/node/@name
/uc-export//JobpStruct/task/dynvalues/dyntree/node/@id
/uc-export//JobpStruct/task/checkpoint/@TcpExecute
/uc-export//JobpStruct/task/when/@WhenExecute

/uc-export//JobpStruct/task/@Alias
/uc-export//JobpStruct/task/@Object

/uc-export//JobpStruct/task/runtime/@MrtExecuteObj
/uc-export/JOBP/ATTR_JOBP/RExecute
/uc-export/JOBP/JOBP_FE/JobpStruct/task/ForEach/@source_name
/uc-export//RUNTIME/MrcExecute
/uc-export//RUNTIME/MrtExecuteObj
/uc-export//PROMPTSET/@name /uc-export//PRPTBOX/@name
/uc-export//PROMPTSET/PRPTBOX/*[starts-with(local-name(), 'VARIABLE')]/@promptsetname
/uc-export//PROMPTSET/PRPTBOX/@promptset

/uc-export//DYNVALUES/dyntree/node/@name
/uc-export//DYNVALUES/dyntree/node/@id

/uc-export//SYNCREF/Syncs/row/@Name
/uc-export//OUTPUTSCAN/filterobjects/row/@execute
/uc-export//OUTPUTSCAN/filterobjects/row/@filter
/uc-export//OSCRI/text

/uc-export//MSCRI/text
/uc-export//PSCRI/text
/uc-export//XUIEDITOR/text
/uc-export//DATAEDITOR/text
/uc-export//DOC/text

This list is probably not complete.

 

CDATA sections

Some parts of the UC4 XML schema include bits of text embedded in CDATA sections.

  • Prompt set PRPT objects (Embedded XML)
    • XUIEDITOR element (Prompt set dialog box definition)
    • DATAEDITOR element (Prompt set default values)
  • Scripting tabs of executable objects (Plain text)
    • PSCRI element (Pre-process tab, or Process tab of JOBF objects)
    • MSCRI element (Process tab)
    • OSCRI element (Post-process tab)
  • Documentation tabs of all objects (Embedded XML & plain text)
    • DOC element whose type is xml (Structured XML documentation)
    • DOC element whose type is text (Plain text documentation)

 

Prompt set data source references

Some prompt set elements (radio buttons, check boxes, combo boxes) have a data source, a VARA object that defines the values displayed for that element, e.g., the pick list for a combo box or the list of radio buttons displayed.

  1. Identify embedded XML of prompt set containing the name of a particular VARA:
    /uc-export/PRPT/PROMPTSETXUI/XUIEDITOR[contains(text(),'UC0.PRPT_DATASOURCE.VARA')
  2. Inside the embedded prompt set XML, identify data source references to the VARA:
    /dialog/readpanel/*[local-name()=('integer','text','combo','dynradiogroup','dyncheckgroup','time','date','timestamp')]/properties/entry[@name='reference' and contains(text(),'UC0.PRPT_DATASOURCE.VARA')]

Prompt set default values

Prompt set elements can have default values, and these values can contain strings that one might want to change, e.g., {VARA,COLUMN,KEY} references to VARA objects whose names have been changed.

  1. Identify embedded XML of prompt set defaults that mention the name of a particular VARA:
    /uc-export/PRPT/PROMPTSETDATA/DATAEDITOR[contains(text(),'{UC0.PRPT_DEFAULTS.VARA,')]
  2. Inside the embedded prompt set XML, identify data source references to the VARA:
    /PRPTS/PRPTBOX/*[starts-with(local-name(), 'VARIABLE') and ends-with(local-name(), 's.00') and starts-with(., '{UC0.PRPT_DEFAULTS.VARA') and ends-with(., '}')]

Scripting tabs of executable objects

Any executable object can contain AE scripting content in one or more scripting tab.

  1. Identify scripting tabs mentioning a particular JOBI object:
    /uc-export/*[local-name()=('JSCH','JOBP','JOBP_IF','JOBP_FOREACH','JOBF','JOBS_UNIX','JOBS_WINDOWS','JOBS_MVS','JOBS_SQL','JOBS_CIT','EVNT_CONS','EVNT_DB','EVNT_FILE','SCRI','CALL')]/*[local-name()=('PRE_SCRIPT','SCRIPT','POST_SCRIPT')]/*[local-name()=('PSCRI','MSCRI','OSCRI') and contains(text(),'UC0.DEV.MAIN.JOBI')]

Documentation tabs

There are two types of documentation tab:XML and plain text.

  1. Identify XML documentation tabs containing a the string ‘Assignment Group’:
    /uc-export//*[starts-with(local-name(), 'DOCU_') and @type='xml']/DOC[contains(text(),'Assignment Group')]
  2. Identify text documentation tabs containing a the string ‘Assignment Group’:
    /uc-export//*[starts-with(local-name(), 'DOCU_') and @type='text']/DOC[contains(text(),'Assignment Group')]

 

RA job attributes

RA job attributes are specific to each RA solution. They can appear in JOBS_CIT objects, but also in JOBP tasks.

  1. Identify a specific RA job attribute with a specific value.
    /uc-export//CIT/citcont/cit/component[@xmlName='attribute_name' and @value='attribute_value']/@value
  2. Identify a specific RA job attribute with a specific value for a specific RA solution.
    /uc-export//CIT/citcont[@jobtype='ra_solution_name']/cit/component[@xmlName='attribute_name' and @value='attribute_value']/@value

 

Object variable values

Object variables can appear at the level of the object or workflow task. The capitalization of the dyntree element differs between these two cases.

  1. Identify a specific object variable value.
    /uc-export//*[fn:matches(fn:lower-case(local-name()),'dynvalues')]/dyntree/node/VALUE/Values/row[@Name='variable_name' and @Value='variable_value' and @Value='variable_value']/@Value
  2. Identify a specific object variable value in a specific object.
    /uc-export/*[@name='object_name']/*[fn:matches(fn:lower-case(local-name()),'dynvalues')]/dyntree/node/VALUE/Values/row[@Name='variable_name' and @Value='variable_value']/@Value

 

Prompt set variable values

Prompt set variables can appear at the level of the executable object or workflow task.

  1. Identify a specific prompt set variable value.
    /uc-export//*[fn:matches(fn:lower-case(local-name()),'dynvalues')]/node/PROMPTSET/PRPTBOX/*[@promptname='prpt_variable_name' and text()='prpt_variable_value']/text()
  2. Identify a specific prompt set variable value in a specific prompt set object.
    /uc-export//*[fn:matches(fn:lower-case(local-name()),'dynvalues')]/node[@name='prompt_set_name']/PROMPTSET/PRPTBOX/*[@promptname='prpt_variable_name' and text()='prpt_variable_value']/text()
  3. Identify a specific prompt set variable value in a specific prompt set, in a particular workflow.
    /uc-export/JOBP[@name='workflow_name']/*[fn:matches(fn:lower-case(local-name()),'dynvalues')]/node/PROMPTSET/PRPTBOX/*[@promptname='prpt_variable_name' and text()='prpt_variable_value']/text()

 

Static VARA object values

Static VARA objects can have up to 5 values for each key. Value 1 is specified by the attribute Value; Value 2 is specified by the attribute Value1; and so on.

  1. Identify a specific VARA value in Value 1.
    /uc-export/VARA/VARA/Variables/row[@Name='key_name' and Value='value']/@Value_number
  2. Identify a specific VARA value in Value 2.
    /uc-export/VARA/VARA/Variables/row[@Name='key_name' and Value1='value']/@Value1
  3. Identify a specific VARA value in Value 5, in a specific VARA object.
    /uc-export/VARA[@name='object_name']/VARA/Variables/row[@Name='key_name' and Value4='value']/@Value4

 

{VARA,KEY,COLUMN} references

In many attributes of UC4 objects, it is possible to enter either object/script variables of the form &VARIABLE#, or VARA object references of the form {VARA,KEY,COLUMN}. These variables are evaluated/resolved at activation/run time. When a VARA object is renamed, it may also be necessary to update any curly-brace-style references to the VARA object whose name has changed.

 

Below are Xpaths that can be used to identify elements containing a reference to the UC0.PARMS.VARA object.

 

Header tab

/uc-export/*/XHEADER/*[starts-with(.,'{UC0.PARMS.VARA,') and ends-with(.,'}')]

Object type-specific tab

E.g., ATTR_JOBS & ATTR_JOBF

/uc-export/*/*[starts-with(local-name(), 'ATTR_')]/*[starts-with(.,'{UC0.PARMS.VARA,') and ends-with(.,'}')]

File transfers

File transfers have several fields specific to the object type that can contain VARA object references.

/uc-export/JOBF/JOBF/*[starts-with(.,'{UC0.PARMS.VARA,') and ends-with(.,'}')]

Runtime tab

/uc-export/*/RUNTIME/MrcExecute[starts-with(.,'{UC0.PARMS.VARA,') and ends-with(.,'}')]
/uc-export/*/RUNTIME/MrtExecuteObj[starts-with(.,'{UC0.PARMS.VARA,') and ends-with(.,'}')]

Rollback tab

/uc-export/*/ROLLBACK/CBackupObj[starts-with(.,'{UC0.PARMS.VARA,') and ends-with(.,'}')]
/uc-export/*/ROLLBACK/CRollbackObj[starts-with(.,'{UC0.PARMS.VARA,') and ends-with(.,'}')]
/uc-export/*/ROLLBACK/FBackupPath[starts-with(.,'{UC0.PARMS.VARA,') and ends-with(.,'}')]

Output Scan tab

/uc-export/*/OUTPUTSCAN/HostFsc[starts-with(.,'{UC0.PARMS.VARA,') and ends-with(.,'}')]
/uc-export/*/OUTPUTSCAN/LoginFsc[starts-with(.,'{UC0.PARMS.VARA,') and ends-with(.,'}')]

Workflow task pre- or post-conditions

/uc-export/JOBP/JOBP/JobpStruct/task/preconditions/PreCon/conditions//params/param[@type='V' and starts-with(@value,'{UC0.PARMS.VARA,') and ends-with(@value,'}')]
/uc-export/JOBP/JOBP/JobpStruct/task/postconditions/PostCon/conditions//params/param[@type='V' and starts-with(@value,'{UC0.PARMS.VARA,') and ends-with(@value,'}')]

 

A mostly complete list of fields where it is possible to use variables can be found in the documentation: Predefined Variables in Objects – Attributes for Predefined Variables

 

Also, {VARA,KEY,COLUMN}-style VARA object references can appear in embedded CDATA sections in the XML document. (See CDATA sections, above.)

Statistics
1 Favorited
2 Views
0 Files
0 Shares
0 Downloads

Tags and Keywords

Related Entries and Links

No Related Resource entered.