PDFScout Inspector Partner Integration Documentation

Owned by Eric Niday
Last updated: Jun 19, 2024
7 min read

The Scout PDF Inspector is a crucial component in the EPR Partner API, ensuring all uploaded documents meet predefined standards before entering the plan review process. It checks for issues like file corruption, invalid filenames, excessive file size, and unreadable pages. By preemptively identifying these issues, Scout significantly reduces errors and rejections during the review phase, streamlining the workflow and enhancing the overall efficiency and reliability of the document management process.

Introduction

This document provides comprehensive guidance for integrating the PDFScout Inspector with your permitting software and citizen access portal. This integration ensures that all files submitted for plan review meet the necessary standards and will pass the upload process without issues.

Overview

PDFScout Inspector is a tool that validates and inspects PDF files against predefined criteria. It is designed to be integrated into permitting software's backend systems and citizen access portals to preemptively catch any issues with submitted PDF documents.

Key Links

Prerequisites

Before starting the integration process, ensure you have:

  • Access to the PDFScout API.

  • Necessary API credentials (username and password).

  • Postman installed for testing API endpoints.

  • Sample PDF documents for testing.

Base URL of Scouts

USA UAT Scout: https://scout-api.uat.eplansoftreview.com/

USA Production Scout: https://scout-api.eplansoftreview.com/

Canada UAT & Production Scout: https://scout-canada.eplansoftreview.com/


Configuration of Scout

To modify the configuration settings for the PDFScout Inspector, follow the base URL. It is essential to refer to the Configuration documentation to understand what settings can and should be modified and which ones should remain unchanged to ensure optimal functionality. Proper configuration helps tailor the PDF inspection process to your requirements while maintaining compliance with overall system standards.

 

Postman Collection

The provided Postman collection is designed to facilitate comprehensive testing of the PDFScout Inspector integration. It includes pre-configured API calls and environment settings to streamline authentication, file uploads, and result retrieval. Using this collection, you can easily simulate and verify each step of the document inspection workflow, ensuring your integration meets all requirements.

:

Integration Steps

1. Authentication

First, authenticate to get the token required for subsequent API calls.

Request

POST {{url}}/api/auth Content-Type: application/x-www-form-urlencoded username=xxx password=xxx

Response

{ "status": "success", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }

2. Get Upload URL

Retrieve the URL where you will upload your PDF file.

Request

GET https://scout-api.eplansoftreview.com/api/uploadUrl?filename=portfolio.pdf token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

 

Response

{ "success": true, "message": "Use the method and url to upload file to Scout server.", "data": { "method": "PUT", "url": "https://eplan-scout.s3.us-west-2.amazonaws.com/xxxx", "contentType": "application/pdf", "filename": "portfolio.pdf", "filePath": "1718806418789portfolio.pdf" } }

Upload your PDF file to the URL obtained in the previous step.

Request

PUT https://upload-url.eplansoftreview.com/upload/xyz Content-Type: application/x-www-form-urlencoded file: <your-pdf-file>

 

Response

200 Success

4. Retrieve Scout Results

Get the results of the PDF inspection to see if the document passed or failed the checks.

Request

POST https://scout-api.eplansoftreview.com/api/scout token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Content-Type: application/x-www-form-urlencoded filePath: 1718806418789portfolio.pdf

 

Response: Success

{ "success": true, "data": { "filename": "1718806824206portfolio.pdf", "filesize": 1480878, "numPages": 7, "outlines": null, "results": [ { "key": "accessible", "success": true, "value": null, "message": "File is accessible", "rejectIfFailed": true }, { "key": "version", "success": true, "value": "1.6", "message": "PDF version is compatible", "rejectIfFailed": true }, { "key": "attachment", "success": true, "value": null, "message": "File has no attachment", "rejectIfFailed": true }, // more results ] } }

Response: Fail

{ "success": false, "data": { "filename": "1718806824206portfolio.pdf", "filesize": 1480878, "numPages": 7, "outlines": null, "results": [ { "key": "accessible", "success": true, "value": null, "message": "File is accessible", "rejectIfFailed": true }, { "key": "version", "success": true, "value": "1.6", "message": "PDF version is compatible", "rejectIfFailed": true }, { "key": "attachment", "success": true, "value": null, "message": "File has no attachment", "rejectIfFailed": true }, { "key": "signature", "success": false, "value": "File has no digital signature", "message": "File has no certified digital signature", "rejectIfFailed": true }, // more results ] } }

 

Failure Logic and Error Handling

When processing the results of the PDF inspection, each item in the results array can have a success value of true or false. Items with rejectIfFailed set to false do not affect the overall result but can be presented as warnings.

Example

{ "key": "signature", "success": false, "value": "File has no digital signature", "message": "File has no certified digital signature", "rejectIfFailed": true }

Reason for Failure: File has no digital signature, file has no certified digital signature.

Accessibility Check

If the file fails the accessibility check because it is password protected or corrupted, it triggers a different handling logic since it cannot be accessed for further checks.

Example of Accessibility Failure

{ "success": false, "data": { "filename": "1718807180180portfolio.pdf", "filesize": 809141, "numPages": 0, "results": [ { "key": "accessible", "success": false, "value": "This file is password protected." } ], "isPassed": false } }

Default Rejection Issues

  • Accessible: Invalid files, corrupt, or password-protected PDFs.

  • Filename: Invalid characters in the filename.

  • Size: Files exceeding 400 MB.

  • Page Count: Files exceeding the maximum page count (default is 500 pages).

  • Page Access: Unreadable pages.

Default Warning Issues

  • Metadata: Hidden content and unexpected metadata.

  • Rotation: Mixed page orientations.

  • Annotations: Annotations appearing in the PDF reader’s comment panel.

Refer to the Scout Inspector Tool documentation for more details on each issue and how to resolve them.

Testing

Refer to the Scout Test Plan for comprehensive steps and details on testing your integration. This includes creating a permit application, uploading sample test documents, and verifying the results.

Conclusion

Following these steps ensures seamless integration of the PDFScout Inspector into your system, helping to maintain the integrity and compliance of all submitted documents. For any further assistance, consult the provided links or contact support.

Need Help?

For support and inquiries, reach out to:
Channel Partner - Scott Garner sgartner@eplansoft.com
Integration Manager - Eric Niday eniday@eplansoft.com
General Support - support@eplansoft.com

Related articles