im editissue

CLI Reference > Workflows and Documents Commands > im editissue

im editissue

edits an existing Integrity Lifecycle Manager issue

Synopsis

im editissue [--[no]showWorkflow] [--[no]batchEdit] [--query=[user:]query] [--removeAttachment=value] [--removeFieldValues=value] [--removeRelationships=value] [--addAttachment=value] [--addFieldValues=value] [--updateAttachment=value] [--addRelationships=value] [--addSourceTrace=value] [--addSourceLink=value] [--removeSourceTrace=value] [--removeSourceLink=value] [--customFieldDefinition=value] [--customFieldValue=value] [--removeCustomFieldDefinition=name] [--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 id...

Description

You can edit and update issues, depending upon the permissions assigned to you by your administrator.

You would need to edit an issue if, for example, someone on your project team assigned an issue to you, making you responsible for performing some action; or if you were responsible for reviewing all new submissions and assigning them to other team members.

When you use the -g or --gui option, Integrity Lifecycle Manager 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 Integrity Lifecycle Manager Client GUI.

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 Integrity Lifecycle Manager 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.

• You cannot edit historical versions of issues.

• Relevance and editability rules are evaluated on the Integrity Lifecycle Manager Client’s time zone.

• Computed expressions return dates/times in the Integrity Lifecycle Manager Client’s time zone and perform calculations in the Integrity Lifecycle Manager 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, Integrity Lifecycle Manager 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 editing, 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 Code field 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 Integrity Lifecycle Manager Help Center. For more information on creating configuration management metrics, refer to the Integrity Lifecycle Manager 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.

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

• By default, Integrity Lifecycle Manager 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.

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

• Setting a user, group or project field to an inactive value 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.

For example,

im editissue --query="Deferred Release 2.0 Features" --field=Project:/"Release 3.0"

edits all issues returned by the Deferred Release 2.0 Features query to change the Project field to Release 3.0.

Options

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

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

• --updateAttachment=value

updates information for an existing attachment, where value is of the form "[field=fieldName,path=pathToFile[,name=nameOfAttachment][,summary=shortDescription]]".

Note the following:

• If there are no differences in the updated attachment, the existing attachment is not updated.

• If the specified attachment does not exist, it is added to the item.

• If the updated attachment exists, but there are differences, the existing attachment is removed and the new attachment is added.

• The comparison of attachments is based on a message dialog algorithm (MD5) which relies on a checksum to calculate and compare the size of the attachment files. This comparison method is not guaranteed to work in all cases and it is possible to have collisions between two different attachments that are identical in size. While such collisions are rare, to avoid any possibility of collisions when using the im editissue\u00a0command, you can manually update the attachments using the --addAttachment\u00a0and --removeAttachment\u00a0command options.

• --addRelationships=value

adds related issues, where value is of the form [FieldName]:IssueID[relationshipFlags][,...].If no field name is specified, the Forward Relationships field is used. Adding a related issue is only permitted if your administrator has allowed relationships for the issue type.

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

• --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 are specifying a variant or build project for project=scmProjectName use a keyword string. For build projects, make sure you specify the build keyword (#b=) immediately after the top level project keyword (#). For more information on keyword strings, see the description for --project=project under general options on the options reference page.

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

• --[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, and other state transitions, as indicated by the Legend.

• --[no]batchEdit

specifies whether to edit multiple issues as one operation, or to edit each issue individually.

--batchEdit edits multiple issues as one operation and saves the changes only after all the issues are edited.

--nobatchEdit edits and saves the changes to each issue individually.

You cannot perform the following edits in a batch edit:

• remove attachments

• add or remove source links (or source traces from a source link field with trace enabled)

• --field=value

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

To specify an Integrity Lifecycle Manager project, project names must be preceded by a (/), for example, --field=Project=/testProject.

To specify a configuration management project, use the following syntax: --field=field-name=server=server:port: :project=projectname/project.pj::(devpath=devpath|revision=checkpoint-revision).

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

• --query=[user:]query

specifies the name of a query to populate the issue selection, for example, "Cosmos Critical Defects". All issues returned in the query are selected for editing. If any issues are specified, the --query option is ignored).

Integrity Lifecycle Manager initially assumes that text before the colon (:) is a user name and text after it is a query name. If Integrity Lifecycle Manager fails to find a matching user name and query name, it searches for a query name matching the exact text. For example, if you type jhoyt:CosmosDefects, Integrity Lifecycle Manager searches for the query named CosmosDefects created by jhoyt. If Integrity Lifecycle Manager cannot find the query and/or user, it searches for the query named jhoyt:CosmosDefects created by any user.

• --removeAttachment=value

removes attachments, where value is of the form "[field=fieldName,name=nameOfAttachment]".If no attachment field is specified the default Attachments field is used.

• --removeFieldValues=value

specifies existing field values to remove, 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.

• --removeRelationships=value

removes related issues, where value is of the form [fieldName:]id[,...]. If no field name is specified, the Forward Relationships field is used.

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

• --removeSourceTrace=value

removes 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:

• You can specify the configuration path for project=scmProjectName using a keyword string. For more information on specifying project paths using a keyword string, see the description for --project=project under general options on the options reference page.

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

• --removeSourceLink=value

• removes a link to a source file, where value is of the form "field=scmSourceFieldName,server=scmServerName,port=scmPortNumber, revision=memberRevisionID, [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.

• issue id...

specifies the ID of the issue you want to edit. Use spaces to specify more than one issue, for example 3423. This option must be used if a query is not used to select issues for editing. This selection overrides the --query option.

If document versioning is enabled, you can also specify versioned items. To type the ID of a versioned item, use the format Live Item ID-major.minor, for example, 184-1.2.