Creating a Spec XML File
The business administration change promotion spec file is a mechanism that enables you to define criteria to select administrative objects at a macro level to be exported using an XML file. For example, you can specify a filter criterion to export only those profiles that are from a specific organization or context, or export policy access control rules for a given principal only, and so on. The BACSpec.xsd file contains the rules and constraints that are applicable while creating a spec file. The BACSpec.xsd file is located at <Windchill_Home>\prog_examples\BAC\schema. Filtering objects using a spec file is supported on both synchronized and selective modes. The subsequent sections in this topic describe the element structure and related information to be used in a spec file for each object along with sample spec XML code. In addition, some sample spec files for each type of object are provided for reference at <Windchill_Home>\prog_examples\BAC.
Use the -s or --objectType option in the export command to upload and process the spec XML file. The -s or --objectType option is available only if you have set the com.ptc.windchill.bac.features.enabled property in wt.properties to 2666518. Without this configuration, any attempt to upload a spec file will be rejected with an error. This option is available for both selective and synchronized modes.
In addition to using identity attributes of an object as filter criteria, you can use the GlobalContainerCriteria tag in the spec file to filter objects at a container level. See the Global Container Criteria section in this topic for more details.
Each object type in the system supports only a specific set of filter criteria. While creating the spec file, make sure that the criteria you have provided are valid for that object type. For example, for policy access control rules, name is not a supported filter criterion. So you cannot export policy access rules based on name. Similarly, life cycle state or type ID are not supported filter criteria for profiles. The following sections provide details on the various elements that can be used for each object type while creating a business administrative change promotion spec file.
The string values specified for an element, subelement, or attribute in the spec file are case sensitive.
Profile
The spec file allows you to filter Profiles on the basis of the name of the profiles from a specific organization container or the exchange container. This section describes the XML elements that can be used to filter objects by profiles in selective mode systems. The profile schema contains the following elements:
Element | Description |
ExchangeContainer | Use this element to filter profiles that were created at the site level. Only one instance of this tag is allowed in the spec XML file. |
Organization | Specify the name of the organization. For example, PTC. |
name | Specify the name of the profile. For example, Profile1. |
You can create a spec XML file to select all profiles named Profile1 in either ExchangeContainer or PTC organization as shown below:
Object Initialization Rule
This section describes the XML elements used to filter and export object initialization rule (OIR) records in selective mode systems. Only TypeBasedRule elements are supported for OIR. You can filter OIRs on the basis of the name of an OIR from a specific organization container, application container, the exchange container, or object type. The following elements are contained in the OIR schema:
Element | Subelement | Attribute | Description |
ExchangeContainer | – | – | Use this element to filter OIRs that were created at the site level. Only one instance of this tag is allowed in the spec XML file. |
AppContainer | – | type | Specify the type of application container. Valid values are Project, Product, or Library. This is a required attribute for AppContainer. |
– | name | Specify the name of the application container. This is a required attribute for AppContainer. |
– | orgName | Specify the name of the organization within the application container. For example, PTC. This is a required attribute for AppContainer. |
Organization | – | name | Specify the name of the organization. For example, PTC. |
name | – | – | Specify the name of the OIR. For example, TestUser. |
objectType | – | – | Specify the internal name of the object. For example, wt.doc.WTDocument. The internal name for an object is available from the Type and Attribute Management utility. |
The following is a sample spec file to filter and export OIR records with names OIR-part-org, OIR-doc-org, and OIR-doc-prod1 from PTC organization and based on WTDocument as the object type:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BACSpec xmlns="http://www.ptc.com/bac">
<OIR>
<name>OIR-part-org</name>
<name>OIR-BACdocument-org</name>
<name>OIR-document-org</name>
<Organization name=”PTC”/>
<objectType>WCTYPE|wt.doc.WTDocument</objectType>
<objectType>WCTYPE|wt.doc.WTDocument|com.ptc.ptcnet.BACDocument</objectType>
</OIR>
</BACSpec>
Preference
This section describes the XML elements used to filter and export preferences in selective mode systems. The following elements are contained in the preference schema:
You can filter preferences on the basis of the type of containers, Windchill user, preference category, preference definition, and preference client.
Element | Subelement | Attribute | Description |
ExchangeContainer | – | – | Use this element to filter preference instances hat were created at the site level. Only one instance of this tag is allowed in the spec XML file. |
AppContainer | – | type | Specify the type of application container. Valid values are Project, Product, or Library. |
– | name | Specify the name of the application container. |
– | orgName | Specify the name of the organization. For example, PTC. |
Organization | – | name | Specify the name of the organization container. For example, PTC. |
User | – | – | Specify the name or ufid or email ID of a Windchill user or WTUser to filter and export the preference instance of a user. You must specify at least one of these values as filter criterion for WTUser in the spec file. |
excludeInstances | | | Use excludeInstances to specify whether you want to exclude any preference instance during the filtering of preferences. If you use excludeInstances only, then all preference instances will be excluded during the filtering process. For a more specific filtering, use the instanceType and visibility subelements as filter criteria. |
instanceType | – | Specify the type of instance to be excluded from the filtering of preferences. The valid values are as follows: • USER • CONTAINER • ORGANIZATION • SITE |
visibility | – | Specify the visibility setting values for which the preference instances need to be excluded. The valid values are as follows: • USER • CONTAINER • ORGANIZATION • SITE • HIDDEN • PRODUCT • PROJECT • LIBRARY • USERONLY • PRODUCT,PROJECT • PRODUCT,LIBRARY • PROJECT,LIBRARY • PRODUCT,PROJECT,LIBRARY |
Name | – | – | Specify the internal name of a preference definition. Use the getInternalNames command to obtain internal names. See getInternalNames for more information. |
CategoryName | – | – | Specify the internal name of a preference category. Use the getInternalNames command to obtain internal names. See getInternalNames for more information. |
ClientName | – | – | Specify the internal name of a preference client. Use the getInternalNames command to obtain internal names. See getInternalNames for more information. |
Container information, user information, and excludeInstances are mutually exclusive options for filtering preferences.
Sample spec file to filter and export a preference definition named Intro from the GOLF_CART application container under Test Organization. The spec file also specifies the filter criteria to export records of a preference named AAA from a preference client named Windchill and preference client named DEMO and exclude the filtering of preferences with hidden visibility in User and Container instances:
To obtain internal names—Specifying filter criteria on the basis of preference category, preference definition, and preference client requires you to provide the internal name of the preferences. Use the following command to obtain the internal names for preferences from a specific locale:
java wt.scm.client.SCMCMD getInternalNames getInternalNames [--user <user>] [--password <password>] [--outputdir <outputdir] [--locale <locale>] [--objectType <objectType] [--help]
Option | Required | Description |
-p --password | No | The password of the Windchill user running the command. |
-t --objectType | Yes | The object type whose internal names are to be obtained. Specify Preferences for this option. This option will be enhanced to support new object types in a future release. |
-u --user | No | The user name of the Windchill user running the command. The user running the command must be a valid Windchill user and a site administrator. |
-h --help | No | Use this option to display help text for the utility. The help text lists full descriptions of each option as well as the syntax for running the utility. |
-l --locale | No | The locale in which the output file is to be generated. If a locale is not specified, the output file is generated in the default locale. |
-o --outputdir | Yes | File path to the location where the CSV file is generated and saved. If this option is not specified, the files are saved to the default location in the Windchill temp directory ${wt.temp}/bac. |
On executing this command, a CSV report is generated and saved at the specified location. The CSV report provides information about the object type, internal name, and the display name in the locale that was specified in the command.
Policy Access Control Rule
The following elements are contained in the policy access control rule schema for selective mode systems:
You can filter policy access control rules on the basis of principal attributes for only selective mode systems. You can set the filter as a combination of principal elements with containers, domains, or only attributes.
When creating a spec file for policy access control rules for synchronized mode systems, specify only the object type. No other filter criteria are supported.
Element | Subelement | Attribute | Description |
Organization | name | – | Specify the name of the organization. For example, PTC. |
ExchangeContainer | – | – | Use this element to filter policy access control rules that were created at the site level. Only one instance of this tag is allowed in the spec XML file. |
AppContainer | – | type | Specify the type of application container. Valid values are Project, Product, or Library. This is a required attribute for AppContainer. |
– | name | Specify the name of the application container. This is a required attribute for AppContainer. |
– | orgName | Specify the name of the organization. For example, PTC. This is a required attribute for AppContainer. |
OrganizationDomains | name | – | Specify the name of the organization. For example, PTC. This is a required attribute for OrganizationDomains. |
path | – | Specify the file path or the folder location of the administrative domain for the defined object. This is a required attribute for OrganizationDomains. |
ExchangeContainerDomains | domain | path | Specify the administrative domain for the defined object. |
AppContainerDomains | – | type | Specify the type of application container. Valid values are Project, Product, or Library. This is a required attribute for AppContainerDomains. |
– | name | Specify the name of the application container. This is a required attribute for AppContainerDomains. |
– | orgName | Specify the name of the organization. For example, PTC. This is a required attribute for AppContainerDomains. |
domain | path | Specify the administrative domain for the defined object. This is a required attribute for AppContainerDomains. |
Principal | – | – | Specify the principals or participants. See the Principal section in this topic for details on the various sub elements and their corresponding attributes. |
typeid | – | – | Specify the type identifier of an object such as WTPart, WTDocument. For example: WCTYPE|com.ptc.windchill.bac.delivery.BACReceivedDelivery |
state | – | – | Specify a lifecycle state for the object type in upper case. |
allExceptPrincipal | – | – | Specify whether you want to collect principal objects. Valid values are true and false. |
The following is a sample spec file to filter and export all policy access control rules that have WTPart as type ID, with lifecycle state set to APPROVED, and where allExceptPrincipal is true.
The following is a sample spec file to filter and export all policy access control rules from System exchange container domain, Test Organization organization domain, and application container domains such as GOLF_CART, Test_Lib, and Test_Project.
The following is a sample spec file to filter and export all profiles from exchange container and Test Organization, and all policy access control rules from exchange container and application containers such as product, project and library.
The following is a sample spec file to export all profiles, object initialization rules, and policy access control rules from a synchronized mode system:
Lifecycle Template
This section describes the XML elements used to filter and export lifecycle template records in selective mode systems. You can filter lifecycle templates on the basis of the name of a lifecycle template from a specific organization container, application container, or the exchange container.
Consider the following guidelines while developing the spec file for lifecycle templates:
• You can propagate lifecycle templates that are only present in System Domain.
• You can propagate only the latest iteration of a lifecycle template. This is true even if the number of iterations of a lifecycle template varies on the source system and target system.
• When a delete action is propagated on the last iteration of a lifecycle template on the target system, this action automatically deletes the master too. This is true even if the latest iteration of the lifecycle template on the source system that was exported is the only iteration present in the target system.
• You can propagate delete action for lifecycle templates only if the matching Database Mapping and Local ID information are found in synchronized mode systems. In selective mode systems a matching Database Mapping must be found.
• Deletion of intermediate iterations of lifecycle templates is not supported. Only the latest iterations which match either by Database Mapping or Local ID information are deleted in respect to mode of exchange.
• When an iteration of a lifecycle template is deleted on the source system, during the export process, the deleted information of the iteration along with the available latest iteration in source system is propagated to the target system. This helps to synchronize the latest iteration in use on the target system.
• Filtering of lifecycle templates based on business identity for propagating delete action is not supported.
• Deletion of lifecycle templates that are in use by other objects is not supported.
The following elements are contained in the lifecycle template schema for selective mode systems:
Element | Subelement | Attribute | Description |
Name | – | – | Specify the name of the lifecycle template. |
ExchangeContainer | – | – | Use this element to filter lifecycle templates that were created at the site level. Only one instance of this tag is allowed in the spec XML file. |
AppContainer | – | type | Specify the type of application container. Valid values are Project, Product, or Library. This is a required attribute for AppContainer. |
– | name | Specify the name of the application container. This is a required attribute for AppContainer. |
– | orgName | Specify the name of the organization within the application container. For example, PTC. This is a required attribute for AppContainer. |
Organization | – | name | Specify the name of the organization. For example, PTC. |
The following is a sample spec file to filter and export all the lifecycle templates from the Exchange container and GOLF_CART product in Demo Organization:
The following is a sample spec file to filter and export all lifecycle templates named as Default in Demo Organization:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BACSpec xmlns="http://www.ptc.com/bac">
<LifeCycleTemplate>
<Organization name="Demo Organization"/>
<Name>Default</Name>
</LifeCycleTemplate>
</BACSpec>
The following is a sample spec file to filter and export all the lifecycle templates that are named as Basic and Default:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BACSpec xmlns="http://www.ptc.com/bac">
<LifeCycleTemplate>
<Name>Basic</Name>
<Name>Default</Name>
</LifeCycleTemplate>
</BACSpec>
Workflow Process Template
This section describes the XML elements used to filter and export workflow process template records in selective mode systems. You can filter workflow process templates on the basis of the name of a lifecycle template from a specific organization container, application container, or the exchange container.
Consider the following guidelines while developing the spec file for workflow process templates:
• You can propagate workflow process templates that are only present in System Domain.
• You can propagate only the latest iteration of a workflow process template. This is true even if the number of iterations of a workflow process template varies on the source system and target system.
• When a delete action is propagated on the last iteration of a workflow process template on the target system, this action automatically deletes the master too. This is true even if the latest iteration of the workflow process template on the source system that was exported is the only iteration present in the target system.
• You can propagate delete action for workflow process templates only if the matching Database Mapping and Local ID information are found in synchronized mode systems. In selective mode systems a matching Database Mapping must be found.
• Deletion of intermediate iterations of workflow process templates is not supported. Only the latest iterations which match either by Database Mapping or Local ID information are deleted in respect to mode of exchange.
• When an iteration of a workflow process template is deleted on the source system, during the export process, the deleted information of the iteration along with the available latest iteration in source system is propagated to the target system. This helps to synchronize the latest iteration in use on the target system.
• Filtering of workflow process templates based on business identity for propagating delete action is not supported.
• Deletion of workflow process templates which are used by other objects is not supported.
• Exchange of externalized workflow process template is not supported.
The following elements are contained in the workflow process template schema for selective mode systems:
Element | Subelement | Attribute | Description |
Name | – | – | Specify the name of the workflow process template. |
ExchangeContainer | – | – | Use this element to filter workflow process templates that were created at the site level. Only one instance of this tag is allowed in the spec XML file. |
AppContainer | – | type | Specify the type of application container. Valid values are Project, Product, or Library. This is a required attribute for AppContainer. |
– | name | Specify the name of the application container. This is a required attribute for AppContainer. |
– | orgName | Specify the name of the organization within the application container. For example, PTC. This is a required attribute for AppContainer. |
Organization | – | name | Specify the name of the organization. For example, PTC. |
The following is a sample spec file to filter and export all the workflow process templates from the Exchange container and GOLF_CART product in Demo Organization:
The following is a sample spec file to filter and export all the workflow process templates named as Submit in Demo Organization:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BACSpec xmlns="http://www.ptc.com/bac">
<WorkflowProcessTemplate>
<Organization name="Demo Organization"/>
<Name>Submit</Name>
</WorkflowProcessTemplate>
</BACSpec>
The following is a sample spec file to filter and export all the workflow process templates that are named as Review and Submit:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BACSpec xmlns="http://www.ptc.com/bac">
<WorkflowProcessTemplate>
<Name>Review</Name>
<Name>Submit</Name>
</WorkflowProcessTemplate>
</BACSpec>
Type Definition
The spec file allows you to filter and export Attribute template on the basis of the internal name of the type definition. Attribute template schema contains the following elements:
Element | Description |
Name | Specify the Internal name of the type definition. For Example, Name1. |
Namespace | Specify the Namespace of the type definition. For Example, Namespace1. | If there is no information to be provided for Namespace, do not include it in spec file. |
|
Flavor | Specify the Attribute template flavor of the type definition. For Example, LWCTYPE. |
The following is a sample spec file is used to filter and export attribute template:
Principal
You can create a spec file using one element or a combination of principal elements. If you use all the elements of principal in a spec file, the sequence of the elements in the schema must be in the order as shown in the following figure.
The following elements are contained in the principal schema:
• Role Principal
Represents the system groups that were created for roles assigned to team members in context teams and shared teams, and the system groups created in an application context representing the organizations that have members in the context team.
This element supports group name, group type, and container, which could be either exchange container or organization container, of a Windchill role or WTRoleprincipal. You must specify either exchange container or organization for WTRolePrincipal.
The following elements are contained in the WTRoleprincipal schema:
Element | Subelement | Attribute | Description |
groupname | | | Specify APPROVER as the name of the internal group. |
grouptype | | | Specify DynamicRole as the type of group to which the internal group belongs to. |
ExchangeContainer | – | – | Use this element to filter system groups that were created at the site level. Only one instance of this tag is allowed in the spec XML file. |
Organization | – | name | Specify the name of the organization. For example, PTC. |
The following is a sample spec file to filter and export all policy access control rules based on RolePrincipal from PTC organization:
The following is a sample spec file to filter and export all policy access control rules based on RolePrincipal from the exchange container:
• Group
Specifies the ufid or a combination of name and exchange container or organization container of a Windchill group or WTGroup.
The following elements are contained in the WTGroup schema:
Element | Subelement | Attribute | Description |
name | – | – | Specify the name of the group. For example, Administrator. |
Organization | – | – | Specify the name of the organization. For example, PTC. |
ExchangeContainer | domain | path | Use this element to filter groups that were created at the site level. Only one instance of this tag is allowed in the spec XML file. |
ufid | – | name | Specify the Unique Federation Identifier (UFID) of the object. The valid format for this parameter is: <ufid_string>|<ldap repository>|<ldap repository> |
The following is a sample spec file to filter and export all policy access control rules from the Administrator group from PTC organization, from exchange container, and a specific ufid:
The following is a sample spec file to filter and export all policy access control rules from all groups under the exchange container:
• Internal Group
These are groups that are not represented in the LDAP, but which are maintained internally by Windchill. For example, Library Creator.
The following elements are contained in the InternalGroup schema:
Element | Subelement | Attribute | Description |
groupname | | | Specify the name of an internal group. |
grouptype | | | Specify DynamicRole as the type of group to which the internal group belongs to. |
ExchangeContainer | – | – | Use this element to filter internal groups that were created at the site level. Only one instance of this tag is allowed in the spec XML file. |
Organization | – | name | Specify the name of the organization. For example, PTC. |
AppContainer | – | type | Specify the type of application container. Valid values are Project, Product, or Library. This is a required attribute for AppContainer. |
– | name | Specify the name of the application container. This is a required attribute for AppContainer. |
– | orgName | Specify the name of the organization. For example, PTC. This is a required attribute for AppContainer. |
The following is a sample spec file to filter and export all policy access control rules from the LIBRARY CREATOR group from PTC organization:
• WTUser
Specifies the name or ufid or email ID of a Windchill user or WTUser. You must specify at least one of these elements as filter criterion under WTUser in the spec file.
The following elements are contained in the WTUser schema:
Element | Description |
name | Specify the name of the user. For example, TestUser. |
emailid | Specify the email ID of the user. For example, testuser@ptc.com. |
ufid | Specify the Unique Federation Identifier (UFID) of the object. The valid format for this parameter is: <ufid_string>|<ldap repository>|<ldap repository> |
The following is a sample spec file to filter and export all policy access control rules based on the ufid:
The following is a sample spec file to filter and export all policy access control rules based on the email ID of a user named TestUser:
• WTOrganization
Specifies the name or ufid of a Windchill organization or WTOrganization. At least one of the elements is required in the spec file. You must specify at least one of the elements as filter criterion under WTOrganization in the spec file.
The following elements are contained in the WTOrganization schema:
Element | Description |
name | Specify the name of the organization. For example, PTC. |
ufid | Specify the Unique Federation Identifier (UFID) of the object. The valid format for this parameter is: <ufid_string>|<ldap repository>|<ldap repository> |
The following is a sample spec file to filter and export all policy access control rules from PTC organization and ufid:
• PseudoRole
Specifies the filter to collect objects based on pseudo roles.
The following elements are contained in the PseudoRole schema:
Element | Description |
name | Specify ALL or OWNER for this attribute where, • ALL is a pseudo role that is used by Windchill to represent all participants • OWNER is a pseudo role that is used by Windchill to represent the object owner |
The following is a sample spec file to filter and export all policy access control rules that have pseudo role set as ALL or OWNER:
The following is a sample spec file that references all the principal elements in the mandated sequence:
Global Container Criteria
Use GlobalContainerCriteria to specify a common container as a global filter criterion for all the object types specified in the spec file. Containers specified in GlobalContainerCriteria are additively applied to all object types in the spec file. Use of GlobalContainerCriteria in a spec file to import or export records is supported only on selective mode systems.
For example, to filter and export all profiles from PTC organization in GlobalContainerCriteria and exchange container, then all profile records from PTC and ExchangeContainer are fetched. Here is the sample XML for this example:
While creating a spec file using GlobalContainerCriteria, you must consider the following points:
• This element is at the first level immediately after the BACSpec root tag.
• This element is at the same level as object tags in the spec file.
• This element supports the following containers:
◦ Exchange container
◦ Organization container
◦ Application container
• Check whether the container you specify in GlobalContainerCriteria is valid for a given object type.
• For a granular search, specify a valid container within an administrative object. For example, application containers for policy access control rules.
| You cannot specify application container or domain with GlobalContainerCriteria for Profiles. |
• Use of domain as a child element within an object element is not supported. For example, you cannot specify domain under application container for policy access control rules.
The following is a sample spec file to filter and export all profiles in exchange container and policy access control rules from the Drive System application container under PTC organization:
