Quickstart

This guide shows you how to use the basic emtellisplit client to submit data for processing to the emtellisplit engine.

Prerequisites

1. A trial or license agreement from us to use the API
2. An emtellisplit API account with the correct permissions allowed by our support team.
3. A username and password along with an IAM URL, and/or an API key created by yourself or our support team.
4. The emtellisplit API URL to which you’ll be submitting your reports. The URL will be something like this https://<your-prep-endpoint>/
5. AWS S3 bucket(s) or Azure blob storage container(s) and corresponding access credentials, given to you by your own support team, for your input files and output files. The credentials must grant read, write, and list object access. (OPTIONAL) Temporary credentials (STS for AWS, SAS token for Azure) may also be used, but generating them is outside the scope of this client’s functionality.

Step 1. Download the emtellisplit client

Download the latest emtellisplit client package here.

Extract the zip file.

unzip /path/to/emtellisplit-client-1.3.12.zip

Step 2. Install the emtellisplit client

Check the Prep client system requirements.

Optionally create a virtual environment and then install the Prep client.

python3.10 -m venv venv
source venv/bin/activate
pip install emtellisplit-client-1.3.12-py3-none-any.whl

The emtellisplit-client should now be installed. Check by printing out the client version number as follows:

emtellisplit-client --version

Step 3. Configure the emtellisplit client

Set up the following in a .toml file. Note: by default the client reads from ./emtellisplit-client-config.toml when the config file path is not specified.

[server] # the API server, and user credentials
emtellisplit_url = 'http://localhost:8421'
iam_url = 'https://iam' # if using user/pass
[server.credentials]
api_key = 'replace' # if using the api key authentication method
username = 'username'
password = 'password'
[cloud_storage] # the cloud object storage details to read/write emtellisplit input/outputs
cloud_provider = 's3' # or azure
input_bucket = 'emtellisplit-user-input'
output_bucket = 'emtellisplit-user-output'
[cloud_storage.credentials.s3] # required with these fields if s3 provider
aws_access_key_id = "replace"
aws_secret_access_key = "replace"
#aws_session_token = 'youneedtogeneratethis'
[cloud_storage.credentials.azure] # required with these fields if azure provider
account_name = "emtellisplituser"
account_primary_access_key = "replace"
#sas_token = 'youneedtogeneratethis'
[processing]
operations = ['split', 'ocr', 'ep']
[processing.split]
sections = true
nosplit = false
[processing.ocr]
output_txt = true
[processing.ep]
[processing.ep.ep_rollup]
subject_id = "Isaac"
subject_dob = "1996-02-30"

Please make sure that you test that your cloud object storage account works and your API key is accepted by the specified Prep server.

Step 4. Process a Document

We will now process this report example-data/sample.pdf by calling the emtellisplit-client as follows, assuming you have the client config file in the same directory as where you are using emtellisplit-client

First, upload a file to your input bucket with the appropriate extension. This can be done using your cloud object storage’s web interface, command line, or using emtellisplit-client.

emtellisplit-client \
   upload-file \
      --object-key sample_in_cloud.pdf \
      --file-path example-data/sample.pdf

There will now be a file called sample_in_cloud.pdf inside your cloud object storage that can be processed.

emtellisplit-client \
    process \
    sample_in_cloud.pdf

Which will process the document using the API server (creating a job identifier) and produce outputs inside your output cloud object storage. The types of output files and their contents will depend on the processing options specified in the client configuration. See processing options.

The outputs will have the following structure

<job_id>/<original_document_stem>/...

For the example, if the API server created a job_id of fccb1b7993a34de3838338c02f42a99f, all outputs would be prefixed with

fccb1b7993a34de3838338c02f42a99f/sample_in_cloud/

For more advanced usage and description of processing options, see advanced usage.