Kina

Using Extraction Instructions with Kina

Leave a comment

Introduction

This document is about getting started with using Kina to extract information.  We have tried to make it as easy as possible to be able to extract complicated tables and forms.  Kina performs this work based on natural language instructions, which look like operational procedures.   The instruction text, known as Extract Instruction Language (EIL), itself reads as standard English, and is designed for use by non-technical users, both for writing it, as well as for reading it.  This allows for quickly gaining an understanding of what is occurring on a particular document and serves as a means of describing to Kina how to find and extract information.  EIL provides a rapid way to create extractions and can be a powerful tool to extract the information you need from a document.

For example, in the following, one can fairly quickly determine what the system is being asked to do:
On the page entitled "Bill of Material", collect the field "Style Number".
In the above example the system will look for the word style number and place it in the document record.

Here is another more comprehensive example.
On page 1, collect fields "Style #", "Division", "Department", Season, Year, "Create Date", "Revise Date", "Product Type", "Size Scale", "Sample Size", "Size Category", "Prod Type".
Find text "Prod Desc". Move right 1 inch. Collect cell as "product_description".

As you can see, it is fairly quick to tell the system what to collect, and generally, where to collect it. Similar to operational procedures used in organizations, an auditor or a reviewer should easily be able to determine what information came from what location on a document.


Writing Instructions For Kina

To give you a way to flex your knowledge, there is a sample practice document that the below examples are from.  In order to get started, go to Operate -> Process Sample Purchase Order.  This will submit and process a purchase order called “Purchase Order – Kina Sample” which should complete in a few seconds.  Make sure you are in the Panel view.  To get to the panel view, hover your mouse over the button that looks like as follows:

If a tool tip appears that says  “Change Layout to a Side Panel Display”, click it.  This will take you to the panel view.    If the tooltip says “Change Layout to a Table Display”, you are in the correct location.

Open the document by clicking on the column that has an element with the document name.  This will open the document in the viewer to the right.  Once the document has opened, click the “Structure” tab.  Here, you are able to tell Kina what to do when it sees this document.

Procedures

At the highest level, a list of instructions is called a procedure.  A procedure is simply a list of instructions in sentence and paragraph form that tell Kina what to do.  For each document type within Kina, you can define a procedure as to what to do.  Kina will follow the procedure for each page in the document.  You can tell Kina in the document’s procedure what to pay attention to on what page of the document.  In many cases, depending on the page, there may be different instructions on what to specifically do.  A procedure contains instructions, formatted in sentences and paragraphs.  There are a few formatting rules that are important to Kina, because they help the system appropriately interpret what to do. They are as follows, and follow the written English rules as much as possible. Like operational instructions, each phrase will be interpreted in sequence, allowing a chain of events to occur.

Sentences and Paragraphs

Each sentence is an instruction or sequence of instructions. Sentences follow each other, and keep the “context” of the prior sentence. In the above example in the Introduction, each sentence uses the prior sentences ending context to continue, similar to how one reads a set of instructions. Using the example:
Find text "Invoice #". Move down 0.5 inches. Collect area as "invoice_number".
Kina will perform the following:

  1. Will search the current page for the text Invoice #.
  2. IF the text Invoice # if found, Kina will then move down 1/2 an inch.
  3. IF the move succeeds, will collect the text in the area 1/2 inch below the Invoice # and place it in the invoice_numberdocument field.

The three sentences in the last example constitute a Paragraph, and each sentence uses the last for it’s context as to where it is and how to proceed. If any of the sentences in the paragraph fail, Kina will break out of the paragraph and not continue, otherwise unpredictable results will occur.

New Lines

If a sentence is followed by a single newline (one enter key press), the current focus is reset to the entire page. This is useful because, once a particular operation succeeds, the current focus will be in a particular region or small area of the page.

If a sentence is followed by a double newline, the current “page filter” resets. In this way you can tell Kina what operations to do on each page. For example, in the following paragraphs:

On page 1, set line tolerance to “0.4”. Collect fields “Style #”, “Division”, “Department”, Season, Year, “Create Date”, “Revise Date”, “Product Type”, “Size Scale”, “Sample Size”, “Size Category”, “Prod Type”.
Find text “Prod Desc”. Move right 1 inch. Collect cell as “product_description”.

On pages entitled “(BOM)”, add horizontal line at (0.208 0.278 0.4 0.1). Go to (0.09, 0.28, 0.001, 0.001). Collect cell as “style_name”. Remove text. Move right 0.5 inches. Move down 0.02 inches. Place text “Material”. Move up 0.5 inches. Place text “Header”. Add vertical line at (0.040 0.253 0.1 0.8). Remove lines at (0.329 0.315 0.07 0.8). Select table materials.

