im copyissue

CLI Reference > Workflows and Documents Commands > im copyissue

im copyissue

copies the common fields of an existing PTC RV&S issue to a new issue

Synopsis

im copyissue [--asOf=[date|label:label] [--[no]showWorkflow] [--[no]copyFields] [--copyFieldsList=field],field]] [--[no]link] [--linkToField=field]] [--addAttachment=value] [--addFieldValues=value] [--addRelationships=value] [--addSourceTrace=value] [--addSourceLink=value] [--type=type] [--field=value] [--richContentField=value] [--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]] issue

Description

im copyissue copies the common fields of an existing PTC RV&S issue to a new issue. This includes any attachments referenced in rich text fields. You can complete fields in the new issue, and add relationships and attachments. You can also use the im copyissue --link or the im copyissue --linkToField command to create a relationship between the source issue and the copied issue. To select an issue, use the -g or --gui option and PTC RV&S displays an issue selection dialog box.

For example,

im copyissue --link --type=Docs --asOf="January 8, 2007 10:00:00 AM EST" 123

creates a new Docs issue from issue 123, copying the content of the common fields as of January 8, 2008, and linking the new issue to the original issue through the Forward Relationship field.

Note the following:

• Your administrator can configure long text fields to support rich content. Rich content enhances the display of text in long text fields by adding formatted text, tables, background colors, images, and hyperlinks. From the CLI, rich content is applied using a limited set of HTML elements and attributes. For a complete list of supported elements and attributes, see the PTC RV&S Help Center.

• Your administrator defines which issue types and custom fields you are allowed to edit. If your administrator defines a field as a logging text field, you may only enter new text and not edit existing text.

• Displayed date fields do not change based on the time zone that a user is operating in; however, displayed date/time fields vary based on the time zone that a user is operating in.

• Relevance and editability rules are evaluated on the PTC RV&S Client’s time zone.

• Computed expressions return dates/times in the PTC RV&S Client’s time zone and perform calculations in the PTC RV&S Server’s time zone where appropriate.

• The list of users in the Assigned User field is limited to those with permissions to the issue’s project. The same applies to the Assigned Group field.

• Depending on your workflow, you may not be able to edit an issue that is in an end state.

• Your administrator may include the time in date fields. You can specify the time when you select a date from the calendar. Time is specified from 00:00:00 to 23:59:59 inclusive in 24 hour format; however, PTC RV&S displays the time in 12 hour format. For example, specifying 13:56:45 displays the time as 1:56:45 PM. If you do not specify a time, the current time displays in the date field.

• To retrieve metrics from a configuration management project related to the issue you are copying, your administrator may define a field that accepts a configuration management project as a value. Optionally, you can specify a checkpoint revision or development path. If you specify a configuration management project and a checkpoint, then save the issue, one or both of the following may occur when you view the issue in the GUI or Web interface:

◦ One or more computed expressions in the issue calculate specific metrics about the project, displaying the results as a read-only value in a computed field (the visibility of the computed field depends on the field’s relevance rules). For example, once you specify a project for the Source Code field, a Lines of Code field could calculate and display the number of lines of code in that project. As lines of code are added or removed from the project, the Lines of Codefield updates to display the new value.

◦ A metrics hyperlink displays in the configuration management project field. Clicking the hyperlink displays various configuration management metrics about the project.

In addition, the server and project information display in the configuration management project field as a hyperlink. Clicking on the hyperlink displays the project in a Project view.

To select a configuration management project, you require the OpenProject permission for the specified project. Once a configuration management project has been specified, metrics can be obtained by any user with permissions to view the configuration management project field. For more information on selecting configuration management projects and viewing configuration management metrics, refer to the PTC RV&S Help Center. For more information on creating configuration management metrics, refer to the PTC RV&S Help Center.

Important:

Metrics are only maintained against project checkpoints; therefore, to generate metrics, you must specify a checkpoint when you specify the configuration management project.

