Adding Elements to Documents

This chapter provides an overview of element types and data types and discusses how to:

• Use the elements action toolbar.

• Manage primitive elements.

• Manage compound elements.

• Manage collection elements.

Understanding Element Types and Data Types

This section describes the element types and element data types that the PeopleSoft system supports as part of its document framework.

Note. The term and concept of elements described in this chapter refers to node elements.

Element Types

When you manage documents in the PeopleSoft system, you can add and manage root elements, child elements, and peer elements.

The first element that appears in a document is the root element. A document can have only one root element. When you create a new document, the system automatically creates a root element and uses the document name as the root element name.

Data Types

This section discusses the data types that PeopleSoft supports.

See Also

Defining Primitive Element Properties

Managing Compound Elements

Managing Collection Elements

Using the Elements Action Toolbar

This section discusses how to:

• Access and enable the action toolbar.

• Use the action toolbar buttons.

Accessing and Enabling the Action Toolbar

Use the action toolbar to select element types and data types to add to a document.

The elements action toolbar appears on the Document Builder - Documents page under the document tree. This example shows the action toolbar:

Hover over any button to display the element type that you can add to the system

Child Element Action Buttons

The first set of three buttons highlighted in the following example enable you to add child element types to a document:

The following table lists the child element buttons in the order they appear on the toolbar and the action you can perform with each:

Peer Element Action Buttons

The second set of three buttons highlighted in the following example enable you to add peer element types to a document:

The following table lists the peer element action buttons in the order they appear on the toolbar and the action you can perform with each:

Delete and Move Element Action Buttons

The following example highlights the action toolbar buttons you can use to delete and move elements in the document tree:

The following table describes the action buttons you can use to delete and move elements in the document tree:

Accessing and Enabling the Action Toolbar

To access the action toolbar, select PeopleTools, Documents, Document Builder and then select a document or create a new document.

The following example shows a document definition named Items. The action toolbar appears under the document tree section:

The action toolbar is not enabled until you click an element in the document tree. In the previous example, the action toolbar is not enabled since no element is selected. The following example shows the price element of the Item document selected and the action toolbar enabled:

When you click an element, the element types and data types that you can add are enabled on the toolbar. If an element or data type is not enabled on the toolbar, either you have not selected an element to which to add an element or you are not allowed to add the element type or data type to the document tree at that time.

When you select the root element on the document tree, the Dependencies section appears. Document dependencies are discussed elsewhere in this PeopleBook.

See Viewing Document Dependencies.

When you select any other element type on the document tree, the properties defined for the element appear on the right side of the page, as shown in the previous example. Defining element properties is discussed elsewhere in this chapter.

See Also

Defining Primitive Element Properties

Managing Compound Elements

Managing Collection Elements

Managing Primitive Elements

This section provides an overview of adding elements to documents and discusses how to:

• Add primitive elements.

• Define primitive element properties.

• Add enumerated values.

Understanding Adding Elements to Documents

You build out a document structure by adding elements to a document tree.

Use the action toolbar on the Document Builder - Documents page to add elements to documents. As described elsewhere in this chapter, the Action Toolbar features buttons to add primitive, compound, and collection elements, both child and peer elements, to documents.

Note. After you add an element to a document, you must define the element properties before you can save the document.

Adding Primitive Elements

To add primitive elements (child or peer) to documents:

1. Access the Document Builder - Documents page (PeopleTools, Documents, Document Builder).

2. On the document tree, click the element to which to add a primitive child or primitive peer element.

3. On the action toolbar, do one of the following:

   • Click the Add Primitive Child button to add a primitive child element.

   • Click the Add Primitive Peer button to add a primitive peer element.

The element appears on the document tree and you may define its properties.

See Defining Primitive Element Properties.

Defining Primitive Element Properties

When you add a primitive element data type to a document, the properties that you can define for the element appear on the right side of the Document Builder - Document page.

To access the page, select PeopleTools, Documents, Document Builder. The right side of the following example shows the primitive data type properties section:

The following table describes the properties that you can define for primitive data type elements. Except where noted, the properties in the table are applicable to all primitive data type supported by the system:

Adding Enumerated Values

You can define allowed values, or enumerated values, for some primitive data types.

An example of enumerated values is a list of acceptable state abbreviations that can be used in a primitive element called State that is a string.

In the Documents Builder, you can define enumerated values for the following primitive data types:

• Character.

• Date.

• DateTime.

• Integer.

• String.

• Time.

Use the Set Enumerated Values page (IB_ENUM_SEC) to set enumerated values. You access the page by using the Add Enumerated Values link that appears on the Document Builder - Documents page when you define properties for one of the primitive data types in the previous list.