In the above example, there are two “paragraphs”. In the first paragraph, sentences one and two build on each other. Then there is a single line break, with a 3 more sentences, starting with
Find text “Prod Desc”.This sentence still only applies to page 1, but starts back at the whole page, vs using the last area of focus, which would be the area of the “Prod Type”field.

Then there are two line breaks. This causes the current page condition to reset, and any text found will not be subject to theOn Page 1 clause. Instead, a new page condition is created for any pages that have the text (BOM) that looks like a title or header. If Kina determines this to be the case as it is processing a document, then it will follow the paragraph instructions, starting with adding a horizontal line at a location on the screen.

Page Conditions

Page conditions are simply statements, like the ones above, that begin paragraphs and provide a condition for following those instructions. In general, start paragraphs with an appropriate page condition. Page conditions are not necessary. If a paragraph doesn’t have a page condition, then those instructions will be followed on every page of the document.

That sums up the basics of using the EIL mechanism with Kina. In addition to the above there are more advanced constructs to provide control flow, but these will be covered later.

Using References

References are values that have been “remembered” as part of the current procedure being followed.  They allow you to refer back to a piece of information that may be necessary for the current instruction.  For example, you may want Kina to refer back to a total sum, and validate the determined sum against the remembered total sum.  Another example: if information is laid out in a tabular form, and the first row is the column headers, you can reference the column headers in order to name each record in the subsequent rows.   For many extractions references aren’t really needed, as Kina is just collecting information and placing them in a record.  However, in more advanced scenarios, references can be a crucial tool for building procedures.

A reference can be defined in the following way.
Set reference ship_to="John Doe".
Set reference ship_to=:value.

Or using the shorter “let”:
Let ship_to="John Doe".
Here is an example, in which a cell’s content is collected and placed in the ship_to variable. However, since we don’t want the SHIP TO: text as part of the cell, we only “keep” the part of the value after the :.  To perform an operation on a reference, use the using keyword, or proceed the reference name with a $ symbol, as in $ship_to.  In this case we snipped the SHIP TO: from the reference ship_to.  The special word :value always contains the last value (or set of values) that were collected as part of the last instruction.  In this case the instruction is Collect cell, which places the text found in the current area into the :value reference. For example:

Find the words "SHIP TO:". Collect cell. Set reference ship_to=:value. Using ship_to keep after :.
To use a reference’s value (and not otherwise change it like above), refer to it with a : in from of the name, such as
:ship_to
.

Here is another example.   In this case, we are remembering a location on the page, and returning to it later in the procedure.  The special word :area always contains the last area of focus on the page.
Let start_position=:area.
We have now stored the current area of focus in the reference :start_position.  Later on in our procedure, we need to reference it, perhaps to go back there and move to another position relative to it.  So we can say:
Go to :start_position.
There are 3 things to remember with references.

  1. They are created with the terms “Set reference” or “Let“.  When they are created do not place a : in front of the name.
  2. The values they refer to are accessed by placing a : in front of their name as in :start_position.
  3. They can be modified by the using keyword or the $ symbol prior to the name of the reference.  Do not place a : in front of the name in this scenario, since you do not want the value the reference refers to, but the reference itself.

References are only remembered for the current procedure.  You cannot refer to references across pages, unless they are stored as a record in the transaction and then recalled.  For example on page 1, you may collect the invoice number, and you may want to refer to the invoice number on every page.  To do this, prepend document/ to the right side of the equals sign:
let invoice_number=document/invoice_number
This will pull the invoice_number field stored in the document transaction into the invoice_number reference.

So we might collect the invoice_number as follows:
On page 1, find field "Invoice #:" as invoice_number.
and refer to it on subsequence pages as:
let invoice_number=document/invoice_number.
References can hold numbers, texts, arrays, areas and dictionaries.


Phrases and Instructions

This section lays out the instructions that constitute EIL. EIL strives to be as naturalistic as possible in terms of expression. This allows a more free-flowing range of words and grammar that matches the context of the instruction.

 

1. Page Conditions

To set up a page condition, start a sentence or paragraph with the words:

  • On page
  • On pages
  • For page
  • For pages

The immediate words following the above can be:

  1. A single number, such as 1
  2. A range, such 1-3
  3. An instruction such asentitled,with the title,find title
  4. Or an instruction that will succeed or fail, such as find the word,find the words, etc

 

Examples:
On page 2, collect fields “Address” and “Phone”.On pages entitled “Specifications”, select the table named “Measurements”.

 

2. Finding Information On A Document.

