Using the Components Import/Export Utility

The ProjectWise Components import/export utility (Pwcompie) can import and export component schemas (data models) and instance data to and from an application-neutral XML format. It can be used to install sample data models or data sets, and to transfer data from a staging computer to a production computer. In addition, the utility provides an alternative way of importing and exporting component data to and from ProjectWise.

The format of the information read from and written to the ECXML import/export file conforms to the ECXML schema, an XML schema developed by Bentley.

CAUTION: Access rights for a component class can be exported from one datasource and imported into another. Before you can import access rights into a datasource, however, you must add the users and groups to which the access rights are assigned to the datasource. If the users or groups are not in the datasource, the access rights will not be imported with the rest of the class data.

To Run the Components Import/Export Utility

In a command window, go to the ...\ProjectWise\bin directory.
Note: If the directory in which the utility resides is included in the system PATH variable, you do not need to be in this directory when issuing the command.
At the command prompt, enter:
```
pwcompie (–importSchema | –importInstances | –exportSchema | –exportInstances) filename [options]
```
Choose one of the commands in parentheses. See Examples of importing and exporting with Pwcompie.

Pwcompie options

The table lists the options for the Components Import/Export utility.

Option Syntax	Alternate Syntax	Description
–importSchema <importFile>	–is <importFile>	ECXML import file containing a schema
–importInstances <importFile>	–ii <importFile>	ECXML import file containing instance data
–exportSchema <exportFile>	–es <exportFile>	EXCML export file containing a schema. The exportFile is the ECXML export file into which schema or instance data will be written.
–exportInstances <exportFile>	–ei <exportFile>	ECXML export file containing instance data The exportFile is the ECXML export file into which schema or instance data will be written.
–ecIndex	–x	Import/export Components index entries and instance data
–ecIndexOnly	–xo	Import/export Components index entries only (no instance data)
–instructions <instFile>	–n <instFile>	ECXML instructions file (if omitted on export, defaults to export all)
–forDocument <docPath>	–f <docPath>	ECXML export of all instance data (and optionally Components index entries) associated with the specified document
–datasource <datasource>	–d <datasource>	ProjectWise datasource login (if omitted, you will be prompted)
–user <username>	–u <username>	ProjectWise login user name (if omitted, you will be prompted)
–pass <password>	–p <password>	ProjectWise login password (if omitted, you will be prompted)
–nameSpacePrefix <prefix>		nameSpacePrefix xml attribute value for the exported ECSchema, for example 'simcorp'.
–schemaName <name>		schemaName xml attribute value for the exported ECSchema, for example 'Bentley.Simcorp.Demo'
–schemaVersion <MM.mm>		Major and minor version of the ECSchema you are exporting, for example 01.04
–upgrade20 <file>		Upgrade ECSchema from ECXML1.2 to ECXML2.0. Outputs to current directory. -upgrade20 requires a login, though it will not alter the datasource into which you login.
–exportOdsSystemSchema		Export Bentley_ODS ECSchema. Filename determined by ECSchema Version
–preview	-	Preview import without actually importing (import only)
–noprompt	-np	Suppress prompts and fail with error (use when running an unattended process)
–suppressaccessrights	-sp	Suppress export of access rights
–novalidate	-	Skip schema validation. If the schema is not validated before export, schema inconsistencies may not be detected, and the schema import may not succeed. In some cases, however, you may need to disable validation to allow export of a certain subset of the schema that is not invalid. Schema validation is also initiated before and after schema import. Before import, validation determines if the existing schema is valid.

Examples of Importing and Exporting with Pwcompie

The following are examples of how to use the pwcompie utility.

Exporting a schema to a datasource, using the ECXML instructions file

pwcompie –exportSchema mySchema.xml –instructions MyInstructionFile.xml –datasource myPWDatasource –user myUserName

Since the ProjectWise password option is not included, the user will be prompted to enter it.

Importing a schema into a datasource

pwcompie –importSchema mySchema.xml –preview –d myPWDatasource –u myUserName –p myPassword