The following example shows the Add Enumerated Values link that appears when you define a primitive element called State that is a string:

Click the Add Enumerated Value link to access the Set Enumerated Values page. The following example shows the page:

To set enumerated values, enter an acceptable value in the Value field and then a description for the value in the Description field. In the previous example, the Value column shows the acceptable abbreviations and values that the State element can contain for several of the United States. The Description field shows information about each of the values.

When enumerated values exist for a primitive data type, when you are working in the properties section a Show Enumerated Values link appears instead of a Set Enumerated Values link. The following example shows the properties section for the State element after enumerated values are defined. Note that a Show Enumerated Values link appears:

To set enumerated values:

1. Select PeopleTools, Documents, Documents Builder.

   The Documents Builder - Documents page appears.

2. In the document tree, select the element for which to add enumerated values.

   The properties for the element appear on the right side of the page.

3. Perform one of the following actions:

   1. Click the Add Enumerated Values link to add values.

      This link appears if no enumerated values are defined for the element.

   2. Click the Show Enumerated Values link to modify existing values.

      This link appears if enumerated values are already defined for the element.

4. Enter enumerated values and descriptions:

   1. In the Value field, enter an acceptable value for the element.

   2. In the Description field, enter a description for the value.

5. Click the plus button (+) to add additional rows of values and descriptions.

6. Click the OK button.

   The Documents Builder - Document page appears.

Managing Compound Elements

This section provides an overview of compound data types and discusses how to:

• Add compound elements.

• Define complex primitive data types.

• Define documents as compound element data types.

• Define PeopleSoft records as a compound element data types.

Understanding Defining Compound Data Types

A compound data type can be a complex primitive data type, another document, or a PeopleSoft record.

Adding Compound Elements

When you add a compound data type to the document tree, the Add Compound Child or Add Compound Peer page appears, depending on whether you are adding a child or peer element. The Add Compound Child page and the Add Compound Peer page are identical and have the same object name, IB_LOGICALCOMP_SEC.

The following example shows the Add Compound Child page:

To add compound elements (child or peer) to documents:

1. Access the Document Builder - Documents page (PeopleTools, Documents, Document Builder).

2. On the document tree, click the element to which to add a compound child or compound peer element.

3. On the action toolbar, do one of the following:

   • Click theAdd Compound Child button to add a compound child element.

   • Click the Add Compound Peer button to add a compound peer element.

     The Add Compound Child page or Add Compound Peer page appears.

4. In the Name field, enter a name for the compound element.

5. Select the type of compound element to create. The options are:

   • Complex Primitive

     When you select this option, the Document Builder - Documents page appears for you to define the element properties.

     See Defining Complex Primitive Data Types.

   • Document

     When you select this option, you search for and specify the document to use as the compound element.

     See Defining Documents as Compound Element Data Types.

   • Record

     When you select this option, you search for and specify the PeopleSoft record to use as the compound element.

     See Defining PeopleSoft Records as Compound Element Data Types.

Defining Complex Primitive Data Types

This section discusses how to:

• Define properties for complex primitive elements.

• Define attributes element properties.

• Add additional attribute elements to complex primitive data types.

Defining Properties for Complex Primitive Elements

After you create and name a complex primitive data type, two elements appear in the document tree on the Document Builder - Documents page. One element is for the complex primitive and the other is for the first of one or more element attributes.

The following example shows a newly created complex primitive element (and attribute) element appearing in the document tree:

The complex primitive element is denoted by a complex primitive icon to the left of the element name. In addition, it is highlighted. The attribute is denoted by the primitive icon to the left of the name.

In the example, the complex primitive element is highlighted, and the properties appear on the right side of the page. They are:

Defining Attributes Element Properties

Properties you define for an attribute element appear when you select an element in the document tree.

The following example shows the attribute element TransactionID selected in the tree:

When you select an attribute element, the properties you can define for it appear on the right side of the page.

To specify attribute element properties:

1. In the document tree, select an attribute element.

   The attribute element properties appear on the right side of the page.

2. In the Element Name field, enter the name of the element as you want it to appear in the generated XML.

   If you change this name, the complex primitive element and attribute element name changes to the value you enter.

3. Select the Required check box to make the attribute a required element.

4. From the Type drop-down list box, select an element type.

   Primitive element types are described elsewhere in this chapter.

   See Defining Primitive Element Properties.

5. Click the Save button.

Adding Additional Attribute Elements to Complex Primitive Data Types

You can add the following element types as attribute elements to complex primitive data types:

• Primitive child.

• Primitive peer.

• Compound peer.

• Collection peer.

You add these elements to complex primitives as you would any other element, first using the action toolbar on the Document Builder - Documents page to add the element to the document tree, and then defining the element properties.