A field is defined as a label/value pair on the document.   The field is usually identified by a label, and then, typically, to the right or below, a value to be associated with that label.  The following would be considered valid fields:

In the above, John Smith is the value for the Name: label, and John is the value for the First Name and Smith is the value for the Last Name label.  Notice that colons are not necessary and that positional characteristics are used to discern where the label starts and the value starts.

To gather the above, tell Kina:

Collect fields "Name", "First Name", "Last Name".

They will be placed in the document values “name“, first_name and last_name respectively.  By default, Kina looks to the right of the label to discern the value, but sometimes, the values are below the labels.  To collect those values, first tell Kina:
Values are below labels. Find fields "Invoice #", "Client Order Number".
To switch back, use the phrase:Values are right of labels.
Once you have collected values, you will want to store them in your Kina transaction, so you can send the information to your downstream systems as structured data.  Let’s say we want a record called invoice_header, and we want to extract the client order number (the referenced purchase order).
Collect field "client order number" as po_number and place it in invoice_header.
Collect "invoice #" as invoice_number and place it in invoice_header.

A record will be created called invoice_header.  It will contain two fields, client_order_number:
invoice_header={
"po_number"=12345,
"invoice_number"=03922
}

Now, forms and documents aren’t always laid out so nicely.  Sometimes you will have to specify in more depth how to collect fields.  Here is a more in depth extraction for a purchase order:
On page 1, find the words "ISSUE DATE". Move down 0.2 inches. Collect cell as issue_date and place in document.
Find the words "SHIP TO:". Collect cell. Set reference ship_to=:value. Using ship_to keep after :. Using ship_to append ", ". Move down 0.5 inches. Collect cell. Set reference ship_to_1=:value. Using ship_to append :ship_to_1 and save value as ship_to and place in document.
Find the word "SHIPVIA", move down 0.2 inches and collect cell as ship_via and place in document.
Find the word "PROCESS", move down 0.2 inches and collect cell as process and place in document.
Find the phrase "CNXL DATE", move down 0.2 inches and collect cell as cancel_date and place in document.
Find the phrase "P/O NUMBER", move down 0.2 inches and collect cell as po_number and place in document.
Find the phrase "PAY TERMS", move down 0.2 inches and collect cell as payment_terms and place in document.
Find the phrase "EARLIEST SHIP DATE", move 0.2 down inches, collect cell as earliest_ship_date and place in document.
Go to [0.460 0.045 0.414 0.10] and find the word "RN#:". Move right 0.25 inches, expand area by 2, and collect area as rn_number and place in document.
Go to [0.460 0.045 0.414 0.10] and find the exact word "CA#". Move right 0.25 inches, expand area by 2, and collect area as ca_number and place in document.

Above you can see, you can fairly explicit in terms of how to describe to Kina what to do.  The last few sentences contain the phrase “Go to […]”.   The phrase “Go to” tells Kina to move the active area, or “cursor”, to the position described by the numbers between the brackets.  Do not worry, you don’t have to come up with those numbers yourself.   In the following section, we will learn about locations and how to define them.

Let’s use the example document that we initiated at the beginning of this document for the following section.  Click the Location Icon on the Structure tab:

Then double click the upper left hand point of your area on the document, and double click the lower left hand point.  The coordinates are copied into the clip board.  Paste them into your extraction language text at the correct location.  The pasted text will be the brackets [] and the determined coordinates.  The coordinates are in percentages, ranging from 0 to 1.  The format of the location structure is [x y width height], where x signifies the offset from the left hand side of the page and y signifies the offset from the top of the page.  [0.0 0.0 1.0 1.0] means the full page.  [0.0 0.0 0.5 0.5] is the upper left hand corner.  [0.0 0.0 1 0.5] is the top half of the page and [0.5 0.0 1 0.5] is the bottom half of the page.

Above, the term “cursor” was mentioned.  The cursor represents the active page location where Kina is focused on data extraction.  Similar to a cursor on your screen, it moves about the page.  The cursor starts with a full page scope, meaning the active area is the entire page.  However, this is not always what you want.  You will sometimes want to change the position (x,y) and limit the width and height to a specific location.   The Go to phrase accomplishes this.

Let’s say our cursor is presently initialized and has a full page scope.  Our goal is to collect the address of a vendor.  We search for a word with the phrase, “Find the word Vendor:”, and it is found on the document.  The cursor has moved to the following location:

The red rectangle over the word Vendor: is the location of the cursor.  The cursor has a position on the document: an x,y and width and height.   Our goal is to collect the address though and not the vendor.  So we need to move our cursor over to the right and expand it a bit to make sure we cover the area we care about.  To do this, we can use the move and expand area phrases.
Move right 1 inch. Expand area down 3.8 times. Expand area right 2.5 times.
Now our cursor looks like this:

Finally, we can collect the data underneath the cursor using the phrase:
Collect area as vendor_address.
That’s great for non repeating things.  But sometimes, you’ll have a document, or form, that you need to repeat steps over and over from different places on the page or document.   Depending on the circumstances, there are a few things you can do.

Let’s say we have the following, and we need to extract the table data for SKUs, quantity, unit cost, and total cost.

There are multiple ways to do this with Kina.  In this example, we are going to use the EDL to collect the table as a loop.  First we need to anchor to the table, or find it on the document with our cursor.   Since we know that in this document, the table always begins with SKU.  However, it is a short word, and due to how fuzzy search works in Kina, we may want to use something a little longer instead.  So, we will anchor to the term Currency, above the SKU.  Since this is a form, we are not too worried about it changing.
Find word "Currency:".
We can even be more specific, telling Kina to look in a specific place in the document, using go to:
Go to [0.032 0.206 0.314 0.100] and find the word "Currency:".

Next let’s move the cursor down to the table:
Move down 0.75 inches.
Now we are positioned where we want to be:

Note that our cursor doesn’t have to be covering the whole SKU to collect the value.  You just need to make sure that the cursor is covering the upper-left hand corner of the word, in this case 013104489222.  The entire value will be collected up to the end of the word.

Now we need to collect all the row’s values and place them in a record.  How can we accomplish this?

Let’s slide across the row and create a record.  So continuing with our paragraph:
Collect area as SKU and place it in line_items. Move right 1 inch. Expand area right 3.0 times and collect area as description and place it in line_items. Move right 1 inch and chop area left by 1.5 and collect area as quantity and place it in line_items. Move right 1 inch and collect area as unit_cost and place it in line_items. Move right 1 inch and collect area as total_cost and place it in line_items.
Now we have a record defined in line_items.  We have three rows in this table, but sometimes we may have more and sometimes less.  We need to be able to dynamically collect fluctuating rows.  Let’s get to that next:
Go to [0.032 0.206 0.314 0.100] and find the word "Currency:". Move down 0.75 inches. Until done do:
Collect area as SKU and place it in line_items.
  Move right 1 inch. Expand area right 3.0 times and collect area as description and place it in line_items.
  Move right 1 inch. chop area left by 1.5 and collect area as quantity and place it in line_items.
  Move right 1 inch and collect area as unit_cost and place it in line_items.
  Move right 1 inch and collect area as total_cost and place it in line_items.
  Mark record complete.
  Move left 5.5 inches. Move down 0.2 inches.
  Break on success when area is empty.
End block.

If you look above we used the
Until done do:
phrase, which creates a loop condition.  The statements which are looped are between thedo:and theEnd block.

Similar to a typewriter, once Kina reaches the right hand side of the page, it moves back 5.5 inches and down 0.2 inches.  Then, if the area in the cursor is empty, meaning no text within it, it breaks out of the loop.  Having an empty space isn’t necessarily a “complete” condition, so if we did not place this, Kina would continue trying to collect records until the end of the page, or an error condition is encountered, at which point it would consider itself “done” and leave the loop.   Notice how the instructions seem to be more in a list form vs. the standard paragraph form.  In a loop block, statements on a new line do not reset the cursor to the full page view.  This is because the loop performs a repeating action, and reverting to a whole page makes it much more difficult to accomplish an extraction in this mode.  Additionally, having the whole loop in one long paragraph makes it difficult to interpret.  Intuitively, a list of items makes it much more understandable to an auditor or a review, similar to a list of bullets.

So now we have collected all the information on the document.  The whole extraction for this document is as follows:
Collect field "PO Number".
Collect field "Order Date" and place it in document.
Find the word "Vendor:". Move right 1 inch. Expand area down 3.8 times. Expand area right 2.5 times. Collect area as vendor_name_and_address and place it in document.
Go to [0.032 0.206 0.314 0.100] and find the word "Currency:". Move down 0.75 inches. Until done do:
  Collect area as SKU and place it in line_items.
  Move right 1 inch. Expand area right 3.0 times and collect area as description and place it in line_items.
  Move right 1 inch. chop area left by 1.5 and collect area as quantity and place it in line_items.
  Move right 1 inch and collect area as unit_cost and place it in line_items.
  Move right 1 inch and collect area as total_cost and place it in line_items.
  Mark record complete.
  Move left 5.5 inches. Move down 0.2 inches.
  Break on success when area is empty.
End block.

Now, see if you can add the field cancellation date to your extract.

 

Leave a Reply

Your email address will not be published. Required fields are marked *