PrizmDoc® v14.1 Release - Updated
PrizmDoc / API Reference / PrizmDoc Server REST API / Application Development / Plain Text Redactors
In This Topic
    Plain Text Redactors
    In This Topic

    Introduction

    The plain text redactors REST API allows your application to take a source document and a redaction markup file as input and produce redacted plain text as output.

    For application development in .NET, we recommend using the PrizmDoc Server .NET SDK instead of the REST API. See the How to Create Redacted Plain Text topic in the .NET SDK documentation for an example of how to do perform plain text redaction with the .NET SDK.

    Available URLs

    URL Description
    POST /v2/plainTextRedactors Creates and starts a new plain text redactor process.
    GET /v2/plainTextRedactors/{processId} Gets the state of an existing plain text redactor process.

    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

    Name Description
    Content-Type Must be application/json
    Accusoft-Affinity-Token The affinityToken of work files specified by input.source.fileId and input.markup.fileId. Required when server clustering is enabled.

    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

    Status Code JSON errorCode Description
    480 "MissingInput" A required input value was not provided. See errorDetails in the response body.
    480 "InvalidInput" An invalid input value was used. See errorDetails in the response body.
    480 "UnrecognizedInput" An unrecognized JSON property was provided. See errorDetails in the response body.
    480 "ResourceNotFound" Source document or markup work file does not exist. See errorDetails in the response body.
    480 "LicenseCouldNotBeVerified" The server's license could not be verified. If you are evaluating the product without a license, the product is running in evaluation mode and this particular part of the product is unavailable without a license. To obtain a license, contact us at info@accusoft.com. If you have a license, make sure you configured your license correctly, that your license has not expired, and that you have not exceeded any license limits.
    580 "InternalError" The server encountered an internal error when handling the request.

    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

    Name Description
    Accusoft-Affinity-Token The affinityToken of the plain text redactor process. Required when server clustering is enabled.
    Parameter Description
    {processId} The id of the plain text redactor process.

    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

    Status Code JSON errorCode Description
    404 "ResourceNotFound" Text redactor process specified by {processId} could be found.
    200 "InvalidJson" Provided markup work file cannot be parsed as JSON.
    200 "InvalidMarkup" Provided markup JSON does not satisfy the Markup JSON Specification.
    200 "MarkRefersToNonExistentPage" Provided markup JSON refers to a non-existent page in the source document. See errorDetails in the response body.
    200 "UnsupportedSourceDocument" Provided source document is a CAD file and it is not supported.
    580 "InternalError" The server encountered an internal error when handling the request.

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