This article discusses various ways to copy xCommerce objects between projects and between machines including using the Import feature, Disk File copying, the Clipboard, and plain text copying.

When  creating an xCommerce project, you use Designer to build a variety of xObjects including XML Templates, Connections, Code Table Maps, Custom Scripts, Components, and Services. xObjects themselves are simply XML files (i.e. text) stored beneath your project directory on disk. The XML files contain meta-data for the xObject that is interpreted and executed by xCommerce Server and editable/executable by Designer.  In fact every aspect of a project is stored as XML text files. Sometimes it is desirable to copy xObjects from one project to another. This can be done a number of ways (each with its own advantages and disadvantages) including using Designer's Import features, copying xObject disk files, copying xObjects to the clipboard, and copying XML text to the clipboard.

Services, Components, Code Tables, Code Table Maps, Connections, Custom Scripts, and XML Templates.

xObjects not supported:

The main Project file (yourproject.xcp).

The project variables file (PROJECT.xml).

XML Template Categories.

Deployed Project files.

Also, references between xObjects are not supported. So if you Import a JDBC component without importing the connection xObject it utilizes, the component won't work. Or if you import a Code Table Map without importing the Code Tables it uses, it won't work either.

Process:

Open the target project, select an xObject category, and using the RMB, pick Import from the context menu. From the Import dialog browse the file system to locate the source project and particular xObject.

Advantages:

Import copies complex xObjects composed of multiple meta-data files such as XML Templates (which are composed of an xObject file in the XML Template directory, one or more XML Sample files, a DTD file, and an XSL file in the Imports sub-directory) and Custom Scripts (which are composed of an xObject file in the Script directory and multiple function files in the functions directory). Import also lets you conveniently rename the xObject during the Import. As an added bonus, Designer remembers the last project you imported from thus reducing the navigation you have to do. In addition, each time you do another import Designer even positions you to the proper xObject sub-directory if you change the type of xObject you are importing.

Disadvantages:

Import can be slow when copying many xObjects because it only copies individual xObjects and not whole categories or whole projects. Also Dependent xObjects are not automatically copied.

NOTE: With some xCommerce objects copying the xObject meta file on disk can be as good as an Import but only when the following two conditions are true: 

1.     The xObject is not dependent on other xObjects to work
2.     The xObject consists of only a single XML file on disk. 

A Connection Resource, a Code Table Resource, and an XML Map component whose functionality is self-contained match this profile and can be equally transferred between two projects by either copying the xObject meta file or Importing the object.

However, a Service depends on other Components it calls to work properly so it doesn't fit the profile.  The exceptions to this statement are when the Service is defined to behave like an XML Map component and does not call other components.  Code Table Maps also do not fit the above profile because they require Code Tables, and Enterprise Enablers require a Connection Resource. In this case Import falls short because it does not copy the dependent xObjects along with the xObject of interest. So you have to perform either additional Imports for the dependents or additional file copies.

That leaves two remaining xObjects: XML Templates and Custom Scripts. XML Templates consist of multiple objects on disk. There is the Template definition file plus one or more Sample XML documents plus an optional DTD and an optional XSL Style Sheet. Import works well for this case because it copies these files collectively and places them in the proper project sub-directories.

That leaves Custom Scripts. Custom Scripts are an interesting hybrid. Although it appears on disk that each Custom Script Resource is a single XML meta file, alas they are not.  When you create a Custom Script Resource (such as the Date library included on the xCommerce distribution CD), Designer creates an XML object file for it that contains all the text you wrote to create all the individual functions in the Custom Script. When you validate the Custom Script, Designer then parses each function for correct syntax and creates individual meta-data files about each individual function (these are used to display the Custom Scripts in the Expression Builder). So, if the Date library you were creating had 10 functions in it, when all is said and done you will have one Custom Script object in the 'script' directory of your project and 10 function meta data files in the 'functions' directory of your project. 

So with Custom Scripts you can just copy the xObject file to another project, HOWEVER, the custom scripts will not work until you open and validate them. Once the scripts are validated, Designer will re-create all the function meta-data files in the function directory and everything will work.  Of course if you just Import the Custom Script, Designer will automatically bring along all the function meta files as well.

xObjects supported:

Services, Components, Code Tables, Code Table Maps, Connections, Custom Scripts, XML Template Categories, XML Templates, the main projectfile (yourproject.xcp), and the project variables file (PROJECT.xml).

xObjects not supported:

All xObjects are supported.

Process:

