File Download Endpoint(POST)

File Download Endpoint(POST)

Initial Preparation

File Download Endpoint is accessed through the url {{baseURL}}/CSSAPI/V2/Files/{{entityName}}/Download

• baseURL – your company’s ContractInsight URL
• entityName – name of the database table

The HTTP request type is POST. Content type for this request is set to applications/json.

Introduction

File Download Endpoint is designed to allow clients to download files associated with an entity. Things to keep in mind when making calls to UPDATE Endpoint:

1. You can only download one file at a time.
2. Request format for this endpoint is the same as for GET Endpoint. Except, field collection needs to be empty. Adding fields into collection might produce errors.
3. OrderByTag and GroupByTag must be empty or skipped. Setting those properties to any values will cause REST API not able to execute the query and an exception will be returned.
4. StartIndex and Length attributes will be ignored.
5. In case when the Clause is written in a way that produces multiple files to be pulled from database, REST API returns first file it pulls from the table.
6. Clause with rules is required to execute the query
7. Successful response is of multipart/form-data format. It is composite: binary file and JSON object containing Contract ID, FileType, and FileName properties. 

Request Format

Since OrderByTag, GroupByTag, StartIndex, and Length properties are not needed, they can be skipped.

Response

1. Successful response is of multipart/form-data format. Response has two parts (highlighted are special delimiters called boundaries)
   1. Response of type application/octet-stream. Contains actual file bytes.  
   2. Response of type application/json that contains an object describing the file
2.   Failed response varies depending on the error (no standard response is available)

More on Failed Response

1. When the clause criteria are syntactically correct, but the file is not found/pulled, the error may look like this:

2. Adding fields

1. If the field list includes the one holding actual file, error shown in previous example will be returned
2. If the field list doesn’t include the one holding actual file, the following error will occur:

3. When you attempt to configure OrderByTag and GroupByTag, an exception will be returned that is similar to the one below:

Downloading the file with Postman

When testing the endpoint with Postman, we will be getting response in the format described above. If we want to download the file, we need to expand the “Send” button and select “Send and Download” option:

When the request runs successfully, you will be prompted to save the file on your machine:

File Download Endpoint in Action

Task 1: Download file based on file name (partial file name)

In this example, we are downloading file from tblContractFiles

{

    "Fields": [

    ],

    "Clause": {

    "condition": "AND",

    "rules": [

        {

            "id": "FileName",

            "field": "FileName",

            "type": "int",

            "input": "text",

            "operator": "contains",

            "value": "test"

        }

    ],

    "valid": true

}

}

[{"ID":3,"FilePath":null,"ContractID":2,"EmployeeID":335,"Keywords":"","FileType":".docx","EntryDate":"2022-10-17T14:02:18.443","FileName":"test.docx","LastCheckedOutTo":0,
"LastCheckedOutDate":null,"CheckedOutTo":0,"DocVersionNumber":1,"IsDeleted":0,"ExtractedText":null,"IsPublic":"Internal",
"ExRefID":null,"DocType":"","FileCategoryID":0,"DirectURL":"http://localhost:8081//ViewFile.aspx?ID=3&tbl=Cont","ContractFileGUID":"268306A7-2BA0-4F6A-B834-567D8E6D7136","FileDirectoryGUID":"BA7951DD-3D13-4C63-BC3C-9AD65F317B2C","PageOCRStatusID":0,"PageOCRStatus":"",
"IsVirusScanned":false,"IsPotentialVirus":false,"IsOCRComplete":0,"OCRFileID":0,"DateUpdated":"2022-10-17T14:02:18.443","FileSizeBytes":11990,"TextExtract":null,"IsCategoryExtractComplete":false,"CategoryExtractDate":null}]

Task 2: Download a File associated with a particular contract ID

Here, we are downloading a file without specifying file name or ID. The file is associated with a contract with ID of 2. Please Note that when the Clause produces more than one returned record, the first file will be returned.

{

    "Fields": [],

    "Clause": {

        "condition": "AND",

        "rules": [

            {

                "id": "ContractID",

                "field": "ContractID",

                "type": "integer",

                "input": "number",

                "operator": "equal",

                "value": "2"

            }

        ],

        "valid": true

    }

}

}

[{"ID":1,"FilePath":null,"ContractID":2,"EmployeeID":335,"Keywords":"","FileType":".docx","EntryDate":"2022-10-14T14:35:54.387","FileName":"Requirements.docx",
"LastCheckedOutTo":0,"LastCheckedOutDate":null,"CheckedOutTo":0,"DocVersionNumber":1,"IsDeleted":0,"ExtractedText":null,
"IsPublic":"Internal","ExRefID":null,"DocType":"",
"FileCategoryID":0,
"DirectURL":"http://localhost:8081//ViewFile.aspx?ID=1&tbl=Cont","ContractFileGUID":"4E65AF6A-4EB8-4EAE-8750-C41422595F1F","FileDirectoryGUID":"BA7951DD-3D13-4C63-BC3C-9AD65F317B2C","PageOCRStatusID":0,"PageOCRStatus":"","IsVirusScanned":false,
"IsPotentialVirus":false,"IsOCRComplete":0,"OCRFileID":0,"DateUpdated":"2022-10-14T14:35:54.387","FileSizeBytes":55317,"TextExtract":null,"IsCategoryExtractComplete":false,"CategoryExtractDate":null}]

--bf28e5b7-8c45-4e42-b17f-0b42b5d61818--