Understanding XML Output for Info*Engine Groups
Info*Engine maintains all generated groups as serializable Java objects. These objects can be easily manipulated by custom Java applications, JSP pages, and tasks. Then, when there is a request to display a group, Info*Engine generates an XML document containing the group.
By default, the Info*Engine generated XML document contains the following parts:
• The document declaration at the beginning of the document.
• The wc:COLLECTION element, which is the document root for all Info*Engine generated XML documents.
• The root group element, which is named through the CLASS parameter on webjects that produce output groups. For example, if the CLASS parameter is set to “Employees,” then the root group element start tag includes <Employees>. In addition to the element name, the group element start tag always includes the NAME attribute. The value of the NAME attribute comes from the group name specified on the GROUP_OUT parameter of the webject that created the group.
• The wc:INSTANCE elements, which identify Info*Engine objects (rows) within a group. Each Info*Engine object contains attributes that are coded as sub-elements of a wc:INSTANCE element.
These parts are described in detail in the following sections. For examples of Info*Engine XML output, see the example XML tasks documented in
Group Webjects.
In addition, Info*Engine can also generate XML output that includes the metadata that is part of the group, element, or attribute data.
Document Declaration
XML documents must begin with an XML declaration that specifies the version of XML being used and the character encoding for this XML document. The current version of XML defined by the W3C, and used by Windchill, is 1.0. In addition, Info*Engine supports UTF8 for the character encoding. All XML generated by Info*Engine therefore begins with the following XML declaration:
<?xml version="1.0" encoding="UTF-8" ?>
An XML “namespace” is a collection of names, identified by a URI reference [RFC2396], which are used in XML documents as element types and attribute names. A namespace allows an XML author to uniquely specify a vocabulary to prevent naming collisions. Info*Engine defines the namespace http://www.ptc.com/infoengine/1.0, and associates the namespace prefix wc: to all Info*Engine defined elements and attributes.
<wc:COLLECTION xmlns:wc="http://www.ptc.com/infoengine/1.0">
The document entity, also known as the document root, serves as the root of the entity tree and a starting-point for an XML processor. Info*Engine defines the wc:COLLECTION element as the document root for all Info*Engine generated XML documents.
Info*Engine Groups
The serializable objects used for manipulating Info*Engine groups stores the values of the webject CLASS and GROUP_OUT parameters that were specified when the group was created. The value of the CLASS parameter is used to define the element name for the root element of the group data, and the value of the GROUP_OUT parameter is used as the NAME attribute for this element. For example, if a CLASS parameter is set to “DemoGrp” and the GROUP_OUT parameter is set to “salesGrp,” then Info*Engine generates the following XML document elements:
<?xml version="1.0" encoding="UTF-8" ?>
<wc:COLLECTION xmlns:wc="http://www.ptc.com/infoengine/1.0">
<DemoGrp NAME="salesGrp" TYPE="Object" STATUS="0">
</DemoGrp>
</wc:COLLECTION>
If the webject CLASS parameter is undefined or omitted, then Info*Engine uses “Unknown-Class-Name” as the element name. Though it is not technically an error to omit the CLASS parameter, the task writer should always include the CLASS parameter. Omitting the CLASS parameter makes the XML document vague. For example the following XML elements define two groups of information: “employees” and an unnamed group. In the example, it is more difficult to understand what data the unnamed group represents:
<wc:COLLECTION xmlns:wc="http://www.ptc.com/infoengine/1.0">
<Employees NAME="group1" TYPE="Object" STATUS="0"/>
</Employees>
<Unknown-Class-Name NAME="group2" TYPE="Object" STATUS="0"/>
</Unknown-Class-Name>
</wc:COLLECTION>
The group element contains two other attributes: TYPE and STATUS. The TYPE attribute indicates the group type. For data groups, this value is always Object. The STATUS attribute indicates the completion status for the generation of this group. A status of zero (0) indicates that no errors occurred. A non-zero value indicates that data is incomplete due to some error. Although the status values for groups no longer need to be checked, the STATUS attribute remains for backward compatibility. Info*Engine currently throws an exception whenever a webject cannot generate the requested group.
Info*Engine Objects
An Info*Engine group can contain one or more objects. In the XML document, each object is identified by the <wc:INSTANCE> start tag and </wc:INSTANCE> end tag. Objects can contain zero or more attributes, where each attribute can contain data. Each Info*Engine attribute corresponds to a XML sub-element that appears within the wc:INSTANCE element.
For example, assume that the following XML document represents a single Info*Engine group delimited by the <EMP> and </EMP> tags, which contains a single object. The object is delimited by the <wc:INSTANCE> and </wc:INSTANCE> tags:
<wc:COLLECTION xmlns:wc="http://www.ptc.com/infoengine/1.0">
<EMP NAME="empGrp" TYPE="Object" STATUS="0">
<wc:INSTANCE>
<EMPNO>7934</EMPNO>
<ENAME>MILLER</ENAME>
<JOB>CLERK</JOB>
<MGR>7782</MGR>
<HIREDATE>1982-01-23 00:00:00.0</HIREDATE>
<SAL>1300</SAL>
<COMM/>
<DEPTNO>10</DEPTNO>
</wc:INSTANCE>
</EMP>
</wc:COLLECTION">
In the example, you can see the sub-element tags for the Info*Engine attributes and can determine that the object has the following attributes:
EMPNO
ENAME
JOB
MGR
HIREDATE
SAL
COMM
DEPTNO
Metadata in XML Output
Metadata is information about normal application data that is contained in a group, element, or attribute. For example, metadata can provide additional qualifying information such as data type information. It could also provide information about relationships between the elements in a group or between the attributes in an element.
Software that interfaces with Windchill can generate metadata. For example, Windchill attribute type information is stored as metadata. This metadata is automatically passed along with the Info*Engine groups that are created. In addition, you can set metadata using the Set-Metadata webject.
By default, metadata is not included when XML output is generated through the Display-XML webject. To include metadata in your XML output, you can use the FULL mode on this webject.
In the XML output that includes metadata, metadata is nested between <wc:Meta> start tags and </wc:Meta> end tags.