bea.com | products | dev2dev | support | askBEA
 Download Docs   Site Map   Glossary 
Search
e-docs > WebLogic Platform > WebLogic Integration > BPM Topics > Using the Studio > Working with XML Entities

Using the Studio

 Previous Next Contents Index View as PDF  

Working with XML Entities

The following sections explain how to use the Studio to retrieve, compose and save XML entities:

 

Overview of XML Document Management Tasks

Several workflow actions contain a built-in XML editor that you can use to create, edit, and export free-form and type-specified XML documents that are embedded in workflows. The XML Finder helps you locate XML entities from various sources and save them to different types of storage. Tasks related to managing the content and storage of XML documents are described below.

Note: You may also want to familiarize yourself with the workflow expression language and the Studio's Expression Builder tool before beginning to define XML documents, since the dialog boxes in which you can create XML documents require that you enter XML element values as expressions. Complete information on workflow expressions is available in Using Workflow Expressions.

 

Composing and Editing XML Documents

The following action dialog boxes contain a built-in XML editor that you can use to compose, import, and edit well-formed XML documents which are saved within the workflow template definition:

The XML editor presents XML documents in a tree structure consisting of nodes comprising the following standard XML markup:

The left pane displays metadata, such as element and attribute tags, and the right pane displays the actual data values for each tag.

The documents you create and edit in Studio dialog boxes are actually XML document templates that are used to generate XML document instances at run time. This means that you can use workflow expressions for elements and attributes to generate values at run time, and you can invoke the Expression Builder from one of these nodes to help you construct your expression. Element and attribute data must be formulated in workflow expression syntax, so all strings must be enclosed in quotation marks. If the value you enter is not a valid workflow expression, for example, a string not surrounded by quotation marks, or a backslash not preceded by an escape character, the icon appears in front of it. For information on the workflow expression language, and on using the Expression Builder, see Using Workflow Expressions.

You can create new documents and edit existing ones in two modes: free-form mode and content-type mode. In free-form mode, you simply compose and edit the document with no validation against a content type. Use free-form mode when you want to generate well-formed XML documents that do not need to conform to a specific content type. More information about creating free-form XML documents is provided in Creating Free-Form Documents.

In content-type mode, you specify the content type for a new or existing document by loading an existing external Schema document against which the document is validated. You can check the validity of the document as often as you like during the composing or editing process. Complete information about working with content-type-specified documents is provided in Working with Type-Specified Documents.

You can also import existing free-form and type-specified documents from the repository or a file on disk (see Importing Existing Documents), and add a content type to an existing document (see Setting a New Content Type for Existing Documents).

Finally, you can export document templates created or edited in the Studio to the repository or a file on disk. For more information on exporting XML documents from action dialog boxes, see Exporting XML Entities.

Dialog boxes that allow you to work with XML documents include a toolbar described in the following table. Specific procedures for creating, importing, editing, and setting the content type for XML documents are provided in the following sections.

Table 7-1 XML Editor Toolbar Buttons and Keyboard Shortcuts

Button

Keyboard Shortcut

Purpose


Ctrl+q

Retrieves an existing XML document for editing from the repository, a file on disk, or a URL location. For details, see Retrieving XML Entities.


Ctrl+w

Saves the XML message from the workflow to the repository or a file on disk. For details, see Exporting XML Entities.


Ctrl+t

Retrieves a Schema document to set as the content type for an XML document. For more information, see Working with Type-Specified Documents.


Ctrl+k

Displays the contents of the Schema file currently set as the content type. For more information, see Validating Type-Specified Documents.


Ctrl+l

Checks whether the document is valid XML and conforms to the current content type. For more information, see Validating Type-Specified Documents.


Delete

Deletes the selected node, or removes a content type definition from the current document if the document type declaration is selected.


Ctrl+Insert

Adds an element node at the same level as a selected element.


Insert

Adds a root element node for the document, or an element below the level of a selected element.


Ctrl+a

Adds an attribute node to a selected element.


Ctrl+p

Adds a processing instruction node.


Ctrl+m

Adds a comment node.


Ctrl+n

Adds a CDATA section node.


Ctrl+Up arrow

Moves a selected node up within a level.


Ctrl+Down arrow

Moves a selected node down within a level.


Ctrl+Left arrow

Moves a selected node down a level.


Ctrl+Right arrow

Moves a selected node up a level.

 

Creating Free-Form Documents

