Append text or update traces from TSV

post/traces

Appends text to the collection or updates the processorNote field of appended text. There are two types of traces: one is at the decision step boundary and other is at the variable assignment. The scope query parameter is used to specify the type of trace.

This operation processes tab-separated-values (TSV) text with a case-insensitive header row that specifies the order of these required columns:

  • traceId
  • seqNo
  • traceTimeStamp
  • objectUri
  • action
  • processorNote
  • text
A decision trace might require one or more rows of TSV text to convey. The value of seqNo, starting from 1, should be monotonically increasing from the first row to the last row. The rows are likely to be appended using multiple POST actions due to request body size restriction on the client formulating the POST action. Otherwise, one TSV row would have been used.

The text column value must not include the TAB character.

The text column contains whole or part of a decision trace.

The value of the action column is either append or update.

When the POST call is used to append text to the collection, all the above columns except the processorNote column must be given non-empty values.

When the POST call is used to update text to the collection, the only column that can be changed is the processorNote column. The traceId column must have a value for the service to know which execution trace to update. Since a trace has one or more rows, the seqNo column is normally left empty so that all rows of the trace receive the same processorNote value. The other columns (traceTimeStamp, objectUri, text) should be left empty. If values are specified for these columns, they are ignored since they cannot be changed. Here is the order that the columns for updated:

  • traceId
  • seqNo
  • traceTimeStamp
  • objectUri
  • text
  • action
  • processorNote
The output is a multipart/mixed response body. The boundary string of each part is identified in the Content-Type response header. There are three parts in this response.
  1. The first part is for the accepted TSV (header Content-ID: Accepted-TSV). Each trace line that was successfully processed is identified here.
  2. The second part is for the rejected TSV (header Content-ID:Rejected-TSV). Each trace that could not be processed is identified here. It is in CSV format with the following column order: traceId, and error message.
  3. The third part is for global issues (header Content-ID: Global-Issue). It is in TSV format with the following column order: line number, global error message that conveys the error that prevents any TSV processing. An example would be the lack of permissions.

Request Samples

1

Response Samples

1{
2  "part1": {
3    "contentType": "text/csv; charset=\"utf-8\"",
4    "contentId": "Accepted-CSV",
5    "body": "3d4120b3-1fe7-4fce-b333-0ae1b93aa03c,The record with the trace ID \"3d4120b3-1fe7-4fce-b333-0ae1b93aa03c\" is updated."
6  },
7  "part2": {
8    "contentType": "text/csv; charset=\"utf-8\"",
9    "contentId": "Rejected-CSV",
10    "body": ""
11  },
12  "part3": {
13    "contentType": "text/csv; charset=\"utf-8\"",
14    "contentId": "Global-Issue",
15    "body": ""
16  }
17}

Query Parameters

NameTypeRequiredDescription
scope
string
false

The type of traces.

Allowed values:
assignmentstep
Default:
step

Header Parameters

NameTypeRequiredDescription
Accept
string
true

In addition to multipart/mixed, also include application/vnd.sas.error+json in the Accept header. The two media types are separated by a comma. If there is a processing error, the error is reported in a JSON error object. In that case, without this arrangement, since the client is expecting only a response of multipart/mixed type, the server uses Http status of 406 to tell the client that it cannot match the expectation because a JSON error object cannot be mapped into a multipart/mixed response. By also accepting application/vnd.sas.error+json, this is avoided.

Allowed value:
multipart/mixed, application/vnd.sas.error+json

Request Body

The tap-separated-values that contains a header row.

Responses

StatusMeaningDescription
200OK

The request succeeded. One or more rows of text are appended. Check the response for any error.

Schema
400Bad Request

The request was invalid.

Schema