Copyright © 1999-2023. Cloud Software Group, Inc. All Rights Reserved.

XML Canon

XML Canon/Developer (XCD) is a comprehensive development platform that allows organizations to store their XML assets (e.g. XML schemas, DTDs, adjuncts, instance documents, and stylesheets) in a central repository that facilitates adaptability, collaboration, and management.

XML Canon is an entire persistence system that has some RCS capability but not a multi-file project per se.

XML Canon uses permissions to control access to the stored files. XML Canon also provides version control, protecting the development process from duplicate or conflicting efforts.

Features

The following features, accessible via XML Canon's web interface, are provided for the XML-based files in your project, such as your XML Schemas, WSDL files and process definitions.

•	Custom Property Association—apply custom metadata to documents or individual components.

•	Document and Component-Level Searching—query for document and components through a wide array of filters.

•	Namespace Management—browse through a listing of target namespaces and see how a given namespace is used in schema and instance documents.

•	XML Document Differencing—track changes between revisions.

•	SchemaDOC™—generate a graphical inventory and detailed description of an XML Schema’s or DTD’s components in a user-friendly HTML format.

•	Document/Component Relationship Tracking—track the relationship between documents and their components and determine where schemas or individual components (XML Schema elements or types or WSDL message components, for example) are used within the project.

For more information on XML Canon, see the XML Canon Developer documentation available as online help with the product and also via the TIBCO documentation library. The remainder of this section describes the process for specifying XML Canon as the repository for a project, the typical steps for interacting with XML Canon, and some tips and tricks that will facilitate the effective use of XML Canon.

Prerequisites

To use XML Canon as the version control system for TIBCO Designer, you must have:

•	the address of the XML Canon server and the port number on which it is running.

•	an XML Canon user name and password with the permissions required to work in the XML Canon category in which the shared project is stored.

Checking In and Acquiring Resources

This section provides the typical steps involved in interacting with the XML Canon repository, beginning with the initial association of the TIBCO Designer project with an XML Canon category.

Step 1: Specifying XML Canon as the version control system for a given project

This step is performed once for a given project. Each project should be associated with a unique XML Canon category.

To specify XML Canon as the version control system for a given project, select Project > Save As to display the Save Project window.When you open a new empty project, the Save Project dialog appears automatically by default.

Select the XML Canon tab, which requires you to specify these fields:

•	Proxy server—You may access XML Canon via a proxy server that does not require authentication. Not all proxy servers support the WebDAV extensions to HTTP that XML Canon uses. Make sure the proxy server supports required additional functionality.

If you click the Browse button for the XML Canon category field, the proxy server you specified is taken into account. As a result, it is essential that you specify the proxy server before you click Browse.

•	XML Canon category—the URL (http://hostName:portNumber/categoryName) of an empty XML Canon category, which will serve as your top-level project folder.

•	User name—an XML Canon user name.

•	Password—password associated with the user name.

Figure 21 depicts the XML Canon tab filled in with the required information.

Figure 21 XML Canon Tab

 

If you do not know the location of an empty category, click Browse. The Browse for Project Folder will appear. Enter the URL for the XML Canon server and click Connect. You will be prompted to enter your XML Canon user name and password. Upon successful authentication, you will be presented with all of the top-level categories, as depicted in Figure 22.

Figure 22 Browse for an XML Canon Category

Double-click a category (or use the Open button) to view its child categories. New categories can be created using the new folder icon. When you have selected the category in which to store the project, click Select Folder.

Some XML Canon users may not have the ability to create a new category. If you are unable to create a new category, see your XML Canon administrator.

When a URL, user name, and password have been specified on the XML Canon tab, click OK. The specified XML Canon category will now be used to store the project. See Step 2: Check in the project to learn how to make the existing resources in the project accessible to all XML Canon users with the permissions to work within the category.

Step 2: Check in the project

The folders and resources existing within the project prior to Step 1 can be checked into XML Canon by way of the Check In Changes option of the Multi-User menu. The XML Canon Check In dialog appears, listing the folders and files that have been added, moved, modified, or deleted since the project was last checked-in. The XML Canon Check In dialog is shown in

Figure 23 XML Canon Check In Dialog

Global variable settings will appear in the dialog as "defaultVars".

Check-in options are controlled with the following buttons

Table 3 Check-in Buttons

Button	Description
Close	Closes the window without checking in any files.
Undo Changes	Reverts the selected folders or resources to their status prior to the last acquire-check out.
Check in selected	Checks in the changes associated with the selected files or folders.
Check in all	Checks in all of the changes.
Properties	XML Canon augments standard WebDAV functionality by allowing you to specify additional properties when a document is saved. By default you may specify a comment, a revision label, and a stage. If the XML Canon Administrator has configured your server to use custom properties, you may also specify those custom properties. To set all properties, you: • Select a file in the "Check In" dialog, then click "Properties...", or • Double-click an item. Items for which the user has already specified custom properties are shown in bold in the dialog. Depending on how the server is configured, it may not be possible to save changes to XML Canon unless you have specified extended properties. This can happen for two reasons. • The "stage" that the document is currently in does not allow a transition to itself (for example, a "production" document cannot be modified without taking it out of "production"), or • The administrator has specified "custom properties" that are required, and the document may not be saved unless those properties are specified.

A lock icon in the project panel, indicating that the files are not acquired and cannot be edited, marks checked-in items. Figure 24 depicts a project checked into XML Canon.

Figure 24 A Project Checked into XML Canon.

If you are unable to check in changes, your XML Canon user profile may not have the appropriate permission settings. See your XML Canon administrator.

Step 3: Acquiring folders or resources and making changes

Once a project has been associated with XML Canon (see Step 1) and checked-in for the first time (see Step 2), its resources can be acquired (checked out) by other users with access to the XML Canon server and with permission to work within the category associated with the project.

To open a project stored on XML Canon

1.	Select the XML Canon tab from the Open Project dialog.

2.	Specify (or browse for) the XML Canon category in which the project is stored

3.	Supply a user name and password.

Upon successful authentication, the project will be opened.

Upon opening a project shared through XML Canon, you should synchronize the project (Multi-User>Synchronize Project). Synchronize often to ensure that your project tree reflects any resources you have added outside of TIBCO Designer (through a WebDAV folder or the XML Canon interface, for example) as well as any changes made by other users.

Folders and resources marked by a lock icon are read-only until acquired.

To acquire a resource

1.	Select the resource in the project tree

2.	Select Acquire - Check out Resource from the right button menu or the Multi-User menu.

When a resource is acquired, its lock icon will disappear, indicating that you may edit the file.

 

Use the global variables display to acquire global variables. Global variables are acquired through the Acquire-Check out Global Variable Group option of the right-button menu.

Once a user acquires a resource, other users cannot modify it. (Other users can view the resource, but cannot make changes to it.) If you attempt to acquire a resource that is under the control of another user, the message shown in Figure 25 will appear.

Figure 25 Acquire-Checkout Failed

Step 4: Checking in (or reverting) the changes made to an acquired resource

Changes made to acquired resources can be checked into XML Canon, following the same procedure outlined in Step 2.

Reverting Changes

There are two options for returning a folder or resource to its status prior to your acquisition:

•	Select the change(s) within the Check In Changes Dialog and click Undo Changes.

•	Select the modified folder or resource within the project panel and select the Release-Revert Resource option, available via the right-button menu and the Multi-User menu.

Viewing Revision Control Information

The revision control system (RCS) information for a particular resource can be viewed by selecting the View RCS Info for Resource option from the right-button menu or the Multi-User menu. The information available is described in Table 4.

Table 4 Revision Control System Information

Field	Description
Analyzed state	This indicates if the resource was analyzed for document and component level relationships. This applies to XML Schema, DTD, and WSDL resources only.
Comment	Displays any comments added when checking the resource into XML Canon.
Creation date	The date the resource was created.
Display name	The name of the resource.
Document flavor	The resource type.
Document id	The XML Canon internal id for the resource.
Document size	The size of the resource in bytes.
Governing namespace	Namespace that the document governs, for example, in XML Schema, the value of the 'targetNamespace' attribute.
Last modified	The time and date of the last modification.
Last modified by	The name of the user making the last modification.
Last modified by id	The XML Canon internal id of the user making the last modification.
Lock token	Globally unique identifier for the resource being acquired (locked on the server).
Locked by	The user who has acquired the resource.
Mime type	The Multipurpose Internet Mail Extension.
Resource type	The WebDAV resource type.
Revision name	A revision label added when checking the resource into XML Canon.
Revision number	The number of times the resource has been checked into XML Canon.
Root namespace	The default namespace of the resource.
Stage id	The XML Canon internal stage id for the resource.
Stage name	The XML Canon stage of the resource.
Supported lock	The WebDAV locks allowed on the resource.

You can apply custom metadata to the resources through the DAV tab of the user’s XML Canon home page. For XML Schemas, DTDs and WSDL files, custom properties can be specified for individual components as well.

Deleting XML Canon Projects

XML Canon-based projects cannot be deleted in TIBCO Designer. To delete a project, use a WebDAV client.

Tips and Tricks

The following tips will help you use XML Canon effectively as a version control system.

•	Synchronize (Multi-User > Synchronize Project) often to ensure your project reflects the changes made by other users.

•	Any conflicts discovered during the synchronization process will be listed along with instructions for resolving the conflict. You cannot check in any changes until synchronization conflicts are resolved.

•	Because XML Canon automatically treats all of the project’s resources as part of the Revision Control System, the Add Resource to RCS option of the right-button menu Multi-User menus is not applicable when working with XML Canon.

•

When checking in changes, keep in mind that some changes are dependent upon other changes. (For example, a new child folder cannot be checked in until its parent folder is checked in.) If you check in a single change (using the Check in selected button) with a dependency on another change, the other change will also be checked in.

•	Acquisitions are not recursive. When you acquire a folder, its resources and sub-folders are not checked-out.

•	A folder must be acquired if you want to:

a.	rename the folder (or one of its resources or sub-folders)

b.	move the folder

c.	edit the folder’s description

d.	delete the folder

Copyright © 1999-2023. Cloud Software Group, Inc. All Rights Reserved.