To create a free-form document:

  1. In the action dialog box containing the XML editor, click the Add Element button to add a root element to the document. The default element name is selected, ready to be edited.

  2. To rename the element, type over the default text element to enter a name.

  3. To add a value to the element, in the right pane, double-click the field next to the element, and type in a value, using workflow expression syntax.

  4. Continue to add nodes and values to the document by using the toolbar buttons listed in Table  7-1 or by following the procedures listed in Editing XML Documents.

  5. When you have finished composing your document, do any of the following:

Importing Existing Documents

You can import both free-form and content-type-specified XML documents that you have created and exported from the Studio's XML editor or created by any other method. For information about importing type-specified documents, see About Importing Type-Specified Documents.

When you import an existing XML document into a workflow, the XML editor distinguishes between two kinds of XML documents:

Workflow XML document templates created and exported from the Studio contain element and attribute string values enclosed in quotation marks, while other document instances usually do not. Thus, for XML documents not created in a Studio action dialog box, you will be prompted to convert the document to an XML template. The conversion process inserts quotation marks around all element and attribute values where necessary, so that you do not have to do so.

Note: The Studio does not recognize XML documents exported from previous versions of WebLogic Process Integrator as document templates, so you will still be prompted to convert the these XML documents. To prevent the XML editor from inserting an additional set of quotation marks, do not convert the imported document.

To import an existing free-form or type-specified XML document:

  1. From an action dialog box, click the Import button to display the XML Finder.

  2. Follow the procedures in Retrieving XML Entities to use the XML Finder to select a document from various sources. If the document is not detected as a document template, the Enclose Values in Double Quotes message prompt is displayed.

    Figure 7-2 Enclose Values in Double Quotes Dialog Box


     

  3. Respond as follows:

    The document is imported into the editor.

  4. Add and edit nodes and values as necessary, by using the toolbar buttons listed in Table  7-1 or by following the procedures listed in Editing XML Documents.

  5. Optionally, for a type-specified document, validate the document by following the procedures in Validating Type-Specified Documents.

  6. Optionally, to import another document, and replace the current one, click the Import button. When prompted to overwrite the current document, click Yes to continue the import, or No to cancel.

  7. When you have finished editing your document, do any of the following:

Editing XML Documents

The following procedures are generalized for new or imported free-form or content-type-specified documents. For additional procedures on type-specified documents, see Working with Type-Specified Documents.

Table 7-2 Editing XML Documents

To . . .

Perform This Action

Navigate through a document

In the left pane, expand all nodes. Use the scroll bar on the right-hand side of the right pane, or press Tab or the up and down arrow keys, to move up and down within the document.

Add the first element of a free-form document

Click the Add Child button, or press Insert.

Add a sub-element to an element

In the left pane, select the element, then click the Add Child button or press Insert.

Add an element at the same level as another element

In the left pane, select the element, then click the Add Sibling button or press Ctrl+Insert.

Edit an element name

In the left pane, double-click the element to display an entry field. Change the element name as appropriate.

Add an attribute to an element

In the left pane, select the element, then click the Add Attribute button, or press Ctrl+a.

Edit an attribute name

In the left pane, double-click the attribute to display an entry field. Change the attribute name as appropriate.

Edit a value for an element or attribute

In the right pane, double-click the line next to the element or attribute for which you want to add or edit the value. An entry field is displayed. Type the value, or click the Expression button to invoke the Expression Builder to construct a valid workflow expression. String literals must be enclosed in double quotes. If the syntax is incorrect, a red X appears next to the entry. For details about defining workflow expressions, see Using Workflow Expressions.

Add a comment node

In the left pane, select the element after which the comment will appear, then click the Add Comment button, or press Ctrl+m.

Add a processing instruction

In the left pane, select the element after which the processing instruction will appear, then click the Add Processing Instruction button, or press Ctrl+p.

Change a processing instruction target

In the left pane, double-click the processing instruction to display an entry field. Change the processing instruction target as appropriate.

Add a CDATA section

In the left pane, select the element after which the CDATA section will appear, then click the Add CDATA button, or press Ctrl+n.

Edit a value for a comment, processing instruction, or CDATA section

In the right pane, double-click the line next to the comment, processing instruction, or CDATA icon for which you want to edit the value. An entry field is displayed. Type the value.

Change the order of nodes

Select the element, attribute, comment, processing instruction, or CDATA section you want to move, and click the Move Node Up or Move Node Down arrow, or press Ctrl+the up or down arrow key.

