REST API - Defining a Trace in the Request Body

Updated by Stefenie Stockbridge

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

In the request body you must specify:

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
  }
]

How did we do?