Trace: trace

A trace is a link between any two StarTeam items. It expresses a join relationship. Use the trace command to create or to find and update a trace in a project/view described by the -p parameter (or preceding connect/set commands). A trace will only be created if its endpoints are guaranteed to exist.

Syntax

The syntax for this command is:

stcmd{Ex} trace [-id traceID] 
[-sourceType sourceTypeName -sourceID sourceItemID 
[-sourceView sourceViewName]]
[-targetType targetTypeName -targetID targetItemID 
[-targetView targetViewName]]
[-pinSource] [-pinTarget] [-suspect] 
[-traceTypeID nnn]
[-p "user:password@host:port/project/view"]

Parameters

For information about the command parameters, refer to Operation Parameters.

In addition:

Parameter Description
-id traceID Optional. If specified, an existing trace (identified by traceID) is updated, otherwise, a new trace is created.
[-sourceType sourceTypeName -sourceID sourceItemID [-sourceView sourceViewName]]

Optional. If specified, the source endpoint is set to the item which is identified by sourceItemID, sourceTypeName (e.g. changerequest, task, story, sprint, etc) and source view name.

Source view name is optional. If not specified, the source item must resolve to an item in the same view as the trace.

[-targetType targetTypeName -targetID targetItemID [-targetView targetViewName]]

Optional. If specified, the target endpoint is set to the item which is identified by targetItemID, targetTypeName (e.g. changerequest, task, story, sprint, etc) and target view name.

Target view name itself is optional. If not specified, the target item must resolve to an item in the same view as the trace.

[-pinSource] Optional. The default behavior is for the trace to float at the source end. If specified, the trace is pinned to the source tip.
[-pinTarget] Optional. The default behavior is for the trace to float at the target end. If specified, the trace is pinned to the target tip.
[-suspect] Optional. The default behavior is for a trace not to be marked suspect. If specified, the trace is marked as suspect (it's suspect flag is set to true).
[-traceTypeID] If specified, the numeric id must be a valid enum value from the set of trace types:
  • UNDEFINED 0
  • REQUIREMENT_DEPENDENCY 1
  • TASK_DEPENDENCY 2
  • WORK_ITEM 3
  • RESOLUTION_POINT 4
  • VALIDATION_TEST 5
  • MANUAL 6
  • PROCESS_ITEM 7
  • COPY 8
  • BREAKDOWN 9
  • EXECUTION 10
  • DEFECT_STREAM 11
  • REQUIREMENT_STREAM 12
  • BACKLOG_STREAM 13
  • CARRY_OVER 14
  • WHITEBOARD 15
  • DEFINE 16
  • REQUIREMENT_SYNC 17

Example

The following will create a trace in the bar view, source endpoint ChangeRequest (ID 1234) also from the bar view, target endpoint Story (ID 5678) from the foo view, source floating, target pinned: 

stcmd trace -sourceType changerequest -sourceID
1234 -targetType story -targetID 5678 -targetView "foo"
-pinTarget -p "user:pwd@host:port/project/bar"