Exporting an entire schema to a datasource

pwcompie –exportSchema mySchema.xml –datasource myPWDatasource –user myUserName

Since the ProjectWise password option is not included, the user will be prompted to enter it.

Exporting an entire schema to a URI

pwcompie –exportSchema mySchema.xml –ecSchemaURI MyCompany.BusinessDomainName –ecPrefix myc

Since the ProjectWise datasource, user name, and password options are not included, the user will be prompted to enter them.

Instructions File Format

The ECXML instructions file is used to define the data to be exported from a specified datasource.

Instructions file contents

<PWComponentsImportExportInstructions>

     <ExportInstructions>

          <IncludeSchema>
               <Class name=string, includeParents="yes"
                or "no", includeChildren="yes" or "no",
                includeAddons="yes" or "no", 
                includeLinkedClasses="yes" or "no" />
               <CustomFolder name=string, 
                includeClasses="yes" or "no", 
                includeLinkClasses="yes" or "no" />
               <AllClasses/>
               <AllCustomFolders/>
               <AllApplications/>
               <AllFunctions/>
               <AllRules/>
          </IncludeSchema>

          <IncludeInstances> (can contain one or more 
           of the following elements)
               <BySearch className=string, 
               [where=string],
                includeInstancesOfChildClasses="yes"
                or "no" />
               <BySavedSearch searchName=string />
               <AllInstancesOfExportedClasses />
               <AllInstances/>
          </IncludeInstances>

     </ExportInstructions>

     <SpecialHandlingInstructions> (can contain one
      or more of the following elements)
          <SpecialAttribute name=string, type="ATTRIBUTEID" 
           or "CLASSID" or "DOCUMENTID" or "GROUPID"
           or "INSTANCEID" or "PROJECTID" or 
           "USERID" />
     </SpecialHandlingInstructions>

</PWComponentsImportExportInstructions>

Instructions file elements

The table describes the elements that may be used in an instructions file, as well as the attributes that are required for each element.

Element	Description	Attributes
<IncludeSchema> element and associated child elements (for example, <Class>, <CustomFolder>)	Define which parts of the schema will be exported.	-
<Class>	Defines which classes of a schema will be exported.	name — Name of the class to be exported includeParents — Indicates whether associated parent classes are to be exported. includeChildren — Indicates whether associated child classes are to be exported includeAddons — Indicates whether associated add-on classes are to be exported. includeLinkedClasses — Indicates whether associated linked classes are to be exported.
<CustomFolder>	Defines which custom folders are to be exported.	name — Name of the custom folder to be exported includeClasses — Indicates whether classes referenced by relational searches or linked classes used in the custom folder are to be exported. includeLinkClasses — Indicates whether the linked classes used in the custom folder are to be exported.
<AllClasses>	Specifies that all classes in the schema are to be exported.	-
<AllCustomFolders>	Specifies that all custom folders in the schema are to be exported.	-
<All Applications>	Specifies that all applications associated with the schema are to be exported. (Typically used with Bentley Facilities Planner schemas.)	-
<All Functions>	Specifies that all functions associated with the schema are to be exported. (Typically used with Bentley Facilities Planner schemas.)	-
<AllRules>	Specifies that all rules associated with the schema are to be exported. (Typically used with Bentley Facilities Planner schemas.)	-
<IncludeInstances> and associated child elements (for example, <BySearch>, <BySavedSearch>)	Defines the instance data to be exported.	-
<BySearch>	Specifies that all objects returned by all searches referencing a specific class are to be exported. For example: `<BySearch className="EQUIP" where '@"EQUIP_TYPE"="PUMP"' includeInstancesOfChildClassses="no" />`	className — Name of the class referenced by searches. where — SQL expression. Any references to attribute names must be preceded by an '@' . includeInstancesOfChildClasses — Indicates whether instances of child classes are also to be exported.
<BySavedSearch>	Specifies that all objects returned by a specific search are to be exported.	searchName — Name of the search.
<AllInstancesOfExportedClasses>	Specifies that all instances of all classes being exported (as defined using <IncludeSchema>) are to be exported.	-
<AllInstances>	Specifies that all instances are to be exported.	-
<SpecialHandlingInstructions> and associated <Special Attribute> child elements	Exports or imports internal identifiers (for example, attributes or classes) that are stored as instance data. The identifiers to be exported are identified by name and type. (Typically used with Bentley Facilities Planner schemas.)	name — Name of internal identifier to be exported. type — Type of identifier to be exported. Valid values include "ATTRIBUTEID", "CLASSID", "DOCUMENTID", "GROUPID", "INSTANCEID", "PROJECTID", or "USERID".