• You cannot set a date field to null if the date has been previously set.

• You can modify a value from a mandatory field and save it.

• If your administrator has set up electronic signatures, you may need to provide your user name and password when making specific edits to an issue. For example, you could be required to provide an electronic signature when you change an issue’s state to Completed.

• By default, PTC RV&S allows file attachments to a maximum size of 4 MB and a maximum of 255 characters for file names. Your administrator may define a higher or lower limit depending on the requirements of your system. You can also attach more than one file to a single issue.

• Integer fields allow a maximum of nine digits and floating point fields allow a maximum of 15 digits. Your administrator can define default, minimum, and maximum values.

• If you attempt to save changes to an issue after another user saves changes to the same issue, the following error message may appear:

Could not save modified issue:The issue was changed by another user after you began your edit.

Typing Cancel discards your changes. Typing OK displays your unsaved changes to the issue. PTC recommends copying your changes, canceling the issue, then re-editing the issue and adding your changes.

• Copying an issue containing user, group or project fields with inactive values results in an error message.

• Inactive pick list values cannot be specified for pick list fields; however, pick list fields retain inactive pick list values. If you edit a multi-valued pick list field, inactive pick list values can no longer be specified, even if only one of the values was previously inactive.

• If an issue contains multi-valued user or group fields with inactive values, editing the inactive values and saving the issue prompts you to leave the fields unchanged or clear the inactive values.

Options

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

• --asOf=[date|label:label]

allows you to copy an issue as of an historical date or label. This option is used with the --issues option. If a value is not provided the issue is copied as of the server's current time. This field is optional.

• --[no]showWorkflow

specifies whether to display the workflow for the issue type, if your administrator has enabled it. This option can only be specified with -g or --gui. Viewing the Workflow panel is useful for determining where you can progress in the workflow. The Workflow panel displays the complete workflow for the issue type, unvisited states, visited states, the current state, other state transitions, and phases, as indicated by the Legend.

• --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] ".

• 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] ".

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

• --[no]copyFields

specifies whether to copy the common fields of the specified issue to the new issue. Common fields refer to fields that are visible for both the original and new issue types and editable for the new issue type. The default is to copy common fields.

• --copyFieldsList

specifies which common fields to copy to the new issue. Only fields that are visible for both the original and new issue types and editable for the new issue type can be copied. The default is to copy the common fields that were specified by your administrator.

• --[no]link

specifies whether to link the new issue to the Forward Relationships field on the source issue. The ID of the source issue appears in the Backward Relationships field on the new issue.

Your administrator determines which issue types can be linked to other issues.

• --linkToField=field

specifies the relationship field on the source issue to use to link to the newly created issue. The ID of the new issue appears in the specified field.

Your administrator defines relationship fields and determines which issue types can be linked to other issues.

• --addAttachment=value

adds attachments, where value is of the form "field=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 issue 123""

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

If you do not specify the name of the attachment, the file name is used as the attachment name. You can use this option multiple times to specify multiple attachments. An issue cannot have more than one attachment with the same name.

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

• --addFieldValues=value

specifies new field values to add, where value is of the form "fieldName=fieldValue."

This option is only valid for the following multi-valued field types: pick, user, group, item backed picklist (IBPL), and relationship.

• --addRelationships=value

specifies a relationship field, the ID of the related issue, and any relationship flag for the related issue, where value is of the form [fieldName:]id[relationshipFlags][,...]. Use commas to specify more than one issue ID, for example, 23, 242 If no fieldName is specified, the Forward Relationships field is used.

This option is deprecated. Instead, use the --addFieldValues=value option.

• --type=type

specifies the issue type to create. Your administrator defines issue types. This option is mandatory.

• --field=value

specifies a field and its value for the new issue, 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 the issue.

• --richContentField=value

specifies a rich content field and its value for the new issue, 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>".

• issue

specifies the ID of the issue you want copy.