REST API - Defining a Trace in the Request Body
The following services require you to define/specify a trace in the request body:
In the request body you must specify:
- The other artifact in the trace relationship (for REST API - Add Traces Request and REST API - Delete Traces Request requests) OR
- The new parent trace (for REST API - Move Artifact Request)
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 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 }]