Change the hierarchical level of nodes

Select the element, comment, processing instruction, or CDATA section whose level you want to change, and click the Move Node Right or Move Node Left arrow, or press Ctrl+the right or left arrow key.

Delete a node

In the left or right pane, select the element or attribute you want to delete, and click the Delete button, or press the Delete key.

 

Working with Type-Specified Documents

You can create an XML document based on an existing external Schema. Internal DTD declarations are not supported.

You can also import an existing document based on a Schema, and you can set the content type for a document already loaded into the XML editor.

About Storing Referenced Schemas

Because theWebLogic Integration server needs to be able to access a Schema document associated with the XML document template at run time to create an XML document instance, Schemas to be referenced by Studio XML documents must exist as XSD files in a location that can be accessed by a URL, or as entities in the repository.

Warning: Keep in mind that if the URL points to a location not on the same machine as the WebLogic Integration server, there is always a risk that the system referenced by the URL may not be available at run time when the process engine generates the XML document instance. In such an occurrence, server exceptions will result. You should take care to store your XSD files in locations that can be reliably accessed at run time, such as on the file system of the WebLogic Integration server. Also ensure that the URLs you use remain valid at run time and point to the correct location of the required resources.

You may find that storing Schema resources in the repository is a convenient way to retrieve commonly accessed documents. For procedures on importing resources into the repository, see Managing Entities in the Repository.

On the other hand, you should also keep in mind that if you are planning to export newly created documents, or re-export imported documents, references to Schemas held in the repository are only identified by the entity name in the content type declaration, and will not be resolved by third-party XML parsers. Thus, you will want to ensure that your XSDs are placed in an appropriate location depending on whether an exported XML document will be used outside of WebLogic Integration or not. If they are to be used outside of WebLogic Integration, we recommend storing resources on a disk file and accessing them via URLs. If they are not going to be used outside WebLogic Integration, we recommend storing resources in the XML repository.

About Importing Type-Specified Documents

You can import an existing document that contains a document type declaration to an external Schema document, but not to an internal one. However, you must ensure that the referenced Schema is available for the WebLogic Integration server to access at design time, and that the document type declaration uses a valid URL to specify the document location. If the declaration only includes the name of the document, but not the full location, the WebLogic Integration server will not be able to resolve the reference, and the document cannot be imported.

Another option is to store referenced Schema resources in the XML repository. In this case, you may simply specify the name of the repository entity in the document type declaration, and the WebLogic Integration server will resolve the reference. For procedures on importing resources into the repository, see Managing Entities in the Repository.

If you are planning to re-export the document you have imported, the run-time considerations mentioned above also apply.

For procedures for importing type-specified documents, see Importing Existing Documents.

Creating Type-Specified Documents

When you create a new XML document based on a Schema, the XML editor creates a default document consisting of the following:

To create a new type-specified document:

  1. In the action dialog box containing the XML editor, click the Set Content Type button . The XML Finder is displayed.

  2. Follow the procedures in Retrieving XML Entities to use the XML Finder to select a Schema document from the appropriate sources. When the content-type document is retrieved, the Generate Default Document message prompt is displayed.

    Figure 7-3 Generate Default Document Dialog Box


     

  3. Click Yes to generate a default document. The Select Root Element dialog box is displayed, showing a list of all defined elements.

    Figure 7-4 Select Root Element Dialog Box


     

  4. Select the element that should be the root element of the document and click OK. A default document is created. For a DTD-based document, a prolog with the document type declaration is inserted above the root element. For a Schema-based document, an attribute referencing the Schema is inserted in the root element.

  5. Add and edit nodes and values as necessary by using the toolbar buttons listed in Table  7-1 or by following the procedures listed in Editing XML Documents.

  6. Validate your document by following the procedures in Validating Type-Specified Documents.

  7. When you have finished composing and validating your document, do any of the following:

Setting a New Content Type for Existing Documents

You can apply a content type definition to a document after you have created it or to an existing document after import. You can also remove a content type from a type-specified document, or change the content type for a new or existing type-specified document.

To apply a content type definition to a free-form document:

  1. Do one of the following:

  2. Click the Set Content Type button . The XML Finder is displayed.

  3. Follow the procedures in Retrieving XML Entities to use the XML Finder to select a Schema document from the appropriate sources. When the content-type document is retrieved, the Generate Default Document message prompt is displayed.

    Figure 7-5 Generate Default Document Dialog Box


     

  4. Click No to preserve the existing document.

  5. Continue to define your document, as described in Editing XML Documents.

  6. Validate your document, as described in Validating Type-Specified Documents.