Instructions file example

<?xml version="1.0"?>
<PWComponentsImportExportInstructions 
xmlns:xsi="http://www.w3org/2001/XMLSchema-instance">
     <ExportInstructions>
          <IncludeSchema>
               <Class name="Component" 
                includeParents="yes" 
                includeChildren="yes" 
                includeLinkedClasses="yes" 
                includeAddons="no"/>
               <Class name="ComponentLink"
                includeParents="yes" 
                includeChildren="yes" 
                includeLinkedClasses="yes"
                includeAddons="no"/>
          </IncludeSchema>
     </ExportInstructions>
     <>
     <SpecialHandlingInstructions>
          <SpecialAttribute name="AA_ClassId" 
           type="CLASSID"/>
          <SpecialAttribute name="AG_ClassId" 
           type="CLASSID"/>
          <SpecialAttribute name="AQ_ClassId" 
           type="CLASSID"/>
          <SpecialAttribute name="AQI_ClassId" 
           type="CLASSID"/>
          <SpecialAttribute name="AQ_LinkClassId" 
           type="CLASSID"/>
          <SpecialAttribute name="AQ_LinkedClassId" 
           type="CLASSID"/>
          <SpecialAttribute name="Ods LinkClassId" 
           type="CLASSID"/>
          <SpecialAttribute name="Ods LinkFromClassId" 
           type="CLASSID"/>
          <SpecialAttribute name="Ods LinkToClassId" 
           type="CLASSID"/>
          <SpecialAttribute name="AQ_SpecLinkClass" 
           type="CLASSID"/>
          <SpecialAttribute name="A_ClassId" 
           type="CLASSID"/>
          <SpecialAttribute name="AA_AttributeId" 
           type="ATTRIBUTEID"/>
          <SpecialAttribute name="AQ_AttrId" 
           type="ATTRIBUTEID"/>
          <SpecialAttribute name="AG_AttributeId" 
           type="ATTRIBUTEID"/>
          <SpecialAttribute name="AQ_SpecAttrLinked" 
           type="ATTRIBUTEID"/>
          <SpecialAttribute name="AQ_SpecAttrMain" 
           type="ATTRIBUTEID"/>
          <SpecialAttribute name="AA_ProjectID" 
           type="PROJECTID"/>
          <SpecialAttribute name="AA_DocumentID" 
           type="DOCUMENTID"/>
          <SpecialAttribute name="AA_UserID" 
           type="USERID"/>
          <SpecialAttribute name="AQ_UserID" 
           type="USERID"/>
          <SpecialAttribute name="AQ_CommitBy" 
           type="USERID"/>
          <SpecialAttribute name="AA_Updater" 
           type="USERID"/>
          <SpecialAttribute name="AG_GroupId" 
           type="GROUPID"/>
          <SpecialAttribute name="AA_UniqId" 
           type="INSTANCEID"/>
          <SpecialAttribute name="AA_SymbologyId" 
           type="INSTANCEID"/>
          <SpecialAttribute name="AA_DisplayFilterId" 
           type="INSTANCEID"/>
          <SpecialAttribute name="Ods LinkToInstId" 
           type="INSTANCEID"/>
          <SpecialAttribute name="Ods LinkFromInstId" 
           type="INSTANCEID"/>
     </SpecialHandlingInstructions>
</PWComponentsImportExportInstructions>