im editquery
edits the properties of an existing Integrity Lifecycle Manager query
Synopsis
im editquery[--copyColumnsFromQuery[=[user:]query] [--fields=field,field,...] [--[no]sortAscending] [--sortField=field] [--image=[none|default|<path>][--shareWith=u=user1[:modify],user2[:modify],...;g=group1[:modify],group2[:modify],...] [--[no]confirmSharedAdmin] [--description=value] [--name=value] [--sharedAdmin] [--hostname=value] [--queryDefinition=query] [--queryDefinitionFile=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]][user:]query
Description
You use im editquery to edit the properties of an existing Integrity Lifecycle Manager query.
For example, the following edits the existing Release 2.0 Docs Issues query to show the estimated and actual hours for the issues:
im editquery --fields="State","Estimated Hours","Actual Hours","Assigned User" "Release 2.0 Docs Issues"
Note the following:
• You may edit only one query at a time and only queries that you have created.
• The quick query cannot be hidden, deleted, shared with other users and groups, renamed, or given a description.
• Queries with several filters may take longer to run than queries with only one or two filters.
• You cannot edit a query’s associated column set if it is currently being used in an Issues view; however, you can edit the default column set if it is currently being used in an Issues view.
• You cannot query on configuration management project fields.
• Displayed date fields do not change based on the time zone that a user is operating in; however, displayed date/time fields and time entries vary based on the time zone that a user is operating in.
• Symbolic dates are evaluated on the Integrity Lifecycle Manager Client’s time zone.
• When specifying a date range in a query, all dates are treated as timestamps, converted to the time zone on the Integrity Lifecycle Manager Server, and then truncated to a date-only format. The resulting date-only format is then converted to a Structured Query Language (SQL) statement format on the Integrity Lifecycle Manager Server, and the query is run based on the time zone of the server. If the user defining the date range is not in the same time zone as the Integrity Lifecycle Manager Server, a day can be lost or gained at either end of the defined range. The rollback of dates can cause the query results to vary.
|
|
Important: The date range conversion does not cause any problems when the user is in the same time zone as the Integrity Lifecycle Manager Server. For example, if the Integrity Lifecycle Manager Server is in the America/New_York time zone and the following query date range is defined by a user in Germany: Jan 1, 2006 to Jan 31, 2006. The final conversion of the date range is: Dec 31, 2005 06:00:00 AM GMT+01:00 to Jan 31, 2006 06:00:00 AM GMT+01:00. To avoid any date rollbacks when working with query date ranges in Integrity Lifecycle Manager, PTC recommends that users specify the time zone that is used by the Integrity Lifecycle Manager Server to which they are connecting.
|
• Because dynamically computed fields are not stored in the database, dynamically computed short text fields cannot be located with an all text field search in the Integrity Lifecycle Manager Client. To search for dynamically computed short text fields, create a query that includes a specific “field contains” comparison. For more information about computed fields, see your administrator.
Options
This command takes the universal options available to
im commands, as well as some general options. See the
options reference page for descriptions.
• --copyColumnsFromQuery[=[user:]query]
specifies a query to copy the column configuration from to use as the new default for the query you are editing.
|
|
--fields=field, field,...,
--[no]sortAscending, and
--sortField=field are not mandatory, but if specified, they overwrite the current default column configuration.
|
• --fields=field,field,...
specifies the fields to use as default columns for the query. This overrides the current default columns.
• --[no]sortAscending
specifies the sort direction that issues are displayed in. This overrides the current default sort direction.
• --sortField=field
specifies the field that issues are sorted by. This overrides the current default sort field.
• --image=[none|default|<path>]
specifies whether an image appears for the new query.
--image=none does not specify an image for the query.
--image=default specifies the default funnel image for the query.
--image=<path> specifies the path and name of a custom image for the query, for example, c:\images\defect_icon.gif.
|
|
Images must be GIF or JPEG format, and no larger than 16 by 24 pixels.
|
• --shareWith=u=user1[:modify],user2[:modify],...;g=group1[:modify],group2[:modify],...
specifies the users and groups that can use and modify the query. Your administrator defines users and groups.
• --[no]confirmSharedAdmin
specifies whether to confirm the conversion of the query to a system provided object.
• --description=value
specifies a short description for the query.
• --name=value
specifies the new name of the query. Names may be a maximum of 100 characters and cannot contain square brackets.
• --queryDefinition=query
specifies a string to define the query constraints. The query must be of the following format:
<rule> is defined as ( <filtergroup> )
<filtergroup> is defined as one of the following:
(<filtergroup> and <filtergroup> and ...) (<filtergroup> or <filtergroup> or ...)( (<filter>) and (<filter>) and ...)( (<filter>) or (<filter>) or ...)
where
<filter> is defined as disabled (<filter>)<filter> is defined as not (<filter>)<filter> is defined as <fields>|<subquery>|<attachment>|<relationship>|<branch>|<genericcp>|<histval>|<histdate>|<histuser>|<timeentry>|<testresult>|<item>
<histuser> is defined as histuser[Summary|State|..] was changed by <user>
<histuser> is defined as histuser.any field was changed by <user>
<histdate> is defined as histdate[Summary|State|..] was changed <datevalue>
<histdate> is defined as histdate.any field was changed <datevalue>
<histval> is defined as histval[Summary|State|..] <value>
<genericcp> is defined as genericcp:<cptype>:<attrfieldidentifier>:[fieldname]
where <attrfieldidentifier> is attribute or entryattribute and [fieldname] is the real name, not the display name, of the attribute. Use the im viewcptype command to find the attribute name.
<genericcp> is defined as not(genericcp:si:attribute[resolutionlist]is empty)
<genericcp> is defined as genericcp:<cptype>.exists
<relationship> is defined as relationship[ID|Created User|..] using [Relationship Field]=<value>
<relationship> is defined as relationship.exists backward|forward using [Relationship Field]. To restrict your query to either backward or forward relationships, backward must be specified if you specify the Backward Relationships field, and the forward option must be specified if you specify the Forward Relationships field or a custom relationship field. <relationship> is defined as relationshipFlag [Relationship Flag Name] backward|forward using [Relationship Field]
<attachment> is defined as attachment[file size|file name|mime type] <value><attachment> is defined as attachment.exists
<timeentry> is defined as timeentry[issue ID|user|entry date|source|duration|notes|created by|created date|modified by|modified date]<timeentry> is defined as timeentry.exists
<testresult> is defined as testresult.isrelatedto <testresult> is defined as testresult.exists <testresult> is defined as testresult.hasattachment <testresult> is defined as testresult.hasrelateditem <testresult> is defined as [ID]comparison where ID can be one of Verdict, Verdict Type, Modified By, Modified Date, Session ID
<branch> is defined as branch.isBranch<branch> is defined as branch.hasBranch
<branch> is defined as branch[X] in parent contains Y. This filter finds items where field X of the branched from item has a specific value. In other words, an item is a child (is a branch), and the parent item has field X with value Y. Examples follow:
<branch> is defined as branch[X] in child contains Y. This filter finds items where field X of the branched item has a specific value. In other words, an item is a parent (has a branch), and the child item has field X with value Y. Examples follow:
◦ branch[ALM_Text] in parent contains "Project Description"
◦ branch[ALM_Actual Budget] in parent = 12
◦ branch[ALM_Actual Effort] in parent > 20
<item> is defined as item.node
<item> is defined as item.content
<item> is defined as item.segment
<item> is defined as item.subsegment
<item> is defined as item.lockeddocument
<item> is defined as item.meaningful
<item> is defined as item.nonmeaningful
<item> is defined as item.shareditem
<item> is defined as item.group
<item> is defined as item.teststep
<item> is defined as item.testcase
<item> is defined as item.testsession
<item> is defined as item.testsuite
<item> is defined as item.live
<item> is defined as item.versioned
Note: If document versioning is enabled, queries return all items (live and versioned) by default. To specify live or versioned items, include the item.live or item.versioned filter. For more information on document versioning, see the Integrity Lifecycle Manager Help Center.
<subquery> is defined as subquery[Query1|Query2|...]
<fields> is defined as field[ID|Created User|Created Date|..]<value><fields> is defined as field.anyTextField
If document versioning is enabled, you can specify the following conditions to display live and versioned items by ID:
▪ display a specific live item only. For example, "(field[ID]=123)" returns 123.
▪ display a live item and all versions of the item. For example, "(field[ID]=123 include versions)" returns 123, 123-1.0, 123-1.1, and 123-1.2.
▪ display a range of live items. For example, "(field[ID]>123 and 128)" returns 124, 125, 126, and 127.
▪ display a specific versioned item. For example, "(field[ID]=123-1.0)" returns 123-1.0.
|
|
You cannot display a range of versioned items, for example, "(field[ID]>123-1.0 and 128-1.0)".
|
For more information on live and versioned items, see the Integrity Lifecycle Manager Help Center.
<value> is defined as <value> or "is empty" <value> is defined as "is empty"<value> is defined as <leftrangeop> num and <rightrangeop> num<value> is defined as contains <text><value> is defined as <operator> num and <operator> num<value> is defined as <operator> num<value> is defined as hasSourceLinks
<rightrangeop> is defined as < | <=<leftrangeop> is defined as | >=
value> is defined as = <uservalue>, <uservalue>, ..
<uservalue> is defined as "me" | "unspecified" or "is empty" | user1 | user2 | ...
<value> is defined as <datevalue>
<datevalue> is defined as between mm/dd/yyyy and mm/dd/yyyy<datevalue> is defined as between mm/dd/yyyy hh/mm/ss and mm/dd/yyyy hh/mm/ss (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.)<datevalue> is defined as in the last|next num days|months|years<datevalue> is defined as in the last|next num days|months|years hours|minutes|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.)<datevalue> is defined as today|yesterday|tomorrow
num is defined as .. | -1 | 0 | 1 | ..
<operator> is defined as = | > | >= | <= | < | <>
For example:(((field[Summary]contains"Hello")or(field[Assigned Group]="everyone")) and (attachment.exists))((field[Summary]contains"Requirement")or(field[Assigned Group]="Project Managers"))((field[Category]="Technical Requirement") or (field[Category]="System Requirement"))
|
|
To reference the original query in the new query so that any changes to the original query are reflected in the new query, define <subquery> as subquery[OriginalQuery].
|
• --queryDefinitionFile=value
specifies a file that contains the complete definition of the query. See --queryDefinition for the file format.
• --sharedAdmin
specifies the query 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.
• [user:]query
specifies the name of the user who the query belongs to and the query name, for example, jhoyt:"Cosmos Critical Defects". If you are editing a query you own, you do not have to specify the user name, but you must specify the query name.
|
|
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 CosmosDefects query created by jhoyt. If Integrity Lifecycle Manager cannot find the query and/or user, it searches for the jhoyt:CosmosDefects query created by any user.
|
• branch[Project] in child=/Projects/Release2
• branch[Summary] in child contains "Some issue Summary"
• branch[ALM_Content] in child 10
See Also