To remove a content type definition from a type-specified document:

  1. For a Schema-specified document, select the root element attribute node referencing the Schema.

  2. Click the Delete button . The content type definition is removed, and the document becomes a free-form document.

To change the content type for a type-specified document:

  1. For a Schema-specified document, select the root element attribute node referencing the Schema.

  2. Select the node containing the content type definition, above the root element.

  3. Click the Delete button . The content type definition is removed.

  4. Click the Set Content Type button . The XML Finder is displayed.

  5. Follow the procedures in Retrieving XML Entities to use the XML Finder to select a Schema document from the appropriate sources. When the content-type document is retrieved, the Generate Default Document message prompt is displayed.

  6. Click No to preserve the existing document.

  7. Continue to define your document, as described in Editing XML Documents.

  8. Validate your document, as described in Validating Type-Specified Documents.

Validating Type-Specified Documents

While composing or editing a new or imported type-specified documents, you can view the content of an Schema document set as the current content type, and you can take advantage of the Studio validation feature that allows you to view the source of errors and edit them simultaneously.

To view the content of the associated Schema:

  1. Click the View Content Type Definition button . The Content Type Definition window is displayed, showing the content of the current content type definition document.

    Figure 7-6 Content Type Definition Window


     

  2. Click Close to close the window.

To validate a new or imported type-specified document against the content type definition:

  1. Click the Validate Document Structure button . A message is displayed, informing you whether the document is valid. If there are errors in your document, the Validation Errors dialog box appears, listing the nature and location of the error.

    Figure 7-7 Validation Errors Dialog Box


     

  2. Click Next or Prev to scroll through the list of errors, and edit the erroneous node.

  3. When done, click Close to close the dialog box.

  4. Click the Validate Document Structure button again to re-validate the document, and repeat steps 1 to 3 until you receive the Valid Document message.

  5. Click OK to close the Valid Document message box.

 

Using the XML Finder to Retrieve and Export XML Entities

The XML Finder dialog box allows you to retrieve from and save XML entities to the repository, the local file system, or a URL. The dialog box also maintains a list of the XML entities you used most recently, so you do not have to search for them if you want to use them again.

XML entities can be XML documents, Document Type Definitions (DTD), Schema documents (XSD), Message Language Format (MFL) files, and Extensible Stylesheet Language (XSL) template documents.

You can access the XML Finder several ways. Different operations are available depending on the way you access the XML Finder, and whether you are retrieving or saving a document. These topics are described in the following sections.

Retrieving XML Entities

You can retrieve and load XML entities into the following dialog boxes:

Retrieving the Most Recently Used XML Entities

The XML Finder maintains a list of the XML entities you used most recently on your workstation. You can re-use the entities in the list without having to search for them again.

To retrieve an entity from the most recently used list:

  1. Open the XML Finder by doing one of the following:

    Note: The Recent tab is unavailable from the XSL Transform dialog box, and from dialog boxes where you can open a Schema document, because these actions create an XML document instance at run time. Specifying a recent entity is not appropriate in these cases because the process engine cannot access the file at run time.

  2. In the XML Finder dialog box, select the Recent tab. Disk files are identified by filename and location. repository entities are identified by entity name.

    Figure 7-8 XML Finder: Recent Tab


     

  3. Select the entity you want to use.

  4. Optionally, to see the contents of the entity, click Preview to display the Preview Document window. Click OK to close the window.

  5. To return the entity to the original dialog box, click OK.

Retrieving from the Repository

To retrieve an entity from the repository:

  1. Open the XML Finder by doing one of the following:

  2. In the XML Finder dialog box, select the Repository tab.

  3. Select the folder from which you want to retrieve an XML entity.

    Figure 7-9 XML Finder: Repository Tab


     

  4. In the top-most panel on the right, select the entity you want to retrieve.

  5. Optionally, to see the contents of the entity, click Preview to display the Preview Document window. Click OK to close the window.

  6. To return the entity to the original dialog box, click OK.

Retrieving from the File System

You can retrieve content from a file on a local disk drive or any network drive mapped to the local machine.

