Introduction

The Plain Text Redactors API allows you to take a source document and a redaction markup file as input and produce redacted plain text as output.

Available URLs

POST /v2/plainTextRedactors

Creates and starts a new plain text redactor process.

A plain text redactor represents a process that runs on the server and creates a plain text file with the text from the source document. Each redacted text fragment is replaced with the string "<Text Redacted>".

The server process to create the redaction markup is started by this request, but a response is sent before the process is complete. Use the GET /v2/plainTextRedactors/{processId} URL below to get the state and results of an in-progress or completed plain text redactor process.

A new plain text document will be created that will contain the redacted document text. The new document will be made available by a new WorkFile ID.

NOTES:

1. Plain text redactor supports the following mark types (see Markup JSON Specification):

   • TextSelectionRedaction

   • RectangleRedaction

     Other types of marks will have no effect on the result.

2. Plain text redactor will produce an empty plain text document for raster documents.

3. CAD files are not supported.

Request

Request Headers

Request Body

JSON object conforming to the following:

• input
  • source (Object) Required. Describes the document from which text will be redacted. This document will not be modified.
    • fileId (String) Required. The ID of the WorkFile which represents the source document that will have redactions applied.
  • markup (Object) Required. Describes the JSON document which contains the markup definition.
    • fileId (String) Required. The ID of the WorkFile that represents the JSON markup document. The document must satisfy the Markup JSON Specification.
  • dest (Object) Required. Describes the plain text output document.
    • lineEndings (String) Required. Describes the line endings in the plain text output document. The following values are allowed:
      • "\r\n" - Represents Windows-style line endings as CR followed by LF.
      • "\n" - Represents Unix-style line endings as LF alone.
• minSecondsAvailable (Integer) The minimum number of seconds this plain text redactor status will remain available via a GET request. The actual lifetime may be longer. The default lifetime is defined by the processIds.lifetime central configuration parameter.

Successful Response

Response body

JSON object with the following properties:

• input (Object) A copy of the request body input object.
• processId (String) The id of the new plain text redactor process.
• expirationDateTime (String) The date and time (in ISO 8601 Extended Format) when the plain text redactor will be deleted.
• state (String) The current state of the plain text redaction process running on the server. The response will always be "processing".
• percentComplete (Integer) The percentage (0 – 100) complete of the plain text redactor process. The response will always be 0.
• affinityToken (String) Affinity token for this plain text redactor. Present when clustering is enabled.

Error Responses

Example

Request

POST /v2/plainTextRedactors
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    },
    "markup": {
      "fileId": "vry3FPE0zQqYwhzndRccOQ"
    },
    "dest": {
      "lineEndings": "\n"
    }
  },
  "minSecondsAvailable": 60
}

Response

HTTP 200 OK
Content-Type: application/json
{
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "expirationDateTime": "2019-02-07T13:24:35.395Z",
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    },
    "markup": {
      "fileId": "vry3FPE0zQqYwhzndRccOQ"
    },
    "dest": {
      "lineEndings": "\n"
    }
  },
  "state": "processing",
  "percentComplete": 0
}

GET /v2/plainTextRedactors/{processId}

Gets the state and result of an existing plain text redactor process created by POST /v2/plainTextRedactors.

Requests can be sent to this URL repeatedly while state is "processing".

When state is "complete", the new plain text document containing the redacted document text will be made available by a new WorkFile ID in the output.fileId. See the work file API topic to find out how to download a WorkFile.

If the plain text redactor process encountered an error, the state property will be "error" and the errorCode property will contain an error code string.

Request

Request Headers

Response body

JSON object with the following properties:

• input (Object) A copy of the POST /v2/plainTextRedactors request body input object we accepted to create the plain text redactor process.
• processId (String) The id of the plain text redactor process.
• expirationDateTime (String) The date and time (in ISO 8601 Extended Format) when the plain text redactor will be deleted.
• state (String) The current state of the plain text redaction process running on the server. The following values are allowed:
  • "processing" - The plain text redaction is in progress.
  • "complete" - The plain text redaction is completed.
  • "error" - The plain text redaction returns an error.
• percentComplete (Integer) The percentage (0 – 100) complete of the plain text redaction process. The percentage will be 100 when state is "complete".
• errorCode (String) An error code string if a problem occurred during the plain text redaction process. Only present when state is "error".
• output (Object) Describes the created plain text document. Only present when state is "complete".
  • fileId (String) The ID of the new WorkFile that represents a new plain text document with redacted source document text.
• affinityToken (String) Affinity token for this plain text redactor. Present when clustering is enabled.

Error Responses and JSON Error Codes

Example

Request

GET /v2/plainTextRedactors/iFhSZRvrz2vtFjcTSi9Qlg

Successful Response

When the plain text redactor process completes with no errors:

HTTP 200 OK
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    },
    "markup": {
      "fileId": "vry3FPE0zQqYwhzndRccOQ"
    },
    "dest": {
      "lineEndings": "\n"
    }
  },
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "expirationDateTime": "2019-02-07T13:24:35.395Z",
  "state": "complete",
  "percentComplete": 100,
  "output": {
    "fileId": "eOsJIqI8aHkxVV0yJug"
  }
}

Error responses

Response when a plain text redactor process does not exist for the given processId:

HTTP 404
Content-Type: application/json
{
  errorCode: 'ResourceNotFound'
}

Response when provided markup work file cannot be parsed as JSON:

HTTP 200 OK
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    },
    "markup": {
      "fileId": "vry3FPE0zQqYwhzndRccOQ"
    },
    "dest": {
      "lineEndings": "\n"
    }
  },
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "state": "error",
  "errorCode": "InvalidJson",
  "percentComplete": 0,
  "expirationDateTime": "2019-02-07T13:24:35.395Z"
}

Response when markup JSON does not satisfy the Markup JSON Specification:

HTTP 200 OK
Content-Type: application/json
{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    },
    "markup": {
      "fileId": "vry3FPE0zQqYwhzndRccOQ"
    },
    "dest": {
      "lineEndings": "\n"
    }
  },
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "state": "error",
  "errorCode": "InvalidMarkup",
  "percentComplete": 0,
  "expirationDateTime": "2019-02-07T13:24:35.395Z"
}

Response when markup refers to a page that does not exist in the source document:

{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    },
    "markup": {
      "fileId": "vry3FPE0zQqYwhzndRccOQ"
    },
    "dest": {
      "lineEndings": "\n"
    }
  },
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "state": "error",
  "errorCode": "MarkRefersToNonExistentPage",
  "expirationDateTime": "2019-02-07T13:24:35.395Z"
}

Response when source document is a CAD file:

{
  "input": {
    "source": {
      "fileId": "ek5Zb123oYHSUEVx1bUrVQ"
    },
    "markup": {
      "fileId": "vry3FPE0zQqYwhzndRccOQ"
    },
    "dest": {
      "lineEndings": "\n"
    }
  },
  "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
  "state": "error",
  "errorCode": "UnsupportedSourceDocument",
  "expirationDateTime": "2019-02-07T13:24:35.395Z"
}