im analytics
calculates a computed field within a specified timeframe, storing the value in the issue history
Synopsis
im analytics [--recomputeHistory] [--endTime=value] [--field=field] [--increment=value] [--incrementType=value] [--startTime=value] [--[no]clearHistory] [--[no]confirm] [--hostname=server] [--port=number] [--password=password] [--user=name] [(-?|--usage)] [(-F file|--selectionFile=file)] [-g|--gui] [(-N|--no)] [--quiet] [(-Y|--yes)] [--[no]batch] [--settingsUI=[gui|default]] [--cwd=directory] [--status=[none|gui|default]] [--forceConfirm=[yes|no]]
Description
When you create a computed field, you typically configure it to calculate at a specific time in the future, storing the value in the history of each issue containing the computed field.
im analytics calculates what the value of the computed field would have been at specific times and stores the value in the history of each issue containing the computed field. This command is useful for discovering historical trends, for example, you could determine how long a Defect issue typically remained in the In Development state in a current project compared to that of a previous project. For more information on computed fields, see the
im createfield command.
Key Considerations:
• This command is required only if a new calculation if required over existing historical data.
• To use the im analytics --recomputeHistory -g command, you must either be an administrator or have type administrator permissions for all types that the specified field displays in.
• Depending on the options you specify, this command may delete or modify issue history.
• Depending on the following factors, this command may take a long time to complete:
◦ the complexity of the underlying computed expression
◦ the number of issues containing the specified computed field
• The im analytics --recomputeHistory -g command renders issue data as it existed at the specified time. For non-historied data source (attachments, change packages containing entries that have moved, permissions, and administrative objects), the im analytics --recomputeHistory -g command approximates the historical data. To render non-historied data sources as they were known at a specific time, PTC recommends defining computed fields that use the --staticComputation option, which captures historical values.
• Computed fields are calculated in the order that they appear in the issue; however, if a computed field depends on the value of another computed field, it is calculated after the computed field containing the dependant value. Depending on the number of issues in your database and the number of issues containing computed fields that contain dependencies, it may take a long time to calculate the value of the computed fields.
• This command may be cancelled at any time; however, it will not take effect until the specified interval calculation has completed. If you cancel this command, previous field values remain stored in the database. If the clear history option is selected and you cancel this command, issue history is still cleared.
Example
This example illustrates how to determine the historical trend for defects in projects.
1. Create a new type to represent projects, for example, Project.
2. Create some Project issues to represent projects.
3. From the command line, create a computed field, for example, Defect Count, that calculates the number of defects related to each project:
im createfield –-type integer –-computation=‘Query("Financial Toolkit Defects: In Dev", Project, count()) –-name ‘Defect Count’
4. Make the Defect Count field visible in the Project type only.
5. From the command line, project the Defect Count field back in time:
im analytics --recomputeHistory –-starttime=06/01/2002 –-endtime=08/24/2007 –-increment=1 –-incrementtype=week –-field=‘Defect Count’
6. Create a query that lists all Project issues, for example, All Projects.
7. From the command line, create a chart:
im createchart –-trendstep=week –-charttitle=‘Defect Count’ –-startdate=06/01/2002 –-enddate=02/01/2007 –-computations=‘"Defect Count"’ –-query ‘All Projects’ –-charttype=‘Issue Fields Trend’ –-issueidentifier {Summary} –name xx
|
|
To use the im analytics command, you must either be an administrator or have type administrator permissions for all types that the specified field displays in.
|
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.
• --recomputeHistory
performs the recompute history operation, calculating what the value of the specified computed field would have been at specific times and storing the value in the history of each item containing the computed field.
• --endTime=value
specifies the ending calculation date of the computed field using the mm/dd/yyyy hh/mm/ss format, where mm/dd/yyyy hh/mm/ss is the month, day, year, hour, minutes, and seconds. 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.
• --field=field
specifies the computed field to calculate.
• --increment=value
specifies an integer that represents an increment unit. For example, if you specify an increment unit of 1 and an increment type of day, the computed field calculates once a day.
• --incrementType=value
specifies the size of the increment unit. Acceptable sizes are: day, week, month, or year.
• --startTime=value
specifies the starting calculation date of the computed field using the mm/dd/yyyy hh/mm/ss format, where mm/dd/yyyy hh/mm/ss is the month, day, year, hour, minutes, and seconds. 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.
• --[no]clearHistory
clears previous history entries for the selected field between the specified times.
• --[no]confirm
confirms if to calculate the computed field.
See Also
