AE XML schema

[Michael A. Lowry]

Notice: An updated version of this document is available here: AE XML schema 

 

I’m putting together a compendium of useful information related to the AE XML schema. Here is what I have so far.

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_UNIX, EVNT_WINDOWS, EVNT_MVS, etc.
Time event	EVNT_TIME	EVNT_TIME
Output filter	FILTER_OUTPUT	FILTER
File transfer	JOBF	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.

Examples

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 FolderStructelement 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 theFolderStructelement 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 FolderStructelement:
   /uc-export/FolderStruct//*[@link='0']/@name
   (The link attribute appears only forobjects, and not forfolders.)
2. Identify all object references under theFolderStructelement 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 types in boldface in the table above.)

Object usage

Automation Engine objects can also beused inother objects. E.g., a workflow will usually contain several jobs, so under the JOBP element that defines the workflow, there will bereferences tothe 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 isrenamed,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 not complete. I will update it as I learn more about the XML schema, and as I get more experience with real-world AE batches.

[Michael A. Lowry]

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')]

[Michael A. Lowry]

Curly-brace-style VARA object 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,'}')]

Also, {VARA,KEY,COLUMN}-style VARA object references can appear in CDATA sections (see the previous comment).

Is there a way to generate a list of all of the fields of all object types where it is possible to use variables?
Update: A mostly complete list can be found in the documentation: Predefined Variables in Objects – Attributes for Predefined Variables

[Pete Wirfs]

I doubt such a list exists.  I've built my own (SQLServer) query with a multitude of unions to search all of the different places a variable could be referenced.  It started with some sample SQL that Phillipp posted years ago and I add to it as I found more places that need searching.  I've attached my latest version.

Attachment(s)

Grep.txt   4 KB 1 version

[Michael A. Lowry]

petwir: I found a list here: Predefined Variables in Objects – Attributes for Predefined Variables

The list is not comprehensive. For example, curly-brace VARA references can be used in task pre- and post-conditions. Still, the list is mostly complete, and certainly better than nothing. I will update the comment above when I have identified the relevant Xpaths.

[Pete Wirfs]

Good find.  Thanks for that.  

Right off the bat I see references to several attributes that we have never used, so are missing from my Grep.txt solution.

One possible omission; We use variables in our path and file name settings for RA-FTP instructions which are stored in JPPCV.  I don't know that the published list includes this.

[Michael A. Lowry]

I asked Automic Support for a complete list of places where {} expressions can be used. They agreed that the documentation should be updated, and opened PRB00217439 for this.

[Michael A. Lowry]

I moved all of the content above to a new document, AE XML schema. I will make future updates only to the document, so bookmark it. Also, let me know if you are interested in contributing.