im viewsegment
displays a segment in the Document view
Synopsis
im viewsegment [--[no]applyDisplayPattern] [--asOf=[<date>|label:<label>] [--[no]displayOutline] [--fields=field[:width[:rich|plain]],field[:width[:rich|plain]],...] [--filterRule=value] [--filterRuleFile=value] [--filterQueryDefinition=value] [--filterQueryDefinitionFile=value] [--[no]linkWithTable] [--perspective] [--[no]recurseInclude] [--[no]recurseReference] [--sessionID=value] [--[no]showParentage] [--[no]displayOutline] [--[no]showTallRows] [--[no]inlineEditMode] [--currentContext=value] [--focusIssueID=value] [--expandLevel=value] [--outlineColumns=field[:width[:rich|plain]],field[:width[:rich|plain]],...] [--structureFieldIconDisplayField=field] ][--structureFieldDisplayFormat=value] [--outlineItemFormat=value] [--outlineIconField=field] [--outlineItemFormat=value] [--[no]substituteParams] [--hostname=value] [--port=value] [--password=value] [--user=value] [(-?|--usage)] [(-g|--gui)] [(-F value|--selectionFile=value)] [--quiet] [--settingsUI=[gui|default]] [--status=[none|gui|default]] [(-N|--no)] [(-Y|--yes)] [--[no]batch] [--cwd=value] [--forceConfirm=[yes|no]] [--height=value] [--width=value] [-x value] [-y value] issue id... [--[no]showEditPanel] [--[no]confirmSave] [--[no]showIssueView] [--[no]multiEditSession]
Description
im viewsegment displays a segment in the Document view. A segment can be a document root or a subsegment. If you specify the item ID of the reference to a subsegment, the Document View displays the parent document that contains the subsegment.
This command is only supported with the -g or --gui option. When you use the -g or --gui option, PTC RV&S displays an issue selection dialog box. If you browse for issues from the issue selection dialog box, any changes you make to the columns in the Issues View will not be applied to that view when it is accessed through the PTC RV&S Client GUI.
 |
