REST API - Delete Traces Request

Updated by Stefenie Stockbridge 

api/v1/projects/{projectId}/artifacts/{artifactId}/traces?reconcilewithtwoway={boolean}

Description

Deletes the specified trace(s).

You can only delete manual traces (that is, a trace manually added by a user). You cannot delete parent/child relationships or other relationships.

You can delete more than one trace in a single request as long as the ArtifactId you specify in the request body has a trace relationship with the artifact in the request URI.

URL Structure

[Blueprint_URI]/api/v1/projects/{ProjectId}/artifacts/{ArtifactId}/traces
  • ProjectId: The ID of the project that contains the first artifact in the trace relationship you want to delete. A trace relationship always includes two artifacts.
  • ArtifactId: The ID of the first artifact in the trace relationship you want to delete. A trace relationship always includes two artifacts.

Supported Methods

Request URI Parameters

  • ReconcileWithTwoWay (optional): Indicates how to handle the existence of an inverse trace. This parameter can be set to true or false, and is used in conjunction with the Direction parameter in the request body that is set to To or From.
    If reconcileWithTwoWay is set to true, and a bidirectional trace exists, the trace is not deleted; instead, the trace direction opposite to that in the request body is preserved (that is, the inverse trace replaces the bidirectional trace).
    The default is false if not specified. The default is true if the parameter is included in the URI with no given value.

Request Body Parameters

The trace(s) must be included in the body of the request. Read more about how to specify one or more traces in the request body.

Blueprint Result Codes

Your response may contain ResultCode and Message parameters if your request involves changes to Blueprint data.  These parameters provide detailed information about the result of your request.

  • 200 (OK)
    • The artifact updated successfully.
  • 421 (Trace Not Manual)
    • Only valid trace value is Manual.
  • 422 (Trace Not Found)
    • The artifact does not have the specified trace.
  • 425 (Trace Cannot Be Managed)
    • In order to manage a trace, you need to have Trace permissions for both traced artifacts and Edit permissions for at least one artifact.
  • 500: Internal Server Error

HTTP Status Codes

  • 200: OK
  • 201: Successfully Created
  • 206: Partial Content
  • 400: Bad Request
    This error can occur for a variety of reasons:
    • At least one URI or request body parameter is invalid, such as one of the Filter, Traces, Offset or Limit parameters.
    • A required value has not been provided.
    • If you are submitting a POST or PATCH request and have not added the X-HTTP-Method-Override parameter to your request header.
  • 401: Unauthorized
    • The Blueprint token is missing, invalid or expired.
  • 403: Forbidden
    • The applicable permissions are needed. For example, this error can occur when:
      • An Author or Collaborate license is needed for access.
      • Comment permissions are needed on the artifact.
      • Edit permissions are needed on the change summary job.
  • 404: NotFound
    • Item is not found in the project. For example, this error can occur when:
      • Artifact not found.
      • Artifact type not found.
      • Project not found.
      • ALM target not found.
      • Change summary job not found.
      • User does not have edit permissions for this artifact, project or ALM target.
  • 409: Conflict
    • Reason for failure can be found in the response body. Additional information may also be found in the log.
  • 411: Length Required
    • If the Content-Length header is missing in the request.
  • 413: Request Entity Too Large
    • If the provided file size is larger than allowed.
  • 415: Unsupported Media Type
    • If the provided media type is not of MIME Multipart Content "form-data."
  • 416: Request Range Not Satisfiable
    • If offset points to a part of a collection that is not available.
  • 500: Internal Server Error
  • 501: Not Implemented

Examples

XML Example

Example 1

Request URI

https://production.blueprintcloud.com/api/v1/projects/847739/artifacts/847741/traces

Request Body

<?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>

Example 2: using the ReconcileWithTwoWay parameter to retain the inverse of a bidirectional trace relationship

Request URI

https://production.blueprintcloud.com/api/v1/projects/847739/artifacts/843921/traces?reconcilewithtwoway=true

Request Body

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

Response Body

<TraceDeleteResults xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.blueprintsys.com/blueprint/api/v1">
  <TraceDeleteResult>
    <ArtifactId>843927</ArtifactId>
    <Direction>TwoWay</Direction>
    <Message>Trace has been successfully deleted.</Message>
    <ResultCode>200</ResultCode>
  </TraceDeleteResult>		
</TraceDeleteResults>
JSON Examples

Example 1

Request URI

https://production.blueprintcloud.com/api/v1/projects/847739/artifacts/847741/traces

Request Body

[
  {
    "ArtifactId": 847750,
    "Direction": "TwoWay",
    "Type": "Manual",
    "Message": "Trace has been successfully deleted.",
    "ResultCode": 200
  }
]

Example 2: using the ReconcileWithTwoWay parameter to retain the inverse of a bidirectional trace relationship

Request URI

https://production.blueprintcloud.com/api/v1/projects/847739/artifacts/843921/traces?reconcilewithtwoway=true

Request Body

[
  {
    "Type": "Manual",
    "ArtifactId": 843923,
    "Direction": "To"
  }
]

Response Body

[
  {
    "ArtifactId": 843923,
    "Direction": "TwoWay",
    "Type": "Manual",
    "Message": "Trace has been successfully deleted.",
    "ResultCode": 200
  }
]

How did we do?