FLEXBridge DocDrop Service API Documentation

FLEXBridge FLEXBridge FLEXBridge DocDrop Service API Documentation

This document provides comprehensive technical details for the FLEXBridge DocDrop Service API, a key component of the broader FLEXBridge Document Service API. This service is designed to facilitate the secure and efficient storage of documents from external sources into a credit union’s FLEX document database.

1. Introduction to FLEXBridge Document Service API and DocDrop

The FLEXBridge Document Service API is a set of functions designed to interact with a credit union’s document database. It is available for FLEX Releases 8.04 and up, with Document Service API Version 1.80 and up.

The core functions currently available as part of the Document Service API include:

  • Search Document
  • Retrieve Document
  • DocDrop Process (Store Document)

The DocDrop portion specifically handles the process of storing documents from outside sources into the credit union’s document database. All documents stored within the FLEX system through this service are in PDF format.

2. General FLEXBridge API Information

FLEXBridge operates as a RESTful API.

  • It incorporates built-in authentication.
  • Authentication needs to be attached to every request as HTTPS request headers.
  • For details on adding authentication headers, refer to the FLEX Core System documentation.

3. DocDrop Process (Store Document) Details

The DocDrop API Service enables a third party to securely place documents into a designated Shared Folder location. These documents, along with their associated indexing information, are then added to the credit union’s document database.

For each document entry, the service requires two files:

  • A PDF file of the document.
  • A text indexing file with a .idx suffix.

3.1. Setting Up the DocDrop Process

Successful DocDrop setup requires coordination among the credit union, the third party, and FLEX.

Credit Union Responsibilities:

  • Create the Shared Folder Location that will be used for document drop-off.
  • Create all Report IDs needed for the archival process.
  • Ensure the Shared Folder location permissions allow the Linux script to read, execute, and modify files.
    • Without all required permissions, it is possible to see duplicate documents archived into the Document Manager database.

Third-Party Responsibilities:

  • Provide an indexing file (.idx) with the required FLEX attributes for each PDF document.
  • Place (drop) both the PDF and indexing files into the designated Shared Folder.
  • Ensure the PDF and indexing files have matching naming conventions (excluding the file suffix).

FLEX Responsibilities:

  • Set up and deploy the Document Drop API Service to the credit union’s FLEXBridge Server.
  • The FLEX Linux Team creates a custom script that pulls all PDF and index files from the Shared Folder location on a daily basis.

3.2. How the DocDrop Process Works

The daily DocDrop workflow relies on the third party placing documents into the Shared Folder location.

The process is as follows:

  1. Document Placement: The third party places the PDF documents and their corresponding indexing files into the Shared Folder.
  2. Daily Script Run: Each day, the custom Linux script runs.
  3. File Transfer: The script moves all items from the Shared Folder over to the credit union’s FLEXBridge server.
  4. Data Processing & Archiving: The Document Drop API Service then reads the information in the indexing file (.idx). It uses this data, specifically the reportId attribute along with other field values, to move and archive the PDF document into the credit union’s Document Manager Database.

3.3. Output Image and Index File Naming Conventions

The Document Archiving API Services does not rely on specific naming conventions assigned by the third-party to the indexing file and the PDF document.

Key requirements for file naming:

  • Matching Files: FLEX only requires that the identification (title) of the two files match, excluding the file suffix.
    • Example: document.pdf and document.idx are valid.
  • Labeling Flexibility: Files can be labeled to express an application number or to separate various types of documents.
  • Examples of Naming Conventions:
    • Loan documents labeled as Completed Loan Packet_(Loan Application number).
    • Using a unique sequencing number, such as an application number, for the label.

3.4. Indexing File (.idx) Requirements

FLEX requires a text file with a suffix label of .idx for each PDF document submitted for archiving. This indexing file must contain specific attributes for processing, with each attribute on a separate line and no delimiters.

Required Attributes:

  • reportId (String):
    • Credit union-defined value used to archive documents.
    • Maximum 10 characters.
  • reportDate (Date):
    • Date the document will be indexed under.
    • Format as MM/DD/CCYY.
  • accountNumber (Number) OR taxId (Number):
    • A document can be stored under an account number or a tax ID.
    • Maximum 9 characters for both.
    • Both accountNumber and taxId can be sent simultaneously in the indexing file without issue for additional indexing.
    • If one is sent, the other is optional.
  • tellerId (String):
    • The Teller ID to be stored with the document.
    • Maximum 4 characters.

Optional Attributes:

  • suffix (Number):
    • Suffix number to store the document under.
    • Maximum 3 characters.
    • This is the only truly optional attribute/field in the document indexing file.
  • numberOfPages (Number):
    • Number of pages in the document.
    • Maximum 3 characters.

3.5. Report ID Index Information

The Report Id attribute value is created by the credit union. It serves as the document description that FLEX uses to store the document into the credit union’s Document Database.

  • Purpose: Credit unions can create any number of Report IDs as needed for document archiving. The Report ID aids in sorting documents into searchable groups.
  • Examples of Report IDs used by other credit unions include:
    • LOANDOCS
    • MEMBDOCS
    • MBRDOCS
    • MERGDOCS
    • ADVA
    • CRDTRPTS
    • SCANDOCS