Certain command options cannot be used with -g or --gui. These include --filterQueryDefinition, and --filterQueryDefinitionFile. These options are primarily useful for building integrations through the API.
|
Options
When calling the im viewsegment command using the API, you can use --filterRule or --filterQueryDefinition when you need to filter the content on the segment to be returned. For example:
• To provide a supplier with only the Technical Requirement content from a document, use:
--filterQueryDefinition=(field[Category]="Technical Requirement")
• To retrieve all document content nodes that were changed in the last two days, use:
--filterQueryDefinition=(field[Modified Date] in the last 2 days)
• To retrieve only Comment nodes where the most recent change was made by the user "Me", use:
--filterRule=((field[Category]="Comment") and field[Modified By]="me"))
When working with --filterRule and --filterQueryDefinition, note the following key considerations:
• The --filterRule and --filterQueryDefinition options have different rules for filtering content (see detailed descriptions of the two options below).
• The --filterQueryDefinition option always returns the top-most segment (that is, the segment that was passed as an argument to this command). The --filterRule option only returns the segment if it matches the specified filter.
• The im viewsegment command may perform better on larger documents when using --filterQueryDefinition, because only the partial or filtered document is retrieved from the repository. When using the --filterRule option, the complete document is retrieved from the repository and is then filtered.
For larger filter definitions, you can use the --filterRuleFile or --filterQueryDefinitionFile options. For further information on the available options, see the detailed descriptions that follow.
This command also takes the universal options available to im commands, as well as some general options. See the options reference page for descriptions.
• --filterRule=value
specifies a rule to filter the content when viewing the segment from the API.
A <rule> rule is defined as an <expression>
An <expression> is defined as one of the following:( <expression> and <expression> and <expression>)( <expr> or <expr> or <expr> )( <user op> )( <field> <operator> <value> )
where for users and groups:
<user op> rule is defined as a user is not a member of "<group>"<user op> rule is defined as a user is a member of "<group>"<value> rule is defined as a <field> | "<text>" | "<number>"<field> rule is defined as a field[<fieldname>]<fieldname> rule is defined as a ID | Summary | Priority | ...<group> rule is defined as a (everyone | im-dev | ...)<operator> rule is defined as a ( = | > | >= | <= | < | <> )<number> rule is defined as a ( .. | -1 | 0 | 1 | ..)
For example:
((field[Occurrences] > 4) and (field[Created By]="ProjectManager"))
When using --filterRule with the -g or --gui option, note the following:
◦ Field filters:
▪ For single expression with single field filter, the <expression> is converted into a field filter. For example, (field[Input Revision Date] in the last 30 days).
▪ For multiple expressions with and operations the (<expression> and <expression> and <expression>) is converted into multiple field filters. For example, ((field[Input Revision Date] in the last 30 days) and (field[Category]="Heading"))
|
|
OR operation is not supported.
|
This rule does not work for multiple criteria on same field. For example, (field[Input Revision Date]in the last 30 days) and (field[Input Revision Date] in the last 60 days)
◦ Advanced filters:
To convert an expression into advanced filter, user needs to specify extra brackets.
For example: (((field[Input Revision Date] in the last 30 days) or (field[Category]="Heading")))
• --filterRuleFile=value
specifies the name of the file that filters the content of the segment you are viewing.
• --filterQueryDefinition=value
specifies a query definition rule to filter the content when viewing the segment from the API. The filtering applies to all segment nodes, as well as to all included subsegment nodes. Filtering does not apply to the segment (that is, the segment is always returned in the API result whether or not it matches the filter query definition). This option is not valid from the CLI or GUI.
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.
|
|
To reference the original query in the new query so that any changes to the original query are reflected in the new query, define <subquery> as subquery[OriginalQuery].
|
• --filterQueryDefinitionFile=value
specifies the name of the file where the query definition is stored. You can use this option for larger filter query definitions. This option is not valid from the CLI or GUI.
• --perspective
specifies the perspective name to be applied.
|
|
A perspective is based on filter concept and is created using field filters and advanced filters. It offers a filtered view of the contents contained in a single document for which the perspective can be applied across the documents. Whereas, a cross-cutting perspective is created from contents added from various types of documents. A cross-cutting perspective can be shared with other users in the system.
|
|
|
--perspective works independently. This option cannot be used with --filterQueryDefinition, --filterRule, --filterRuleFile, --filterQueryDefinitionFile, and --fields.
|
• --[no]recurseInclude
specifies whether or not to display included subsegments for the segment in the tree pane. When a subsegment is included into the parent, the entire contents of the subsegment are exposed as if they were a sequential part of the parent.
• --[no]recurseReference
specifies to display referenced segments in the tree pane. When a subsegment is inserted into a parent segment, only the reference to the subsegment is exposed. You must open a subsegment to manage its contents.
• --sessionID=value
specifies the item ID of a test session. Including a test session ID provides a test session as context when viewing a document and counts as one of the layers in parameter substitution.
• --[no]showParentage
shows the parentage of the content in a filtered document. This option is only useful if a filter is enabled. By default, parentage is not shown. When enabled, all ancestors in the exported document are shown, from filtered items to the document root.
• --[no]substituteParams
specifies whether to replace parameter references in text fields with a parameter value. For more information on how parameter values are determined, see the PTC RV&S Help Center.
• --[no]displayOutline
specifies to display the Outline, a tree-like relationship hierarchy stemming from the segment you used to launch the view.
• --[no]linkWithTable
specifies that when a segment or node is selected in the Outline pane in the Document view, the same portion of the segment or node is highlighted in the tree pane.
• --outlineColumns=field[:width[rich|plain]],field[:width[rich|plain]],...
specifies the columns to display in the Outline.
• --[no]applyDisplayPattern
specifies whether to apply a display pattern to numeric fields. Display patterns are configured by your administrator and allow you to quantify integer and floating point field values, for example, as currency or percentages. --applyDisplayPattern is enabled by default.
|
|
If you use scripts, PTC recommends using the --noapplyDisplayPattern option to avoid being impacted by administrative changes to display patterns.
|
• --asOf=[<date>|label:<label>]
specifies the date to use for the segment. To specify a date and time, type MM/dd/yyyy h:mm:ss [AM|PM]. To specify the current date, type today. To specify the current date and time, type now. All segment content included in the view is as of the date and time specified.
• --fields=field[:width[:rich|plain]],field[:width[:rich|plain]],...]
specifies the fields, and their respective widths, to display in the Document view. Your administrator defines the available fields. Fields can include ID, Type, Assigned User, Assigned Group, Summary, and others. Use commas to specify more than one field.
• --focusIssueID=value
specifies the item ID to highlight in the tree pane when the segment displays. This colour is defined in the View > Options dialog in the context of the Document view.
• --expandLevel=value
specifies to expand the nodes to a specified level, for example, 1, 2, 3. The default is one.
• --outlineColumns=field[:width[:rich|plain]],field[:width[:rich|plain]],...]
specifies the fields, and their respective widths, to display in the outline pane of the Document view. Your administrator defines the available fields. Fields can include ID, Type, Assigned User, Assigned Group, Summary, and others. Use commas to specify more than one field.
• --currentContext=value
specifies the current task context in the Document view columns. If the value for --currentContext is not a valid context, it is ignored and the default task context will be used.
• --[no]inlineEditMode
enables inline editing. You can edit issue fields from the Document view fields without requiring the Item > Edit command or its subsequent dialog box.
• --[no]showTallRows
allows you to expand the height of a row to fit the data in the columns.
• --structureFieldDisplayFormat=value
specifies the fields and style that should be displayed for the tree nodes.
Defines an output format for user-formatted text. The default formatting is suitable for interpretation by most users; the various formatting options are provided for programmatic control.
Uses the same values as --fields, but similar to a JAVA Message Format string (that is, it requires { } to surround each field). For example:
im viewsegment --structureFieldDisplayFormat="{ID},{Summary}"
• --structureFieldIconDisplayField=field
specifies the field from which the icon is taken. This is the icon that will be displayed for each node in the Outline pane.
• --[no]substituteParams
specifies whether to replace parameter references in text fields with a parameter value. For more information on how parameter values are determined, see the PTC RV&S Help Center.
• issue id...
specifies the ID of the issue of the segment you want to view. Use spaces to specify more than one issue, for example 34 23.
If document versioning is enabled, you can also specify versioned documents. To type the ID of a versioned document, use the format Live Item ID-major.minor, for example, 184-1.2.
|
|
For versioned documents, referencing a content node ID is not supported for the im viewsegment command. When specifying a document version, the ID must refer to a segment or document. In addition, you can only view a versioned document in the PTC RV&S Client GUI.
|
• --[no]showEditPanel
specifies whether to show the embedded item edit panel. This option can be used in conjunction with the --[no]showIssueView option. If conflicts arise, the--[no]showEditPanel option always wins.
• --[no]confirmSave
specifies whether to prompt you to confirm changes are to be saved. This turns on and off whether you a confirmation window opens when you save in this view.
• --[no]showIssueView
specifies whether to show the embedded item view. This option can be used in conjunction with the --[no]showEditPanel option. If conflicts arise, the --[no]showEditPanel option always wins.
• --[no]multiEditSession
specifies whether to use single-row editing or multiple-row editing in the Document view.
See Also
• Commands: im createsegment