POST https://example.com/documentprocessing/document/findandreplace

Description

Executes a find and replace on a template to create a document.

Examples

The following sample replaces all occurrences of the string "Lorem" with "test" in a given document and returns a DOCX document.

# Request:
curl --location --request POST 'https://trial.dsserver.io/documentprocessing/document/findandreplace?returnFormat=DOCX' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer GphAd1R0npJM9OuX2y9mUa4cfqPMOg6p' \
    --data-raw '{
            "findAndReplaceData": [
                [
                    "Lorem",
                    "test"
                ]
            ],
            "template": "CAcBAA4AAAAAAAA[..]",
            "mergeSettings": null
        }'

# Result:
"UEsDBBQAAAAIAAACAAC5EQAAAAADKSKHJHDuHD[..]"

Authorization

This endpoint supports the OAuth authorization method. DS Server checks the access token only when OAuth is enabled in the admin portal (see Enable OAuth). With OAuth disabled, the default of a new installation, the endpoint accepts requests without a token.

DS Server implements OAuth as the authorization method. Two flows are supported:

Authorization Code
Client Credentials

To use the Client Credentials flow, switch on Allow “Client Credentials” grant type in the security profile (see OAuth Grant Types).

In both cases, a valid access token returned from the OAuth endpoints must be passed in a Bearer Authorization Header, as a Query Parameter or in a Cookie.

Authorization Header

Header field	Description
Authorization	A Bearer authorization header (also called token authentication) contains the OAuth access token. The authorization method and a space i.e. "Bearer " is then put before your valid access token. For example: `Authorization: Bearer 4796E23054E64BC773CACBCAF24AD179DE9A3`

Query Parameter

Query parameter	Description
access_token	The access token is passed directly in the endpoint URL as a query string. For example: `?access_token=4796E23054E64BC773CACBCAF24AD179DE9A3`

Cookie

Cookie	Description
access_token	The access token is passed in a cookie named `access_token`. For example: `Cookie: access_token=4796E23054E64BC773CACBCAF24AD179DE9A3`

Request Parameters

Name	Type	Value	Optional
returnFormat	String	A string that specifies the format of the created document. Possible values are: "PDF", "PDFA", "RTF", "DOC", "DOCX", "HTML", "TX" and "TXT" (plain text). Default value is "PDF".	yes

Request Payload

Type	Value
FindAndReplaceBody	The FindAndReplaceBody object contains a JSON array of string arrays, a template encoded as a Base64 string and a MergeSettings object.

FindAndReplaceBody

Name	Type	Value	Optional
findAndReplaceData	String[][]	The find and replace pairs as a JSON array of string arrays. Each inner array holds the text to find and the text that replaces it.	no
template	Base64 encoded string	The template encoded as a Base64 string. Supported formats are RTF, DOC, DOCX and TX.	yes
mergeSettings	MergeSettings	Optional merge settings to specify merge properties and document properties such as title and author.	yes

MergeSettings

Name	Type	Value	Optional
removeEmptyFields	Boolean	Specifies whether empty fields should be removed from the template or not. Default value is true.	yes
removeEmptyBlocks	Boolean	Specifies whether the content of empty merge blocks should be removed from the template or not. Default value is true.	yes
removeEmptyImages	Boolean	Specifies whether images which don't have merge data should be removed from the template or not. Default value is false.	yes
removeEmptyLines	Boolean	Specifies whether lines should be removed that contain only empty fields and no other content. Default value is false.	yes
removeTrailingWhitespace	Boolean	Specifies whether trailing whitespace should be removed before saving a document. Default value is true.	yes
mergeHtml	Boolean	Specifies whether field data can contain formatted Html content or not. HTML content must be enclosed in an <html> tag element. Only active in the Merge endpoint. Default value is false.	yes
author	String	Sets the document's author.	yes
creationDate	DateTime (String)	Sets the document's creation date which will be saved in the document.	yes
lastModificationDate	DateTime (String)	Sets the date the document is last modified.	yes
creatorApplication	String	Sets the application, which has created the document.	yes
documentSubject	String	Sets the document's subject string which will be saved in the document. PDF limitation: The length is limited to 2000 characters.	yes
documentTitle	String	Sets the document's title that will be saved in the document. PDF limitation: The length is limited to 2000 characters.	yes
userPassword	String	Specifies the password for the user to open the document.	yes
culture	String	Specifies the culture for the merge process for date and currency values. It must be a culture name such as "fr-FR" for French or "de-DE" for German. Default value is "en-US".	yes
formFieldMergeType	Number	Specifies in which manner form fields are treated during the merge process. Possible values are: 0 = None (Form fields are not merged at all), 1 = Preselect (Form field content is preselected when possible. Form fields not associated with a data table column are unaffected) and 2 = Replace (Form fields are replaced with database content. Empty form fields are removed according to property MergeSettings.removeEmptyFields). Pass the number; a name such as "Replace" is refused with 400. Default value is 0 (None).	yes
dataSourceCulture	String	Provides a way to specify the culture which is used when parsing date and currency values from the data source in case of formatting problems (e. g. "fr-FR" or "de-DE"). If this property is not provided, the default is the server language.	yes
mergeCulture	String	Provides a way to specify the target culture which is used when formatting date and currency values during the merge process in case of formatting problems (e. g. "fr-FR" or "de-DE"). If this property is null, the default is the server language.	yes
formattingPrinter	String	Specifies the name of a printer the text dimensions and capabilities of which are used to format the document.	yes

Success Response

Status	Description
200	On success, the HTTP status code in the response header is 200 (OK). The response body contains the converted document encoded as a Base64 encoded string.

Error Response

Status	Description
401	A 401 (Unauthorized) with an empty body is returned, if OAuth is enabled and the request has no valid access token.
400	A 400 (Bad Request) is returned, if the body can't be read as a FindAndReplaceBody object. The body is a problem details object (`application/json`) with the title "One or more validation errors occurred." and the message per field in `errors`. This check comes before the license check.
415	A 415 (Unsupported Media Type) is returned, if the `Content-Type` header of a request with a body is not `application/json`.
405	A 405 (Method Not Allowed) with an empty body and the header `Allow: POST` is returned for any other HTTP method, for example `GET`.
400	A 400 (Bad Request) is returned, if no data is found in the FindAndReplaceBody object or no template is uploaded.
400	A 400 (Bad Request) is returned, if DS Server is not licensed or the license is invalid. On a server that is not registered, the body is the JSON string `"DS Server is not registered."` (`application/json`). DS Server checks the license before the parameter values, but after it has read the body and the typed query parameters.
400	A 400 (Bad Request) is returned, if the uploaded template is not valid.

POST /documentprocessing/document/findandreplace