CLI Reference > Workflows and Documents Commands > im createissue
 
im createissue
creates a new Integrity Lifecycle Manager issue
Synopsis
im createissue [--[no]showWorkflow] [--addAttachment=value] [--addFieldValues=value] [--addRelationships=value] [--addSourceTrace=value] [--addSourceLink=value] [--type=type] [--customFieldDefinition=value] [--customFieldValue=value] [--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]]
Description
You create an issue by providing issue data. You can also link the issue you are creating to another issue, or add an attachment to it.
For example,
im createissue --type=Docs --field="Type=Docs" --field="Summary=Update release notes" --description="Update content of release notes" --field="Assigned User=jriley" --field="Project=/Release 2.0"
creates a new Docs issue with the specified field values.
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.
The types of issues that you can create depend on the types created by your administrator. If there are no issue types to select, contact your administrator.
Text fields, such as Summary, support HTTP hyperlinks. This is useful if you want to include a link to a document on an internal or external Web site, such as a design document. You must include the
http:// prefix
.
If you can specify an issue type but not create it, contact your Integrity Lifecycle Manager administrator. The issue may contain a custom field defined to be both mandatory and invisible for this issue type.
If your administrator has set up electronic signatures, you may need to provide your user name and password when creating an issue.
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 creating, 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 PTC Integrity Lifecycle Manager User Guide. 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.
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 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.
Your administrator determines the types of issues that can have attachments. Attachment fields can display under Fields or Attachments, and can display in comma separated values or table display format, depending on how your administrator has defined the attachment field. This procedure is based on the following configuration: an attachment field in table display format under Attachments.
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.
Relationship fields can display under Fields or Relationships, and can display in comma separated values or table display format, depending on how your administrator has defined the relationship field. This procedure is based on the following configuration: a relationship field in table display format under Relationships.
Adding a related issue is only permitted if your Integrity Lifecycle Manager administrator has allowed relationships for the issue type.
To quantify numeric field values, your administrator may define display patterns for numeric fields, for example, as currency or percentages. In addition, a display pattern may format the value you initially enter in the numeric field, for example, an input value of 0.126 may display as 0.13 after you create the issue. For more information on display patterns, contact your administrator.
If a floating point field does not contain a display pattern, the field in the created issue displays the same number of decimal places as when the value was typed in the numeric field.
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.
Setting a user, group or project field to an inactive value results in an error message.
Options
This command takes the universal options available to im commands, as well as some general options. See the options reference page for descriptions.
--[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.
--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
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 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.
--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.
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).
To specify a Parameters field, use the following format:
<Parameter Name =<Parameter Type <Parameter Name ;values=<Parameter Values <Parameter Name ;description=<Description
To specify a Parameter Values field, use the following format:
<Parameter Name =<Parameter Value <Parameter Name [;locked]=true|false <Parameter Name [;description]=A textual description
The <Parameter Type
can be "String" or "Pick List". The "String" type does not have any parameter values. The "Pick List" type has a comma-separated list of values. The locked attribute is optional. If it is not specified the parameter value is not locked. If a parameter name contains a ":", ";" or "=" the character must be escaped. An entry with a given parameter name can only appear once. For more information on parameter fields, see the Integrity Lifecycle Manager Help Center.
--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>"
See Also
Commands: im copyissue, im editissue, im extractattachments, im viewissue
Miscellaneous: options