See Managing Primitive Elements, Managing Compound Elements, Managing Collection Elements.

Defining Documents as Compound Element Data Types

After you create and name a document as the data type for a compound element, you specify the document package, document name, and document version on the Add Compound Child or Add Compound Peer page (IB_LOGICALCOMP_SEC).

When you specify a document as the compound element data type, you can select to use a reference of the document or a copy of the document. Using a reference of the document means that if the document defined as the compound element type is modified, then the changes will be rolled into that document. Using a copy of the document means that the document you define as the compound element type will remain the same, even if the original document is modified in the future.

This example shows specifying the document to add as a compound element data type:

After you search for and select a document, the Document Builder - Documents page appears, and the document appears as a compound element in the document tree. The following example shows the BillTo document added as a compound element to the DEMO_PURCH_ORDER document:

After you create a document as a compound element data type, the document element information appears on the right side of the page. A Go to Child Document link also appears. When you click the Go to Child Document link, the document definition for the compound element appears in a new window.

To define a document as a compound element data type:

1. Create and name a document as a data type for a compound element.

   See Adding Compound Elements.

2. In the Type drop-down list box, select an option:

   • Reference. (Default.)

     Use a reference of the document.

   • Copy.

     Use a copy of the document.

3. Specify the document:

   1. In the Package field, enter the document package name or click the Lookup button to search for one.

   2. In the Document field, enter the document name or click the Lookup button to search for one.

   3. In the Version field, enter the document name or click the Lookup button to search for one.

   4. Click the Search button.

      The search results appear in the Document List grid.

   5. Select a document from the list.

      The Document Builder - Documents page appears, and the document you specified appears in the document tree.

4. Click the Save button.

Defining PeopleSoft Records as Compound Element Data Types

After you name a compound element and choose to create a PeopleSoft record data type, you must search for and select the record. As with other compound data types, you use the Add Compound Child or Add Compound Peer page (IB_LOGICALCOMP_SEC), depending on whether you are creating a compound child or compound peer element.

The following example shows the Add Compound Child page when searching for a PeopleSoft record:

After you enter search criteria, the results appear in the Records grid. When you select a record from the grid, the Select Fields to Insert into New Document page (IB_LOGICALFLD_SEC) appears. Use the page to select the fields to include in the document. The fields become primitive elements in the document, and the record fields properties, such as data type and length, become the default primitive element properties in the document.

The following example shows the Select Fields to Insert into New Document page for the ORDER_ITEMS compound element based on the PeopleSoft record, ITEMS:

When you save the information, the record and its fields become a compound document element. In the previous example, you see that the system reads the package name and version from the document definition and supplies the document name in the Document field.

After you provide the document name and click the OK button, the new compound document element that you created from a PeopleSoft record appears in the document tree on the Document Builder - Documents page. The following example shows the compound element, ORDER_ITEMS, appearing in the document tree:

The previous example shows that the system converted the PeopleSoft ITEMS record and its fields into a document called ORDER_ITEMS, and that the document is a compound child element of the DEMO_PURCH_ORDER document.

Click the Go to Child Document link in the properties section of the page to view and modify the ORDER_ITEMS document definition.

Managing Collection Elements

This section provides an overview of managing collection elements and discusses how to:

• Add collection elements.

• Define collection element properties.

Understanding Managing Collection Elements

Only a collection item that is a primitive or compound data type can be added to a collection element. A Collection can have unlimited Collections as siblings.

Adding Collection Elements

Use the Add Collection Child or the Add Collection Peer page, depending on whether you want to create a collection child or collection peer element. The Add Collection Child page and the Add Collection Peer page share the same object page name: IB_LOGICALCOLL_SEC.

You access the Add Collection Child and Add Collection Peer pages using the action toolbar on the Document Builder - Documents page.

The following example shows the Add Collection Child page:

To add a collection element:

1. Access the Document Builder - Documents page (PeopleTools, Documents, Document Builder).

2. In the document tree, click the element to which to add a collection child or collection peer element.

3. On the action toolbar, do one of the following:

   • Click theAdd Collection Child button to add a collection child element.

   • Click the Add Collection Peer button to add a collection peer element.

   The Add Collection Child or Add Collection Peer page appears, depending on the element you added.

4. In the Element Name field, enter a name for the collection element.

5. Click the OK button.

   The Document Builder - Documents page appears, and the new collection element appears in the document tree. Note that the collection element icon that appears on the toolbar also appears to the left of the collection element in the document tree.

Defining Collection Element Properties

After you add a collection child or collection peer element to a document, the collection element properties appear on the right side of the Document Builder - Documents page. The following example shows the properties for a collection child element called order_status:

You can define the following collection element properties: