PrizmDoc® Viewer v13.27 Release - Updated
PrizmDoc Viewer / API Reference / PrizmDoc Server REST API / Application Development / Redaction Creators
In This Topic
    Redaction Creators
    In This Topic

    Introduction

    The redaction creators REST API allows your application to automatically create redaction definitions for a document based on a given set of text-matching rules.

    For application development in.NET, we recommend using the PrizmDoc Server.NET SDK instead of using the PrizmDoc Server REST API directly. See the How to Create a Redacted PDF topic in the.NET SDK documentation for an example of how to easily create redactions from a set of Regular Expression rules.

    A redaction creator takes as input a source document and a set of text-matching regular expressions and produces as output a markup JSON file (or, if using the deprecated endpoints, a markup XML file). The output markup can then be used with the markup burners REST API to “burn” the redactions into a document.

    Available URLs

    URL Description
    POST /v2/redactionCreators Creates and starts a new redaction creator process.
    GET /v2/redactionCreators/{processId} Gets the state of an existing redaction creator process.

    Deprecated URLs

    URL Description
    POST /PCCIS/V1/RedactionCreator Creates and starts a new RedactionCreator.
    GET /PCCIS/V1/RedactionCreator/{processId} Gets the state and result of an existing RedactionCreator.

    POST /v2/redactionCreators

    Creates and starts a new redaction creator process.

    A redaction creator represents a process that runs on the server which searches a document for text fragments matching specified rules and then, based on any matches, creates a new JSON Markup document containing redaction markup. The redaction markup that is created by this process can be used with the markup burner API to "burn" the redactions into a document.

    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/redactionCreators/{processId} URL below to get the state and results of an in-progress or completed redaction creator process.

    There are two required inputs to create a RedactionCreator:

    • One is a WorkFile object that represents the source document whose text will be searched, and
    • One or more rules to match and redact the document text.

    See the work file API topic for more information about a WorkFile.

    A new markup document will be created that will contain the redaction markup. The new document will be made available by a new WorkFile ID.

    Request

    Request Headers

    Name Description
    Content-Type Must be application/json
    Accusoft-Affinity-Token The affinityToken of the work file specified by input.documentFileId. Required when server clustering is enabled.

    Request Body

    JSON object conforming to the following:

    • input
      • source (Object) Required. Describes the document for which the markup will be created. This document will not be modified.
        • fileId (String) Required. The ID of the WorkFile that represents the source document whose text will be searched.
      • rules (Array) Required. The list of rules, each containing a Regular Expression to match the text and markup properties for any matches.
        • find (Object) Required. Describes the way to find matching text in the document.
          • type (String) Required. Must be "regex". The type of the text match algorithm.
          • pattern (String) Required, when type is "regex". The Regular Expression to match within the source document text using a POSIX extended RE (ERE) or basic RE (BRE) syntax.
          • newLineHandling (String) Describes how to treat the new line characters \n in the source document:
            • "spaces" - (Default) Replaces new line characters with spaces upon text search. This allows you to use a pattern of "one two" instead of "one\ntwo" to find a match on the previous and the next text line (the case when the matched words are split between two lines).
            • "newLines" - Leaves new line characters as is. The regex pattern should include new line character(s) to be able to search for the text that may be split between lines.
        • redactWith (Object) Required. Describes how to redact matching text.
          • type (String) Required. Must be "RectangleRedaction". Type of redaction to be created for the matching text.
          • reason (String) Reason the content was redacted, displayed in the center of the redaction annotation.

            NOTE: Only one of "reason" or "reasons" properties can be specified for a specific rule.

          • reasons (Array of strings) Reasons the content was redacted, displayed semicolon space separated in the center of the redaction annotation.

            NOTE: Only one of the "reason" or "reasons" properties can be specified for a specific rule.

          • fontColor (String) Color of the text specified as a 6-character hexadecimal color string with a leading # sign. For example, a value of "#FF0000" will create red text. Default is "#FFFFFF".
          • fillColor (String) Color of the redaction background specified as a 6-character hexadecimal color string with a leading # sign. For example, a value of "#FF0000" will create a red background. Default is "#000000".
          • borderColor (String) Color of the border specified as a 6-character hexadecimal color string with a leading # sign. For example, a value of "#FF0000" will create a red border. Default is "#000000".
          • borderThickness (Integer) Thickness of the border in pixels. Should be greater than 0. Default is 1.

            NOTE: Large borderThickness values may create borders which visually hide content from neighboring redacted text, however, this content will not be removed from the document during burning.

          • data (Object) A property bag of user-defined values. Property values are only allowed to be strings.
    • minSecondsAvailable (Integer) The minimum number of seconds this markup creator will remain available so you can GET its status. 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 redaction creator process.
    • expirationDateTime (String) The date and time (in ISO 8601 Extended Format) when the RedactionCreator will be deleted.
    • state (String) The current state of the redaction creation process running on the server. This will always be "processing" in this response.
    • percentComplete (Integer) The percentage (0 – 100) complete of the redaction creation process. This will always be 0 in this response.
    • affinityToken (String) Affinity token for this search context. 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 "InvalidInputCombination" An invalid combination of JSON properties 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 work file does not exist.
    580 "InternalError" The server encountered an internal error when handling the request.

    Example

    Request

    POST /v2/redactionCreators
    Content-Type: application/json
    {
      "input": {
        "source": {
          "fileId": "NmFzioyWzFM5ADpthsuitw"
        },
        "rules": [{
            "find": {
              "type": "regex",
              "pattern": "wat"
            },
            "redactWith": {
              "type": "RectangleRedaction"
            }
          },
          {
            "find": {
              "type": "regex",
              "pattern": "[0-9]{3}[-]?[0-9]{2}[-]?[0-9]{4}"
            },
            "redactWith": {
              "type": "RectangleRedaction",
              "borderColor": "#FF0000",
              "fillColor": "#FF0000",
              "fontColor": "#000000",
              "reason": "Redacted",
              "data": {
                "author": "John Smith",
                "phone": "+1 123 456 789"
              }
            }
          }
        ]
      }
    }
    
    

    Response

    HTTP 200 OK
    Content-Type: application/json
    {
      "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
      "expirationDateTime": "2019-02-07T13:24:35.395Z",
      "input": {
        "source": {
          "fileId": "NmFzioyWzFM5ADpthsuitw"
        },
        "rules": [
        {
            "find": {
              "regex": "wat"
            },
            "redactWith": {
              "type": "RectangleRedaction"
            }
          },
          {
            "find": {
              "regex": "[0-9]{3}[-]?[0-9]{2}[-]?[0-9]{4}"
            },
            "redactWith": {
              "type": "RectangleRedaction",
              "borderColor": "#FF0000",
              "fillColor": "#FF0000",
              "fontColor": "#000000",
              "reason": "Redacted",
              "data": {
                "author": "John Smith",
                "phone": "+1 123 456 789"
              }
            }
          }
        ]
      },
      "state": "processing",
      "percentComplete": 0
    }
    
    

    GET /v2/redactionCreators/{processId}

    Gets the state and result of an existing redaction creator process created by POST /v2/redactionCreators.

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

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

    If the markup burning 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
    Content-Type Must be application/json
    Accusoft-Affinity-Token The affinityToken of the work file specified by input.documentFileId. Required when server clustering is enabled.

    URL Parameters

    Parameter Description
    {processId} The id of the redaction creator process.

    Response body

    JSON object with the following properties:

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

    Error Responses and JSON Error Codes

    Status Code JSON errorCode Description
    404 "ResourceNotFound" Redaction creator process specified by {processId} could not be found.
    200 "MarkupCreationError" The server encountered an error when creating the markup.
    580 "InternalError" The server encountered an internal error when handling the request.

    Example

    Request

    GET /v2/redactionCreators/iFhSZRvrz2vtFjcTSi9Qlg
    
    

    Successful Response

    When the redaction creator process completes with no errors:

    HTTP 200 OK
    Content-Type: application/json
    {
      "input": {
        "source": {
          "fileId": "NmFzioyWzFM5ADpthsuitw"
        },
        "rules": [
        {
            "find": {
              "regex": "wat"
            },
            "redactWith": {
              "type": "RectangleRedaction"
            }
          },
          {
            "find": {
              "regex": "[0-9]{3}[-]?[0-9]{2}[-]?[0-9]{4}"
            },
            "redactWith": {
              "type": "RectangleRedaction",
              "borderColor": "#FF0000",
              "fillColor": "#FF0000",
              "fontColor": "#000000",
              "reason": "Redacted",
              "data": {
                "author": "John Smith",
                "phone": "+1 123 456 789"
              }
            }
          }
        ]
      },
      "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
      "expirationDateTime": "2019-02-07T13:24:35.395Z",
      "state": "complete",
      "percentComplete": 100,
      "output": {
        "markupFileId": "eOsJIqI8aHkxVV0yJug"
      }
    }
    
    

    Error responses

    When a redaction converter process does not exist for the given processId:

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

    When source document is corrupted and Markup can not be created:

    HTTP 200 OK
    Content-Type: application/json
    {
      "input": {
        "source": {
          "fileId": "NmFzioyWzFM5ADpthsuitw"
        },
        "rules": [
        {
            "find": {
              "regex": "wat"
            },
            "redactWith": {
              "type": "RectangleRedaction"
            }
          },
          {
            "find": {
              "regex": "[0-9]{3}[-]?[0-9]{2}[-]?[0-9]{4}"
            },
            "redactWith": {
              "type": "RectangleRedaction",
              "borderColor": "#FF0000",
              "fillColor": "#FF0000",
              "fontColor": "#000000",
              "reason": "Redacted",
              "data": {
                "author": "John Smith",
                "phone": "+1 123 456 789"
              }
            }
          }
        ]
      },
      "processId": "iFhSZRvrz2vtFjcTSi9Qlg",
      "state": "error",
      "errorCode": "MarkupCreationError",
      "percentComplete": 0,
      "expirationDateTime": "2019-02-07T13:24:35.395Z"
    }
    
    

    POST /PCCIS/V1/RedactionCreator

    NOTE: This URL has been deprecated and will be removed from the public API in a future release. Please use the newer POST /v2/redactionCreators instead.

    Creates and starts a new RedactionCreator.

    A RedactionCreator represents a process that runs on the server which searches a document for text matching a Regular Expression and then, based on any matches, creates a new Markup XML document containing redaction markup. The redaction Markup XML that is created by this process can be used with the markup burner API to "burn" the redactions into a document.

    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 /PCCIS/V1/RedactionCreator/{processId} URL below to get the state and results of an in-progress or completed RedactionCreator process.

    There are two required inputs to create a RedactionCreator:

    • One is a WorkFile object that represents the source document whose text will be searched, and
    • One or more Regular Expressions to match the document text.

    See the work file API topic for more information about a WorkFile.

    A new Markup XML document will be created that will contain the redaction markup. The new document will be made available by a new WorkFile ID.

    By default, RedactionCreator objects will be automatically deleted 20 minutes after they are created.

    Request

    Request Headers

    Name Description
    Content-Type Must be application/json
    Accusoft-Affinity-Token The affinityToken of the work file involved in the input to the process. Required when server clustering is enabled. Providing this value is important to ensuring the process will execute on the machine where the input work files actually exist.

    NOTE: If you do not provide the required Accusoft-Affinity-Token, the POST itself will succeed but the process itself will likely fail.

    Request Body

    In the request body, provide JSON containing the following properties:

    • input (Object) Input to create the RedactionCreator.
      • documentFileId (String) Required. The ID of the WorkFile that represents the source document whose text will be searched. This document will not be modified.
      • autoRedactionRegularExpressions (Array of strings) Required. The Regular Expressions to match within the source document text. Multiple Regular Expressions provided in the array will be concatenated into a single Regular Expression using the format: "(regex1)|(regex2)…|(regexN)".
    • minSecondsAvailable (Integer) The minimum number of seconds which this RedactionCreator must remain available. If not provided, a configurable default value is used. This value is ignored if it is shorter than the configurable value.

    Response Body

    If successful, this method returns JSON containing the following properties:

    • input (Object) Input we accepted to create the RedactionCreator.
      • documentFileId (String) The ID of the WorkFile that represents the source document whose text will be searched. This document will not be modified. This is an echo of what was passed in by the request.
      • autoRedactionRegularExpressions (Array of Strings) The Regular Expressions to match within the source document text. This is an echo of what was passed in by the request.
    • expirationDateTime (String) The date and time (in ISO 8601 Extended Format) when the RedactionCreator will be deleted.
    • processId (String) The ID of the RedactionCreator.
    • state (String) The current state of the markup burning process running on the server. This will always be "processing" in this response.
    • percentComplete (Integer) The percentage (0 – 100) complete of the redaction creation process. This will always be 0 in this response.
    • errorCode (String) An error code string if a problem occurred during the markup burning process. This will always be null in this response.
    • output (Object)
      • markupFileId (String) The ID of the new WorkFile that represents the new redaction XML markup. This will always be null in this response.
    • affinityToken (String) Affinity token for this search context. Present when clustering is enabled.

    Error Responses

    Status Code Description
    400 Bad Request, if input.documentFileId, input.autoRedactionRegularExpressions is missing or invalid format, or if minSecondsAvailable is not a number.
    405 Method Not Allowed, if POST HTTP method is not used.

    Examples

    Request

    POST prizmdoc_server_base_url/PCCIS/V1/RedactionCreator
    Content-Type: application/json
    Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=
    
    {
        "input": {
            "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ",
            "autoRedactionRegularExpressions": [
                "[0-9]{3}[-]?[0-9]{2}[-]?[0-9]{4}"
            ]
        },
        "minSecondsAvailable": 60
    }
    
    

    NOTE: See the Base URL for PrizmDoc Server topic for more information.

    Response

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "input": {
            "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ",
            "autoRedactionRegularExpressions": [
                "[0-9]{3}[-]?[0-9]{2}[-]?[0-9]{4}"
            ]
        },
        "expirationDateTime": "2014-12-17T20:38:39.796Z",
        "processId": "ElkNzWtrUJp4rXI5YnLUgw",
        "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
        "state": "processing",
        "percentComplete": 0,
        "errorCode": null,
        "output": null
    }
    
    

    GET /PCCIS/V1/RedactionCreator/{processId}

    NOTE: This URL has been deprecated and will be removed from the public API in a future release. Please use the newer POST /v2/redactionCreators and GET /v2/redactionCreators/{processId} instead.

    Gets the state and result of an existing RedactionCreator.

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

    When state is "complete", the new markup XML document containing redactions will be made available by a new WorkFile ID in the output.markupFileId. See the work file API topic to find out how to download a WorkFile.

    If the markup burning process encountered an error, the state property will be "error", the errorCode property will contain an error code string and output will be null.

    Request

    Request Headers

    Name Description
    Content-Type Must be application/json
    Accusoft-Affinity-Token The affinityToken of the work file specified by input.documentFileId. Required when server clustering is enabled.

    URL Parameters

    Parameter Description
    {processId} The id of the process.

    Response Body

    If successful, this method returns JSON containing the following properties:

    • input (Object) Input we accepted to create the MarkupBurner.
      • documentFileId (String) The ID of the WorkFile that represents the source document whose text will be searched. This document will not be modified.
      • autoRedactionRegularExpressions (Array of Strings) The Regular Expressions to match within the source document text.
    • expirationDateTime (String) The date and time (in ISO 8601 Extended Format) when the RedactionCreator will be deleted.
    • processId (String) The ID of the RedactionCreator.
    • state (String) The current state of the redaction creation process running on the server. The following values are allowed:
      • "processing" - The redaction creation is in progress.
      • "complete" - The redaction creation is completed.
      • "error" - The redaction creation returns an error.
    • percentComplete (Integer) The percentage (0 – 100) complete of the redaction creation process.
    • errorCode (String) An error code string if a problem occurred during the redaction creation process.
    • output (Object)
      • markupFileId (String) The ID of the new WorkFile that represents a new XML Markup document specifying the redactions.
    • affinityToken (String) Affinity token for this search context. Present when clustering is enabled.

    Error Responses

    Status Code Description
    404 Not Found, if {processId} does not exist.
    405 Method Not Allowed, if GET HTTP method is not used.

    Examples

    Request

    GET prizmdoc_server_base_url/PCCIS/V1/RedactionCreator/ElkNzWtrUJp4rXI5YnLUgw
    Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=
    
    

    NOTE: See the Base URL for PrizmDoc Server topic for more information.

    Response when the state is "processing"

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "input": {
            "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ",
            "autoRedactionRegularExpressions": [
                "[0-9]{3}[-]?[0-9]{2}[-]?[0-9]{4}"
            ]
        },
        "expirationDateTime": "2014-12-17T20:38:39.796Z",
        "processId": "ElkNzWtrUJp4rXI5YnLUgw",
        "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
        "state": "processing",
        "percentComplete": 0,
        "errorCode": null,
        "output": null
    }
    
    

    Response when the state is "complete"

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "input": {
            "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ",
            "autoRedactionRegularExpressions": [
                "[0-9]{3}[-]?[0-9]{2}[-]?[0-9]{4}"
            ]
        },
        "expirationDateTime": "2014-12-17T20:38:39.796Z",
        "processId": "ElkNzWtrUJp4rXI5YnLUgw",
        "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
        "state": "complete",
        "percentComplete": 100,
        "errorCode": null,
        "output": {
            "markupFileId": "vry3FPE0zQqYwhzndRccOQ"
        }
    }
    
    

    Response when the state is "error" because the work file that represents the source document whose text will be searched could not be found

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "input": {
            "documentFileId": "ek5Zb123oYHSUEVx1bUrVQ",
            "markupFileId": "aQ1BdViqmUisBuevJKO9Sw"
        },
        "expirationDateTime": "2014-12-17T20:38:39.796Z",
        "processId": "ElkNzWtrUJp4rXI5YnLUgw",
        "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=",
        "state": "error",
        "percentComplete": 0,
        "errorCode": "DocumentFileIdDoesNotExist"
    }