im importsegment

CLI Reference > Workflows and Documents Commands > im importsegment

im importsegment

creates one or more new segments from imported requirement information

Synopsis

Description

im importsegment creates one or more new segments from imported information. A segment can be a segment root or a subsegment. If importing as a subsegment, you can optionally add the segment at a specified location in the parent segment's structural relationship list. For example:

im importsegment --parentID=23 --insertLocation=after:34 --field='Project=Project2' --type='Subsegment' --field='Category=SubFolder'

creates a segment and inserts it after ID 34 in the structural relationship list for parent segment 23

im importsegment --field='Project=/Project2' --field='Category=Document' 241 245 243

creates a segment using the default type and adds children with IDs 241, 245 and 243 beneath it.

This command is normally used with an API.

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.

• --subInsertMode=[reference:include]

specifies how subdocuments are inserted when segments are imported into a document.

Referenceinserts a subdocument but the document contents are not visible in the tree structure; the subdocument must be opened in order to manage its contents.

Includeexposes the entire contents of the subdocument as if they were a sequential part of the parent document. You can only reference or include all subdocuments at the same time. The default is Reference.

For example:

im importsegment --type=Segment --field='Project=/Document' --field='Shared Category=Document' --subInsertMode=include --parentId=55 56

results in the newly created document 57 being imported as a reference underneath 551, and 562 being inserted as an inclusion beneath the newly created document.

• --field=value

specifies a field and its value, where value is of the form "fieldName=fieldValue", for example, --field=Severity=Critical. If the field is multi-valued, value is of the form "fieldName=fieldValue,...".

To specify more than one field, specify this option for each field you want to add.

To specify a workflow and document project, project names must be preceded by a (/), for example,--field=Project=/testProject. A Windchill RV&S project is required.

To specify a configuration management project, use the following syntax: --field=fieldname,server=server,project=projectname, [devpath=devpath|revision=checkpointrevision]

• --addRelationships=value

adds related items to the segment, where value is of the form [FieldName]:ID[relationshipFlags][,...]. If no field name is specified, the Forward Relationships field is used.

Adding a related item is only permitted if your administrator has allowed relationships for the segment's item type.

• --addSourceTrace=value

adds a trace to a source file, where value is of the form "field=scmSourceFieldName,server=scmServerName,port=scmPortNumber,file=fileName,project=scmProjectName[,devpath=devpathName] [,projectRevision=revision][,start=startLineNumber][,end=endLineNumber]".

Note the following:

◦ If you specify a configuration path for project=scmProjectName then devpath=devpathName and projectRevision=revision cannot be specified.

◦ You cannot add the same source trace more than once. In order to be considered a new source trace, the trace must have a unique combination of the following attributes: member name, server name, server port, project, project revision, development path, revision, start line number, and end line number.

• --addSourceLink=value

adds a link to a source file, where value is of the form "field=scmSourceFieldName,revision=memberRevisionID, server=scmServerName,port=scmPortNumber,[file=fileName|subproject=subprojectName|isProject],project=scmProjectName[,devpath=devpathName][,projectRevision=revision] [,start=startLineNumber][,end=endLineNumber]".

Note the following:

◦ If you specify a configuration path for project=scmProjectName then devpath=devpathName and projectRevision=revision cannot be specified.

◦ You cannot add the same source link more than once. In order to be considered a new source link, the link must have a unique combination of the following attributes: member name, server name, server port, project, project revision, development path, revision, start line number, and end line number.

• --richContentField=value

specifies a rich content field and its value for the segment, where value is of the form "richcontentfieldname=fieldValue".

To specify a link to an item by ID: <a href="mks:///item?itemid=ID">DisplayText</a>

For example:

<a href="mks:///item?itemid=4547">Part Requirement</a>

To specify a link to an item by ID and label: <a href="mks:///item?itemid=ID&label=LABEL">DisplayText</a>

For example:

<a href="mks:///item?itemid=4547&label=EDF-343">Part Requirement, Label EDF-343</a>

To specify a link to an item by ID and revision: <a href="mks:///item?itemid=ID&revision=REVISION">DisplayText</a>

For example:

<a href="mks:///item?itemid=4547&revision=1.2">Part Requirement, Revision 1.2</a>

To specify a link to an item by ID and date: <a href="mks:///item?itemid=ID&asof=DATETIME">DisplayText</a> where date is in the format for your locale; such as US date formats "mm/dd/yy", "mm/dd/yyyy", or "mmm d, yyyy" with the time "h:mm:ss a".

For example:

<a href="mks:///item?itemid=4547&asof=03/25/2012 12:04:00 AM">Part Requirement, March 25, 2012 12:04am</a>

In the korn shell command line interface, HTML tags must be surrounded by quotes, for example, "b>Feature Overview/b>". In the Windows command line interface (cmd.exe), the ^ escape character must precede the and > characters in HTML tags, for example, ^b^>Feature Overview^/b^>. You may need to escape nested " characters, for example,

--richContentField=Description="<a href=\"mks:///item?itemid=4547\">Part Requirement</a>"

• --addAttachment=value

• adds attachments to the segment, where value is of the form "fieldName,path=pathToFile[,name=nameOfAttachment][,summary=shortDescription] " .

The "pathToFile" must include the path and filename. The "nameOfAttachment" is optional, and gives the attachment a different name than the name of the file specified in "pathToFile".

For example,

addAttachment="field=Attachments,path=c:/temp/notes.txt,name=notes123.txt,summary="Notes for item 123""

adds the existing notes.txt file as an attachment with the name of notes123.txt.

Attachment size limits are set by your administrator. The default attachment size limit is 4 MB.

--type=type

specifies the item type of the segment. Your administrator defines item types. This option is required if more than one segment type is allowed in the solution and the type field is not specified.

--parentID=value

the ID of the parent segment that will contain the reference to the segment being imported. The parent item must be a segment or a node. This option is required.

--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.

--insertMode=[reference|include]

indicates the way content related to the segment should be be imported. This option is required if you specify a --parentID. The options are as follows:

reference references related items but does not include them.

include includes related items as children of the parent item.

segment id...

the ID(s) of previously created segment(s) that you want to import the segment(s) into. Use a space separated list to specify more than one segment, for example, 240 241 242.