Creating a Report ID in FLEX:

  1. From the FLEX Main Menu, type “document” or “document manager”.
  2. Select the Document Manager Configuration option.
  3. Click the Add button (located directly across from the “Spool File Cross-Reference List Heading”) on the lower portion of the screen to create a new entry.
  4. Fill out the required fields and save the entry.
    • Note: FLEX refers to the Report ID as User Data.
    • The User Data field has a maximum length of 8 to 10 characters, depending on the credit union’s current FLEX Release.
  5. Optional: Create a Report Group under the “Document group” option if you want all documents from the third party to archive under a specific Report Group. This can make filtering and searching easier.

3.6. Handling Missing and Invalid Documents

The Document Drop Service is designed to handle situations where indexing attributes are missing or invalid, ensuring that PDF documents are still archived.

What Happens When Information Is Missing or Invalid?
  • If any of the required indexing attributes (reportId, reportDate, accountNumber or taxId, tellerId) are missing a value or have an invalid value, the PDF document will still be archived into the credit union’s Document Manager database.
  • The suffix attribute is the only truly optional field in the document indexing file.
  • When issues occur, the service creates a daily log report indicating any document archiving problems.
Invalid Document Log Reports
  • The DocDrop Service generates a log report that allows the credit union to check for documents that did not archive as expected each day.
  • If there is no log for a given day, it means all documents archived correctly.
  • These log reports are stored in a folder on the credit union’s server, not in the Document Manager database, due to the nature of API services.
  • FLEX recommends checking these log reports often and maintaining any documents that couldn’t archive as expected through Document Manager.
  • Documents with issues are stored under the User Data DMINVALID until adjusted by the credit union.
  • The logs will not show documents that were never shared by the third party. If a document is not archived or found under DMINVALID, the credit union should contact the third party.
  • The log specifies the reason why a document failed to archive under its expected index values. Common errors include incorrect field values for accountNumber, taxId, or tellerId (e.g., an account number exceeding 9 digits).

Locating the Log Reports:

  • Log reports are stored by year, month, and day on the credit union’s server.
  • Path: Navigate to the FLEX folder on your server, then follow the path: /flex/logs/dmimport/{YEAR}/{MONTH} (e.g., /flex/logs/dmimport/2020/01).
  • There will typically be only one log file per day containing all failed items.
How to Reindex and Reassign Documents in Document Manager

Documents may not display correctly in Document Manager because they were unable to archive correctly, often due to blank or invalid index attributes. FLEX archives these failed documents under the DMINVALID User Data in Document Manager to allow credit unions to manage them.

  • Reviewing Invalid Documents:
    • FLEX recommends reviewing DMINVALID documents often.
    • You can use the log reports generated by the service or filter for the DMINVALID User Data directly in Document Manager.
    • If filtering for DMINVALID yields no results, all documents archived correctly.
  • Correcting Invalid Documents:
    • The DMINVALID User Data is typically created in the “Work with Spool Descriptions” section.
    • FLEX usually sets up default custom indexes for DMINVALID, such as Member First Name, Member Last Name, Application Number, and Tax Id, which can be modified by the credit union.
    • Invalid documents filtered under DMINVALID can be corrected through Document Manager using the Reindex or Reassignment options.

Steps for Updating Documents in Document Manager:

  1. Navigate to Document Manager:
    • Go to Document Manager via the FLEX Main Menu.
    • Click on the “Filter” option at the top right of the screen.
    • Under the “User Data” dropdown list, select DMINVALID.
    • Select a Date Range from the dropdown options (FLEX recommends checking daily or weekly).
    • Click ‘OK’ to apply the filter.
  2. Select Reindex/Reassign:
    • Right-click on a document in the filtered list to reveal the Reindex and Reassign options.
  3. Populate Custom Indexes (Optional):
    • The Reindexing option uses Custom Indexes set up for the DMINVALID User Data.
    • By default, these include Member First Name, Member Last Name, Application Number, and Tax ID, but can be customized.
    • Click ‘OK’ to save any entered values.
  4. Reassign Document Type:
    • Select the “Reassign Document Type” option.
    • Adjust the Document Type from DMINVALID to the desired type (e.g., LOANDOCS or SCANDOCS).
    • This option also allows an Account Number or Suffix to be added or changed if incorrect or missing.
  5. Finalize:
    • Validate all selections.
    • Click ‘OK’.
    • Repeat this process for any other invalid entries until none remain.

4. Error Handling: HTTPS Status Code 500 Errors

FLEX has added additional information to the 500 HTTP Status Code errors in the API Service responses to assist with troubleshooting.

  • Troubleshooting: Once the issue that resulted in the error is corrected, the export should be attempted again.
  • Common Causes: The majority of errors through the service occur due to invalid attribute values or values that are not present in the credit union database configuration options.
  • Integrity Checks: Some HTTPS messages are triggered by preset conditions to ensure data integrity and accuracy.
  • Credit Union Resolution: FLEX recommends providing the error to the credit union, allowing them to troubleshoot most errors without FLEX or third-party aid, as credit unions are typically familiar with the messages and how to correct the data.

Common Error Message Examples:

  • {“message”: “Internal server error – The file does not exists in Document Manager”}.
    • This message indicates the document service was unable to retrieve the requested document information.
    • Review values before submitting another request.