im createchart
creates a new chart
Synopsis
im createchart [--chartType=[Distribution|Trend|Issue Fields|Issue Fields Trend]] [--bgColor=value] [--chartFootnote=value] [--chartTitle=value] [--dataColors=value] [--descriptionFont=value] [--[no]displayDescription] [--[no]displayLegend] [--[no]displayLabels] [--endDate=value] [--fieldFilter=field=[value,value,...] [--fieldValues=value] [--footnoteFont=value] [--graphStyle=[VerticalBar|VerticalStackedBar|HorizontalBar|HorizontalStackedBar|Pie|Line|Table|XY|Bubble]] [--groupingValues=value] [--[no]is3D] [--[no]isAutoColors] [--[no]isShowZeroFieldCount] [--[no]isShowZeroGroupingCount] [--legendBgColor=value] [--legendPosition=[Right|Bottom|Left|Top]] [--xLabelRotation=[Horizontal|VerticalDown|VerticalUp|45Down|45Up]] [--legendTitle=value] [--outlineColor=value] [--projectedTrendExpressions=value] [--query=[user:]query] [--startDate=value] [--numberOfSteps=value] [--titleFont=value] [--trendStep=[Hour|Day|Week|Month|Quarter|Year]] [--[no]useIssueDefinedOrigin] [--[no]xReverse] [--[no]xShowGrid] [--[no]xShowTitle] [--yLabelRotation=[Horizontal|VerticalUp]] [--[no]yReverse] [--[no]yShowGrid] [--[no]yShowTitle] [--description=value] [--name=value] [--shareWith=u=user1[:modify],user2[:modify],...;g=group1[:modify],group2[:modify],...] [--sharedAdmin] [--computations=value] [--startDateField=field] [--runDateIsEndDate] [--[no]deltasOnly] [--issueIdentifier=value] [--[no]displayShapesForLineGraphs] [--[no]swapRowsAndColumns] [--[no]displayRowTotals] [--[no]displayColumnTotals] [--rangeDefinitions=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 can define and store any number of charts using Integrity Lifecycle Manager. A chart is a summary of data presented in a graphical format.
For more information on charts, refer to the Integrity Lifecycle Manager Help Center.
For example,
im createchart --name="Release 2.0 Docs Issues By User" --chartType=Distribution --query="Release 2.0 Docs Issues" --fieldValues="Assigned User=jriley,mchang" --groupingValues="State=In Progress"
creates a new chart showing the distribution of Release 2.0 Docs issues among the specified users.
Note the following:
• A chart can be edited by the user who created it. Principals (users and groups) that a chart is shared to can edit it if they have edit permissions assigned to them by the chart creator. A chart can only be deleted by the user who created it or by an administrator.
• The minimum information required to create a distribution chart is a chart name, a field, and a query. The minimum information required to create a trend chart is a chart name, step type, start and end date, and a field. The minimum information required to create an issue fields chart is a chart name, query, and aggregate expression. The minimum information required to create an issue fields trend chart is a chart name, query, step type, start and end date, and numeric field. All other modifications and additional information are optional.
• Charts can do more than just display field information in a graphical format. You can also perform arithmetic calculations between numeric fields, displaying the values in the chart. For example, you can calculate the average for a group of field values or count the number of issues in a specific state. To perform these calculations, you create a computed expression. For more information on the syntax, operators, functions, and operations applicable to computed expressions, see your administrator or the Integrity Lifecycle Manager Help Center.
• All charts are subject to visibility rules set by your administrator. Visibility rules restrict access to specific information based on project and/or issue type. For more information, see the Integrity Lifecycle Manager Help Center, or see your administrator.
• Symbolic dates in rules and queries are evaluated on the Integrity Lifecycle Manager Client’s time zone.
• 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.
For trend charts, the following are valid option combinations:
--startDate
--endDate
--startDate
--numberOfSteps (positive value)
--startDate
--runDateIsEndDate
--startDateField*
--numberOfSteps (positive value
--numberOfSteps (negative value)
--endDate
--numberOfSteps (negative value)
--runDateIsEndDate
*Only applies to Issue Fields Trend charts.
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.
• --chartType=[Distribution|Trend|Issue Fields|Issue Fields Trend]
specifies the chart type.
• --chartFootnote=value
specifies the footnote text of the chart.
• --chartTitle=value
specifies the title of the chart.
• --titleFont=value
specifies the font to be used for the chart title. Use the following format: name,style,size, where style is 0 for plain, 1 for bold, 2 for italic, and 3 for bold italic, for example, helvetica,1,10. When the chart is run, if the specified font cannot be found, Integrity Lifecycle Manager uses a substitute font.
• --descriptionFont=value
specifies the font to be used for the description. Use the following format: name,style,size format, where style is 0 for plain, 1 for bold and 2 for italic, for example, helvetica,1,10.
• --[no]displayDescription
specifies whether to display the chart description.
• --trendStep=[Hour|Day|Week|Month|Quarter|Year]
specifies the interval for each point on a trend or issue fields trend chart graph.
• --[no]useIssueDefinedOrigin
specifies whether to use the start date defined in an issue field for an issue fields trend chart.
• --startDate=value
specifies the start date for trend or issue fields trend charts. To specify a date and time, type MM/dd/yyyy h:mm:ss [AM|PM].
Other acceptable date formats include:
MM/dd/yyyy h:mm:ss a zMM/dd/yyyy h:mm:ss.SSS a zMM/dd/yyyy h:mm:ss aMM/dd/yyyy h:mm:ss.SSS aMM/dd/yyyy
• --endDate=value
specifies the end date for trend or issue fields trend charts. To specify a date and time, type MM/dd/yyyy h:mm:ss [AM|PM]. See the --startDate=value option for additional date and time formats.
• --description=value
specifies a short description for the chart.
• --name=value
specifies the new name of the chart. Names may be a maximum of 100 characters and cannot contain square brackets.
• --shareWith=u=user1[:modify],user2[:modify],...;g=group1[:modify],group2[:modify],...
specifies the users and groups that can use and modify the chart. Your administrator defines users and groups.
• --fieldFilter=field=[value,value,...]
specifies how field filters can be applied to the chart when it is run. The first component of the value is the field name. Currently, only project field filters are supported. The second component specifies the project(s) that you want to filter the chart data by when it is run. For example, --fieldFilter="Project=/Project1" filters for issues that have a value of Project1 in the Project field. If you do not specify a value, Integrity Lifecycle Manager filters for issues with a value of Unspecified in the Project field.
|
|
You can also define project filters for dashboards. Depending on how you design your dashboard, when a chart is run through a dashboard, the dashboard’s project filter can override the chart’s project filter.
|
• --fieldValues=value
specifies the field, field values and aliases used by the chart. For example: --fieldValues=Type=Documentation, Development[Feature Request, Bug] would include issues that have a Type field with a value of Documentation, Feature or Bug, with Feature and Bug types combined on the chart under the alias Development.
Use * to include all field values, and + to automatically include all future field values. For example: --fieldValues=Type=*, +, Development[Feature Request, Bug] would include all current values and any future values for the Type field, with Feature and Bug types combined on the chart under the alias Development.
For more information on specifying chart values, see the Integrity Lifecycle Manager Help Center.
• --footnoteFont=value
specifies the font to use for the footnote. Use the following format: name,style,size format, where style is 0 for plain, 1 for bold, 2 for italic, and 3 for bold italic, for example, helvetica,1,10.
• --groupingValues=value
specifies the field, field values, and aliases to use to group the data in the chart. For example: --groupingValues=State=Submit, In Work[In Progress, In Development] would group chart data into separate components for Submit and In Work, with In Work being a combination of the In Progress and In Development states.
Use * to include all field values, and + to automatically include all future field values. For example: --groupingValues=State=*, +, In Work[In Progress, In Development] would group chart data into separate components for all current values and any future values for the State field, with In Work being a combination of the In Progress and In Development states.
For more information on specifying chart values, see the Integrity Lifecycle Manager Help Center.
• --projectedTrendExpressions=value
When creating or editing an item fields trend chart, you can specify whether to display a projected trend for one of the displayed item field series, thus supporting the use of burn-down charts for planning work remaining within a fixed duration project. The projected trend displays a line between a starting value corresponding to the starting date and the end value corresponding to the end date. In addition, if you choose to display the projected trend, you can also display the actual trend as a line between the last actual series value to the end value corresponding to the end date.
This option specifies attributes for a projected trend graph in the item fields trend chart, where value consists of the following attributes separated by a colon:
chartedExpression is the expression (numeric field) to chart. This value is mandatory.
startValueExpression is a field expression (field name) or numeric constant (numeric value). For a field expression, the numeric value is the historic item field value. This value is mandatory.
endValueExpression is a field expression (field name) or numeric constant (numeric value). For a field expression, the numeric value is the "now" item field value. This value is mandatory.
projectedTrendLabel is a text string used for the chart legend and tooltips.
showUpdatedTrend displays the projected trend in the chart. Specify true or false (default).
updatedTrendLabel is a text string used for the chart legend and tooltips.
Tip: To clear the value for --projectedTrendExpressions=value, specify an empty string.
For example:
--projectedTrendExpressions=Effort:0:"Effort":"Planned Effort":true:"Unplanned Effort"
• --query=[user:]query
• specifies the name of the query that the chart is based on.
|
|
If the chart is a shared admin object, an admin query is required.
|
• --graphStyle=[VerticalBar|VerticalStackedBar|HorizontalBar|HorizontalStackedBar|Pie|Line|Table|XY|Bubble]
specifies the graph style used of the chart.
• --dataColors=value
specifies the custom data colors to be used using the RGB color model. For example: 'R,G,B;R,G;R,G,B' where R,G and B are within the range 0-255.
If the chart has more data points than the data colors you specify, the colors are repeated. If the --[no]isAutoColors option is true, the colors specified here are ignored.
|
|
This option is invalid for table style graphs.
|
• --bgColor=value
specifies the background color of the chart using the RGB color model. For example: 'R,G,B' where R,G and B are within the range 0-255.
|
|
This option is invalid for table style graphs.
|
• --[no]displayLegend
specifies whether to display the chart legend.
|
|
This option is invalid for table style graphs.
|
• --[no]displayLabels
specifies whether to display labels for values in the chart. If you select a pie graph style, this option is automatically selected. --nodisplayLabels is the default option.
|
|
This option is invalid for table graphs.
|
• --[no]is3D
specifies whether to display bar and pie graphs in 3D.
|
|
This option is invalid for table style graphs.
|
• --[no]isAutoColors
specifies whether to use the default chart colors. If false, you must provide colors through the data colors option.
|
|
This option is invalid for table style graphs.
|
• --[no]isShowZeroFieldCount
specifies whether to include empty field values in the chart.
• --[no]isShowZeroGroupingCount
specifies whether to include empty grouping values in the chart.
• --legendBgColor=value
specifies the background color for the chart legend using the RGB color model. For example: 'R,G,B' where R,G and B are within the range 0-255
|
|
This option is invalid for table style graphs.
|
• --legendPosition=[Right|Bottom|Left|Top]
• specifies the legend position in relation to the graph.
|
|
This option is invalid for table style graphs.
|
• --legendTitle=value
specifies the title for the chart legend.
|
|
This option is invalid for table style graphs.
|
• --outlineColor=value
specifies the outline color of the graph using the RGB color model. For example: 'R,G,B'
|
|
This option is invalid for table style graphs.
|
• --xLabelRotation=[Horizontal|VerticalDown|VerticalUp|45Down|45Up]
specifies the rotation of the horizontal axis labels for the chart.
|
|
This option is invalid for table style graphs.
|
• --[no]xReverse
specifies whether the chart uses a horizontal axis with a reverse orientation (left).
|
|
This option is invalid for table style graphs.
|
• --[no]xShowGrid
specifies whether to display horizontal grid lines.
|
|
This option is invalid for table style graphs.
|
• --[no]xShowTitle
specifies whether to display the title for the horizontal axis.
|
|
This option is invalid for table style graphs.
|
• --yLabelRotation=[Horizontal|VerticalUp]
specifies the rotation of the vertical axis labels for the chart.
|
|
This option is invalid for table style graphs.
|
• --[no]yReverse
specifies whether the chart uses a vertical axis with a reverse orientation (down).
|
|
This option is invalid for table style graphs.
|
• --[no]yShowGrid
specifies whether to display vertical grid lines.
|
|
This option is invalid for table style graphs.
|
• --[no]yShowTitle
specifies whether to display the title for the vertical axis.
|
|
This option is invalid for table style graphs.
|
• --sharedAdmin
specifies the chart as a system provided object (objects within the Integrity Lifecycle Manager object model that support solution definition and management, as well as workflow migration). For more information, see your administrator.
Important:
Once a user object is converted to a system provided object, you cannot revert it to a user object again.
• --computations=expression:name:pattern:axis name:minRangeValue:maxRangeValue:tickUnitValue
specifies an expression and numeric axes attributes.
Note the following about specifying numeric axes attributes:
◦ If you specify one set of numeric axes attributes (minimum range, maximum range, and tick unit), these attributes are specified for the X and Y axes. For XY (scatter) charts, PTC recommends against setting individual numeric axes attributes for the X and Y axes.
◦ For bubble charts, PTC recommends against specifying numeric axes attributes because they override the calculated values provided by the underlying expression and users will have to zoom in/out to properly view chart values.
expression specifies an aggregate expression for a distribution chart, a computed expression for an issue fields chart, or a numeric field for an issue fields trend chart. For information on creating expressions, see the Integrity Lifecycle Manager Help Center
name specifies the label name for the aggregate expression, computed expression, or numeric field as you want it to appear in the chart. If you do not define a label, the aggregate expression, computed expression, or numeric field name displays.
pattern specifies the display pattern for the value of the aggregate expression, computed expression, or numeric field value.
axis name specifies a name for the numeric axis as you want it to appear in the chart.
minRangeValue specifies the minimum range to display numeric field values in the chart. If you do not specify a range, a default range displays in the chart.
maxRangeValue specifies specifies the maximum range to display numeric field values in the chart. If you do not specify a range, a default range displays in the chart.
tickUnitValue specifies the units that display on the numeric axis. For example, if you specify a minimum range of 0, a maximum range of 100, and a tick unit of 10, the numeric axis displays 0, 10, 20, 30, 40, and so on up to 100.
|
|
Field names in expressions and expression labels with colons must be enclosed by escaped double quotes, and the whole computation must be enclosed in double quotes, for example,
--computations="\"Actual Dev Time\":\"Hours: Development\":pattern:..."
|
• --startDateField=field
specifies the date field containing the date you want to use as the start date for each issue in an issue fields trend chart.
• --numberOfSteps=value
specifies the trend chart's time span. If this option is specified, the chart's end date is determined by the specified step type multiplied by the specified number of steps.
|
|
You cannot have more than 500 steps in a trend chart.
|
To specify an interval in the past, use a negative value.
• --runDateIsEndDate
specifies that the chart's run date is the end date. This option replaces the --endDate=value option.
• --[no]deltasOnly
• specifies whether to display only the differences between the current and previous values of the reported numeric fields in an issue fields trend chart.
• --issueIdentifier=value
• specifies the field that you want to identify issues by in an issue field or issue fields trend chart. For example, if you specify --issueIdentifier={Project}, each issue in the chart is identified by the value of the Project field.
If you want to add text that precedes the specified field, type it before the field, for example, --issueIdentifier=Project:{Summary}. The chart then identifies each issue by displaying Project: Summary field value .
• --[no]displayShapesForLineGraphs
specifies whether to display shapes in a line graph chart. The shapes in the chart represent data, allowing you to more easily differentiate the data in the chart.
• --[no]swapRowsAndColumns
specifies whether to invert the appearance of columns and rows in a table chart.
• --[no]displayRowTotals
specifies whether to display row totals in a table chart.
• --[no]displayColumnTotals
specifies whether to display column totals in a table chart.
• --rangeDefinitions=value
• specifies range definitions for computed expressions included in a table chart, where value consists of the following attributes: expression name;range field name;range label:lower limit:upper limit:icon:background color:text color:text style:display format; lower limit:upper limit:.....;extend to axis .
expression name specifies the name of the computed expression that the range definition applies to. An expression name is mandatory and must be a valid expression in the chart. For column or row totals, valid expression names are -Column Totals- and -Row Totals-. For distribution charts containing multiple computed expressions, row or column totals must be followed by the expression name.
range field name specifies a valid field name if you want to relate the range definitions to an existing range field. For one chart range, specify an empty string as the range field name. If a valid range field name is defined for each range, define a range label, background color, text color text style, and display format. For individual range definitions, define a range label, lower limit, upper limit, icon, background color, text color text style and display format for each range.
range label specifies a label for the range.
lower limit specifies the lower limit of the range. If a lower limit is not specified, -Infinity is automatically specified.
upper limit specifies the upper limit of the range. If an upper limit is not specified, Infinity is automatically specified.
|
|
A numeric value must be specified for a defined range; range intersections are invalid. For example, the following ranges are invalid: 0 - 5 and 4 - 8, or 0 - 5 and 5 - 10. For an integer field, an acceptable range would be 0 - 5 and 6 - 10. For a floating point field, an acceptable range would be 0 - 5 and 5.01 - 10.
|
icon specifies an image file representing the range category. This is optional.
background color specifies the background color of the range using the RGB color model, for example, 'R,G,B', where R, G, and B are within the range 0-255.
text color specifies the text color of the range using the RGB color model, for example,'R,G,B', where R, G, and B are within the range 0-255.
text style specifies the text style. Available text styles are plain, bold, italic, bolditalic, or defaultplain.
display format specifies how to display the range in the table chart. Available options are value, iconvalue, icon, label, iconlabel, or blank.
extendToAxis specifies whether to apply the range definition associated with a computed expression to all computed expressions in the chart. This option can be false or true. By default, false is specified.
Note the following:
◦ You cannot specify a range for the Count expression.
◦ You can specify a range for each computed expression; however, only one computed expression can specify the extendToAxis option.
◦ If a table cell contains a display definition that conflicts with the extendToAxis option of another table cell, both table cells display the background color option of the table cell with the enabled extendToAxis option.
See Also
