Submissions Overview

A submission is a set of files uploaded together for processing. The system interprets each file as a page, matches it to existing layouts, and groups it into documents based on these matches. The submission keeps the files, processing status, and results together.

Submissions and cases

Submissions and cases group content for different purposes:

• A submission groups the files assigned to one processing record.

• A case groups related content according to a business process, even when that content arrives in different submissions.

For example, a customer might send documents for one mortgage application on two different dates. Hyperscience creates a separate submission for each arrival, but a case can group the content under one Case ID. For more information, see Cases.

Submission lifecycle

A flow defines how Hyperscience processes a submission. A typical document processing flow moves a submission through the following lifecycle:

1. After the files are uploaded, Hyperscience creates the submission, assigns its Submission ID, and starts the selected flow.

2. The system prepares each supported source file for processing and creates its pages.

3. The system classifies the pages and groups them into documents according to the flow.

   • If Hyperscience cannot classify a page automatically, a keyer classifies it in a Document Classification Task.

   • Pages that are not assigned to a document remain unmatched. For more information, see Matching Pages to Layouts.

4. The system identifies and transcribes fields and tables.

   • When confidence is below the applicable Threshold, Hyperscience sends the work to Supervision.

   • The system can also send a sample of results to Quality Assurance (QA). For more information, see Supervision and QA Introduction.

5. The system completes processing and makes the submission output available to downstream systems.

Submission processing

Stage and Flow Run Status describe different parts of this lifecycle. Use both values to understand whether processing is active and where the submission is in the flow.

Stages

The Stage value shows where a submission is in its flow. The Submissions table and the Status card on the Submission Output page show this value. The stages depend on the configured flow. For more information, see Document Processing Flow.

Flow Run Status

Flow Run Status shows the state of the top-level flow run that processes the submission. It is separate from Stage and does not summarize the status of related flow runs.

If a flow run fails or is canceled, the submission keeps the last stage it reached. Use Flow Run Status to determine whether processing is running, completed, failed, or canceled. Use Stage to determine where processing is active or where it stopped. For more information, see Flow Runs Page.

Accepted file types

Hyperscience supports the following file types for submission processing:

Restrictions and processing notes

• Document conversion — Hyperscience converts DOC, DOCX, XLS, XLSX, HTM, and HTML files to PDF before it creates pages. The conversion can change the output, so use another supported format when output consistency is important.

• Encryption and passwords — Encrypted files and password-protected ZIP archives are not supported.

• Email attachments — Hyperscience processes the attachments of EML and MSG files. You can turn off attachment processing for EML files. For more information, see Process EML file attachments.

• Unaccepted file types — Hyperscience does not create pages from files of other types. A submission created through the API with no accepted files fails with the 400 error “No valid documents supplied”.

• Training data — You can upload any accepted file type as training data in Training Data Management (TDM). Training data imported from a ZIP file must contain only PNG, JPEG, TIFF, PDF, HEIC, or HEIF files; the import rejects archives that contain other file types.

Create a submission

You can create a submission by uploading files in the Hyperscience application or by sending them through the API. Input connections, such as folder and email listeners, also create submissions automatically. For more information, see Overview of Integration Capabilities.

Turn on Submission Upload

To upload files in the application, the Submission Upload setting must be turned on:

1. Go to Administration > System Settings.

2. In the General section, click Edit on the Submission Upload card.

3. Set Submission upload to Enabled.

4. Click Save.

When the setting is on, the Submissions page includes the Create Submission button.

Upload files in the application

1. Go to Submissions > Submissions.

2. Click Create Submission.

3. Add your files. Drag them into the upload area, or click the upload area and select the files.

4. If you upload multiple files, select how to submit them:

   • Single Submission creates one submission that contains all uploaded files.

   • One Submission per file creates a separate submission for each uploaded file. For example, uploading five files creates five submissions.

5. Click Next.

6. Select the flow that processes the submission from the Flow drop-down list.

7. Optionally, configure the submission:

   • Select a layout. This option applies to Semi-structured documents only.

   • Select Add to an existing case or Create a new case to add the submission to a case. For more information, see Cases.

   • Turn on Machine Extract Only to process the submission without human review. This option does not change how the files are grouped into submissions.

8. Click Upload.

Automation and Accuracy

Processing a submission with Machine Extract Only can reduce accuracy. For more information, see Accuracy.

Hyperscience creates the submission and lists it on the Submissions page.

Create a submission through the API

To create a submission through the API, authenticate your user and send a POST request to /api/v5/submissions. The files included in the same request belong to the same submission. The request has one required parameter, which depends on the encoding:

• file for multipart/form-data and application/x-www-form-urlencoded encoding. The parameter accepts either a file as multipart/form-data or a string that defines the path of a file to retrieve and include in the submission. The prefix before :// in the path defines the storage type where the file resides. For the supported storage types, see Supported File Stores for Submission in the API documentation.

• files for application/json encoding. For each file, the parameter accepts one of the following JSON objects:

  • An object with the keys file_content_base64, which accepts Base64-encoded file data as a plain string or a data URI, and filename, which contains the file name.

  • An object with the key file_url, which accepts the URL of the file. The file must be one of the accepted file types.

You can add other parameters to the request, such as the flow, a layout, an external ID, or metadata. For more information, see the Submission Creation API documentation.

Submission tracking

Hyperscience assigns a Submission ID when it creates a submission. Use this ID to open the submission, monitor its processing, and retrieve its output.

You can also provide the following tracking information when you create a submission through the API:

• External ID — A unique identifier from an external system. Use it to search for the submission and retrieve its results.

• Metadata — User-defined JSON data for external tracking. Metadata belongs to the submission, not to an individual document, and Hyperscience does not use it to process the submission.

A submission also records its processing context, including the flow and Top-Level Flow run that process it. If your organization uses processing deadlines or SLAs, the submission can also have a processing deadline (goal_time in the API). For more information, see Prioritizing Submissions.

Submission actions and data lifecycle

Actions taken after creation affect a submission in different ways:

For instructions to cancel, resubmit, or delete submissions, see Submissions Page.

Submissions page

Use the Submissions page to find, monitor, and manage submissions. For information about its tabs, filters, actions, and columns, see Submissions Page.

Submission Output page

The Submission Output page provides the content, results, and processing history associated with a submission. Depending on the flow and the processing outcome, it can include:

• Source-file information and original files

• Documents and document folders

• Extracted fields and tables

• Unmatched pages

• Rejected documents

• Cases associated with the submission's pages

• External metadata

• JSON output and transformed output

• Processing activity

For more information, see Submission Output Page.