im branchsegment

CLI Reference > Workflows and Documents Commands > im branchsegment

im branchsegment

branches a segment

Synopsis

Description

im branchsegment branches a segment. A segment can be a document root or a subsegment. Branching creates a copy of the segment and adds it to the project history. You can branch a segment as of a specific date or label. For example:

im branchsegment --asOf="January 8, 2012 10:00:00 AM EST" 123

branches segment 123 as of January 8, 2012.

For more information on branching, see the Windchill RV&S Help Center.

Options

This command takes the universal options available to all im commands, as well as some general options. See the options reference page for descriptions.

• --asOf=<date>:label:<label>

allows you to branch the segment as of a specific date or label.

If a value is not provided, the segment is branched as of the server's current time. This field is optional.

• --project=project

the project you want to assign the branched segment to.

To restrict access to specific information in documents, all documents are subject to visibility rules set by your administrator. You must have visibility to the project you want to assign the branched segment to. For more information, contact your administrator.

• --[no]subSegment

branches the subsegment if the selected node references a subsegment.

• --[no|ignore]recurseInclude

◦ --recurseInclude

copies all included documents from the segment into the branched document.

A new copy of included documents is created from the segment. If you use this option in conjunction with filterQueryDefinition or filterQueryDefinitionFile, the specified filter criteria is applied on the included documents in the branched document that is created.

◦ --norecurseInclude

This is the default option.

References existing included documents from the input document.

If you use this option the specified filter criteria is not applied on the included documents in the branched document.

◦ --ignorerecurseInclude

The branched document will not have any included documents from the input document.

You must use this option in conjunction with filterQueryDefinition or filterQueryDefinitionFile option.

• --[no|ignore]recurseReference

◦ --recurseReference

copies all inserted documents from the segment into the branched document.

A new copy of inserted documents is created from the segment. If you use this option in conjunction with filterQueryDefinition or filterQueryDefinitionFile, the specified filter criteria is applied on the inserted documents in the branched document that is created.

◦ --norecurseReference

This is the default option.

References existing inserted documents from the input document.

If you use this option the specified filter criteria is not applied on the inserted documents in the branched document.

◦ --ignorerecurseReference

The branched document will not have any inserted documents from the input document.

You must use this option in conjunction with filterQueryDefinition or filterQueryDefinitionFile option.

• --[no]swap

specifies to branch the referenced subsegment instead of the owning segment and swaps in the new branch. Specified with --subSegment. The default value is --noswap.

• --filterQueryDefinition=value

specifies a criteria or query definition rule to filter the contents of a document.

The specified filtering criteria is applied to all nodes in the branched document. To apply filtering criteria to included and inserted subsegment nodes, you must use the recurseInclude and recurseReference options.

The filter query definition uses the same format as the --queryDefinition option for the im createquery command. See the im createquery reference page for details.

• --filterQueryDefinitionFile=value

specifies the name of the file that contains the filter query definition

The maximum supported size of a filter query definition file is 64 KB.

• --[no]includeContent

includes all content from the original segment.

When you specify --noincludeContent, no content is copied from the original segment. Only the segment's structure is copied.

You cannot use the--noincludeContent option with the --[no]recurseInclude or --[no]recruseReference options.

• --[no]includeHierarchicalContent

creates the branched document structure that includes or excludes parent and child nodes based on the specified filter criteria.

◦ --includeHierarchicalContent

This is the default option.

If any child node matches the specified filter criteria, all parent nodes up in the hierarchy irrespective of the matching condition are also included.

◦ --noincludeHierarchicalContent

When you specify --noincludeHierarchicalContent, child nodes matching filter criteria will be added in the branched document only if parent nodes up in the hierarchy match the filter criteria.

You must use this option in conjunction with filterQueryDefinition or filterQueryDefinitionFile option.

• --[no]branch

specifies how the nodes of the document are connected back to the nodes in the original document:

◦ If --nobranch is not specified, the newly created nodes have links back to the items that they were branched from. The node items also display Branched From in the item header. Each original node item displays the new item in the Branches field. The default is --branch if this option is not explicitly specified.

◦ If --nobranch is specified, the document is branched without any of the connections back to its original document. All of the newly created nodes are reference mode Author, and each node’s item header does not display Branched From. Each original node item does not display the new item in the Branches field.

• --[no|confirm]large

specifies to display a message to users confirming that they are copying a large number of content issues. The default is 50 and can be modified using the --threshold option.

A confirmation message displays by default when you run this command from the API. You must specify --noconfirmlarge if you want the command to complete.

• --threshold=value

specifies the number of content issues to allow users to copy. The default threshold is 50. Users will be prompted to confirm a copy operation of more than 50 issues. If you increase the default threshold, you can specify --[no]confirmLarge option to either notify users or bypass notification.

• --parentID=value

the ID of the parent segment that the segment will be added to. A parent ID is optional.

• --insertLocation[=number|first|last|before:name|after:name]

determines where the segment should go in the parent segment's structural relationship list. You must specify a --parentID. The options are as follows:

first inserts the segment at the beginning of the list.

last inserts the segment at the end of the list.

before:name inserts the segment before the specified ID.

after:name inserts the segment after the specified ID.

[0,...] inserts the segment at the specified location. If a negative is specified, the segment is inserted at the beginning of the list. If the number specified is too large, the segment is inserted at the end of the list. The default insert location is last in the structural relationship list.

• segment id...

the ID of the segment and/or node you want to branch. To branch a subsegment you must specify --subsegment. The ID for a versioned document can also be specified, for example 99131–1.0. The ID for a versioned node cannot be specified because that node can be a member of multiple versioned documents.

To restrict access to specific information in documents, all documents are subject to visibility rules set by your administrator. You must have visibility to the segment and/or node you want to branch. For more information, contact your administrator.