Before using any variations of this method, be sure to review the Designer documentation section titled "Understanding Where Project Files are Stored". To copy an entire project, use Windows Explorer and simply copy the top level project directory and paste it to a new location.  This may or may not copy any deployment related files depending on where you created them.  To copy an entire category of xObjects such as all XML Map components, simply copy the contents of the xObject sub-directory "map" (but not the actual directory) and paste the files into the "map" sub-directory of the target project. The next time you open the target project with Designer, or click off and then click on that category in Designer, you will see the new objects.

Likewise to copy an individual xObject such as a single JDBC component named "myJDBC", use Windows Explorer and simply copy the xObject file "myJDBC.xml" from the source project "jdbc" sub-directory to the target project "jdbc" sub-directory. A variant of the single copy method is make the xObject an attachment to an eMail allowing you to cross machine and network boundaries. Remember, however, when copying either individual xObject files or a category directory be sure to also copy any referenced xObjects that are needed such as XML Templates, Connections, Code Tables, or Custom Scripts.

Advantages:

You can quickly copy an entire project, a category of xObjects, or individual xObjects. This method copies complex xObjects composed of multiple meta-data files such as XML Templates (which are composed of an xObject file in the XML Template directory and one or more XML Sample files in the Imports sub-directory) and Custom Scripts (which are composed of an xObject file in the Script directory and multiple function files in the functions directory).

Disadvantages:

Requires knowledge of the underlying file structure for a project. You don't have an opportunity to rename any objects. Referenced xObjects are not automatically copied.

Services, Components, Code Tables, Code Table Maps, Connections, Custom Scripts, and XML Templates. While not a true xObject in its own right, an Action can be copied using this method too.

xObjects not supported:

XML Template Categories, the main projectfile (yourproject.xcp), and the project variables file (PROJECT.xml).

Process:

To copy an xObject, select it in Designer and press the toolbar Copy button. Next pick the File | Recent Projects menu choice and select the target project. Once in the target project highlight the proper category and press the Paste button.

For Actions, simply open the source component, copy an action, open the target component and paste. Alternatively, you can have both components open and simply drag and drop selected actions.

Advantages:

This is perhaps the quickest way to make a copy of an xObject. This method copies complex xObjects composed of multiple meta-data files such as XML Templates (which are composed of an xObject file in the XML Template directory and one or more XML Sample files in the Imports sub-directory). However, with Custom Scripts (which are composed of an xObject file in the Script directory and multiple function files in the functions directory) the functions directory portion of the Custom Script is NOT copied. To solve this problem you can simply open the copy of the Custom Script in the target project and press the Validate button.

Disadvantages:

This method only copies individual objects. You don't have an opportunity to rename any objects. Referenced xObjects are not automatically copied.

NOTE: Copying to the clipboard allows you to create your own Custom variants of the basic Actions available in the XML Map Component.  Copy an action to the clipboard.  Create a new or open an existing Custom Script in Designer.  Create a new function name with an empty body between two braces (i.e.  myAction() {   }   ).  Paste the clipboard contents between the braces and the ECMAScript equivalent of the Action is created.  You can then modify the behavior of the Script.  After validating and saving the Script you can then call myAction() from any Component in the Project from any Action that has access to the Expression Builder (typically Map and Function Actions).

xObjects supported:

Services, Components, Code Tables, Code Table Maps, Connections, Custom Scripts, and XML Templates.

xObjects not supported:

XML Template Categories, the main projectfile (yourproject.xcp), and the project variables file (PROJECT.xml).

Process:

This is an interesting twist to copying an individual xObject file. After selecting an xObject in Designer and pressing the Copy toolbar button you can paste the object as text into a Word processing file or the body of an eMail. The receiver of the document or mail simply copies the XML text, opens their project in Designer, selects the proper xObject category and presses the Paste toolbar button. The xObject becomes part of their project.

Advantages:

This method allows you to send an xObject embedded as text in other types of objects and actually view the meta-data contents. Text Copy also copies complex xObjects composed of multiple meta-data files such as XML Templates (which are composed of an xObject file in the XML Template directory and one or more XML Sample files in the Imports sub-directory). However, with Custom Scripts (which are composed of an xObject file in the Script directory and multiple function files in the functions directory) the functions directory portion of the Custom Script is NOT copied. To solve this problem you can simply open the copy of the Custom Script in the target project and press the Validate button.

Disadvantages:

This is probably the slowest way to copy an xObject. This method only copies individual objects. You don't have an opportunity to rename any objects. Referenced xObjects are not automatically copied.