REST API - Defining a Trace in the Request Body

The following services require you to define/specify a trace in the request body:

• Add Traces
• Delete Traces
• Change Parent Trace

In the request body you must specify:

• The other artifact in the trace relationship (for Add Traces and Delete Traces requests)
  OR
• The new parent trace (for Change Parent Trace)

Parameters

You must specify a Traces element first to contain any individual traces you want to specify by using the Trace element. Here is an example in XML:

<Traces>
<Trace>
</Trace>
<Trace>
</Trace>
</Traces>

The following parameters can be specified within each <Trace> element you are specifying:

• ArtifactId: The ID of the artifact whose trace relationship is being defined.
• SubArtifactId: The ID of the sub-artifact whose trace relationship is being defined.
• ProjectId: The ID of the project of the artifact whose trace relationship is being defined.
• Type: Defines the type of trace. The valid values are the following:
  • Manual: Only applicable when adding or deleting a trace.
  • Parent: Only applicable when moving an artifact.
• Direction: The direction of the trace. The valid values are the following:
  • To: From the artifact in the URI request to the artifact in the request body.
  • From: To the artifact in the URI request from the artifact in the request body.
  • TwoWay: The artifacts have a bi-directional trace.
• IsSuspect: Marks the trace as suspect.

Depending on the request, you are adding a trace relationship to, removing a relationship from, or establishing a new child-parent relationship with the artifact in the request body. In each context, some parameters are mandatory, while others are optional or ignored:

• Adding a Trace:
  • Required: direction, type (set to Manual), one of artifactId or subArtifactId (the other is optional)
  • Optional: projectId and isSuspect
• Deleting a Trace:
  • Required: type (set to Manual), one of artifactId or subArtifactId (the other is optional), direction (if the query is using the reconcileWithTwoWay parameter, which is set to true)
  • Optional: projectId
  • Ignored: isSuspect
• Changing a Parent Trace:
  • Required: type (set to Parent), one of artifactId or projectId
    The artifact in the request body must belong to the same project as the artifact in the URI request.
  • Ignored: All other properties are ignored.

Examples

AddTrace Example

Here is an example of a request body in XML format:

<?xml version="1.0" ?>			
<Traces xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.blueprintsys.com/blueprint/api/v1">
  <Trace>
    <ArtifactId>888020</ArtifactId>
    <Direction>To</Direction>
    <IsSuspect>false</IsSuspect>
    <ProjectId>847739</ProjectId>
    <Type>Manual</Type>
  </Trace>
</Traces>

Here is an example of a request body in JSON format:

[
  {
    "Type": "Manual",
    "ProjectId": 123456,
    "ArtifactId": 123,
    "IsSuspect": false
  },
  {
    "Type": "Manual",
    "ProjectId": 123456,
    "ArtifactId": 456,
    "IsSuspect": false
  },
  {
    "Type": "Manual",
    "ProjectId": 789,
    "ArtifactId": 789,
    "SubArtifactId": 789,
    "IsSuspect": false
  }
]

Delete Traces Example

Here is an example of a request body in XML format:

<?xml version="1.0" ?>			
<Traces xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.blueprintsys.com/blueprint/api/v1">
  <Trace>
    <ArtifactId>843925</ArtifactId>
    <Type>Manual</Type>
  </Trace>
</Traces>

Here is an example of a request body in JSON format:

[
  {
    "Type": "Manual",
    "ArtifactId": 847750
  }
]

ChangeParentTrace Example

Here is an example of a request body in XML format:

<?xml version="1.0" ?>			
<Traces xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.blueprintsys.com/blueprint/api/v1">
  <Trace>
    <ArtifactId>999666</ArtifactId>
    <Type>Parent</Type>
  </Trace>
</Traces>

Here is an example of a request body in JSON format:

[
  {
    "Type": "Parent",
    "ArtifactId": 999666
  }
]