To retrieve an entity from the local file system:

  1. Open the XML Finder by doing one of the following:

    Note: The File tab is unavailable from the XSL Transform dialog box, and from dialog boxes where you can open a Schema document, because these actions create an XML document instance at run time. Specifying a file on the local file system is not appropriate in these cases because the process engine cannot access the local file system at run time.

  2. In the XML Finder dialog box, select the File tab.

    Figure 7-10 XML Finder: File Tab


     

  3. In the Look in field, specify the drive and folder from which you want to obtain the XML entity. If necessary, use the buttons to the right of the Look in field.

  4. From the file list, select the entity you want to retrieve.

  5. Optionally, to see the contents of the entity, click Preview to display the Preview Document window. Click OK to close the window.

  6. To return the entity to the original dialog box, click OK.

Retrieving from a URL

You can use a URL to specify a location on a local machine, remote machine on a network, or other external systems. Remote locations must be mapped to a drive on the local machine.

To retrieve an entity from a URL:

  1. Open the XML Finder by doing one of the following:

  2. In the XML Finder dialog box, select the URL tab.

    Figure 7-11 XML Finder: URL Tab


     

  3. In the URL field, enter the complete URL, including the protocol, server, path and filename, of the XML entity you want to retrieve.

  4. Optionally, to see the contents of the entity, click Preview to display the Preview Document window. Click OK to close the window.

  5. To return the entity to the original dialog box, click OK.

Exporting XML Entities

You can save XML documents created within the Studio from the following dialog boxes:

Documents exported from action dialog boxes are formatted with the standard XML escape sequences (") representing quotation marks around element and attribute values. For content-type-specified documents, a prolog including the DOCTYPE and an epilog indicating the validity are also inserted.

Exporting to the Repository

When you export an XML document template from an action dialog box to the repository, the entry is created in two steps. First, an empty entity is created. Then, the entity is populated with the content of the document template. For this reason, it is not possible to preview the document until after it has actually been populated with content, which occurs when you exit the XML Finder.

To save an entity from an Action dialog box to the repository:

  1. From the Set Workflow Variable, Send XML to Client, Post XML Event and Invoke Exception Handler action dialog boxes, click the Export button . The XML Finder appears.

  2. Select the Repository tab.

  3. In the left pane, right-click the folder in which you want to save the entity, and from the pop-up menu, select Add Entity. The Add Entity dialog box appears.

  4. In the Name field, enter a unique name for the entity you are adding.

    Figure 7-12 Add Entity Dialog Box


     

  5. Using the Type drop-down list, select the type of entity you are adding.

  6. Optionally, enter a description and notes about the entity in the Description and Notes fields, respectively.

  7. Click OK. The entity appears in the top right window of the XML Finder.

  8. Click OK to exit the XML Finder. The entity has now been created in the repository.

Exporting to the File System

From action dialog boxes, you can save the XML documents you create or edit as .xml files on a local disk drive or any remote drive mapped on the local machine.

To save an entity to a file on disk:

  1. From the Set Workflow Variable, Send XML to Client, Post XML Event and Invoke Exception Handler action dialog boxes, click the Export button . The XML Finder appears.

  2. In the XML Finder, select the File tab.

    Figure 7-13 XML Finder: File Tab


     

  3. In the Look in field, specify the drive and folder in which you want to save the XML entity. If necessary, use the buttons to the right of the Look in field.

  4. In the File name field, enter the name of the file you want to create, and add the .xml extension. If the file already exists, you are prompted with a warning message. Click Yes to overwrite the file, No to enter a new filename, or Cancel to cancel the export.

  5. Click OK to save the file and exit the XML Finder.

Exporting to a Recently Accessed File

You can only use the Recent tab to export to and overwrite an already existing file.

To save an entity to a recently accessed file:

  1. From the Set Workflow Variable, Send XML to Client, Post XML Event and Invoke Exception Handler action dialog boxes, click the Export button . The XML Finder appears.

  2. In the XML Finder, select the Recent tab.

  3. In the list of entities, select the XML file or repository entity you want to overwrite.

  4. Click OK to save the file and exit the XML Finder.

Exporting to a File Located by a URL

You can only use the URL tab to export to and overwrite an already existing file that can be located by a URL.

To save an entity to an existing file located by a URL:

  1. From the Set Workflow Variable, Send XML to Client, Post XML Event and Invoke Exception Handler action dialog boxes, click the Export button . The XML Finder appears.

  2. In the XML Finder, select the URL tab.

  3. In the URL field, enter the complete URL, including the protocol, server, path and filename, of the XML file you want to overwrite.

  4. Click OK to save the file and exit the XML Finder.

 

Back to Top Previous Next