Installation and Usage of The Kina Listener

Installation and Usage Of The Kina Listener


The Kina Listener is a software application that provides Kina users with the ability to automatically send files to Kina and receive files from Kina. It “listens” to a local folder or network share drive for documents to appear, transmits those files to Kina via HTTPS, and once processing is completed, the Listener will retrieve documents according to specified criteria and place them in a folder in the client’s environment. Additionally, once the documents have been retrieved from Kina, the listener can optionally call a local Javascript component that can perform further processing, such as loading the received structured information in a client system, and placing the document in a locally accessible content repository.
It is downloaded from the software-and-resources page.

Platform Availability

The Listener application currently is available for Windows, Linux and Macintosh operating systems.

Installing the Listener In Your Environment

Installation is straightforward. Download the appropriate zip file for the platform you plan to install it on. Once the download has completed, copy the zip file to the location where you wish to install it and unzip the contents. In Windows and the Macintosh environments, double click the file and follow the extraction rules. In Linux you can use the unzip command from the shell, or use if in a windowing environment such as Unity, double-click on the zip file. Make appropriate shortcuts and links to the installation suitable for the environment it is installed in.

Once the zip file has been expanded into the appropriate location, the Kina Listener is ready to be started. At this point it is installed.

Note for Linux Users: you will need to make sure your installed environment can connect to an X11 server for this graphical application.

To uninstall the Listener, simply delete the folder it has been installed in.

Logging In

To log in to Kina via the Listener, provide your user name (which is your registered email address) and your password on the top portion of the Listener window. Click Login to connect to Kina. To automatically login to the Kina platform when the Listener starts, check the Automatically login option.

Once you have successfully logged into Kina, you will see a Connected status message in the upper left hand side of the window. The connected username will be listed below.


The listener is configured in the main window which appears upon launch. There are four sections, accessible by four tabs. Each section is responsible for a particular purpose, such as sending, receiving, security and general settings. The tabs are explained in the following sections.

Sending Documents To Kina

Figure 1: The Send Tab of the Kina Listener

The first tab is the Sending tab which allows you to configure what local or shared folder the Kina Listener will scan for files to send to Kina. To select which folder will be scanned (or listened to), click the Scan Folder button (identified by 1 on the image above). Once selected, a green OK will appear indicating that the setting has been configured successfully.

Once files are sent to Kina, they need to be removed from the Scan Folder. To move the files upon a successful send, click (2), the Sent Folder button, and select where you want the files to be placed after a successful upload to Kina.

ImportantIf you do not configure the Sent Folder setting, the files will be removed from the folder identified as the scan folder once they have uploaded to Kina for processing.

The Upload Profile setting controls which Upload Profile is used to send the files to Kina. Upload Profiles tell Kina which flow to initiate with each transmitted file, as well as any metadata elements are variables that you might want to pass along, such as a business_process_name that can be used in downstream processing within Kina.

Note that the upload profiles won’t populate until you login to Kina and the Listener can retrieve the available profile set. Once they have been retrieved, you will be able to choose which profile to use with this Listener installation.

Finally, the area marked 4 in the image above is where the recent transmission history is shown. A log file is configured in the Settings tab.

Receiving Documents From Kina

Figure 2: The Receive Tab of the Kina Listener

Once documents are in a Complete status within Kina, they are ready to be downloaded to your environment or sent to a downstream cloud service such as Amazon S3 or for storage. The Kina Listener enables the automatic pickup of ready documents and the placement in your local environment. Documents cannot be directly downloaded from a queue with the Listener as they are not in a complete status. The Listener will only download completed download documents that have an empty disposition status. A documents disposition status can be determined by the Disposition column in the Operate->My Active Work screen within the Kina platform once you have logged in. Similar to an email client, the Listener will only pick up documents that are owned by the user id that has been configured to log into the listener.

The Receiving tab is used to configure what completed documents will be retrieved from Kina and where they will be placed. To select which folder the received documents will be placed in, click the Storage Folder button (1) and select the appropriate folder. Once that has been selected, the Listener will validate and place a green OK next to the entry.

The Use Profile (2)drop down selection indicates what Packaging Profile will be used to package the documents for download and placement into your environment. Packaging Profiles are configured on the Kina platform in the Define->Process and Queue Designer. Once there, select Packaging on the left hand side menu.

In certain cases, you may want to selectively download certain types of documents to different locations in your local environment. You can configure a Listener installation to only pick up files with a specific Grouping ID. The Grouping ID can be set in your process flows or once files have been completed or if they are in a queued state.

Once files have been retrieved by the Kina Listener, a Javascript trigger (4) can be called that can act on the received files and their structured data and metadata. The Set Javascript button enables you to call a Javascript function that can make calls to internal content repositories, web services or other resources with the retrieved Kina content. The Kina Listener can generate a documented stub file that you can build upon. To do so, click on the Generate Stub button and a Javascript file will be created that you can access and expand as needed. If the Javascript function returns a value, this value is returned to Kina and sent as the archive_uri and stored in the archived document’s metadata.

Received files and the information pertinent to the received files are shown in the lower portion of the window (5). This area keeps a running list of the most recent received files.


Figure 3: The Security Tab of the Kina Listener

The Security tab allows you to provide your private key and passphrase to the Listener which is required to receive work with Kina. Transactions are stored in an encrypted state, and in order to access them (and download them), your private key and pass phrase is required.

To get your security keys, login to Kina on the computer you normally access the Kina platform with. The first time you log into the tool, it will prompt you to generate your key set and passphrase. To access these keys click on your user name in the upper right hand corner of the Kina application (not the Listener) and click on the Security tab. Click Get Keys as Zip and your browser will create a ZIP file with your keys and passphrase.

Important: Drag the ZIP file itself to the Security tab and drop it on the Listener. This action will install the correct keys into the Listener.

In top to bottom order, (1) displays your pass phrase, and (2) is your private key. Press Save (3) to store your keys in the Listener for use with Kina.


Figure 4: The Settings Tab

The Settings tab provides basic configuration of the Listener as well as the version number of the Listener instance. This allows you to change the Kina Server (1). The default is usually used, unless you have an on-premises installation, whereby you would set it to the URL of your local Kina instance.

The Log File setting tells the Kina Listener where to write a log file of it’s activities. This helps with debugging connectivity or validating receipt and sending activities as well as debugging any Javascript triggers you may have installed in the Receiving tab. To write a log file, set the directory using the Log Folder button.

In the Windows environments, you can also use Powershell to launch the Listener and watch the output in real time, or use the Get-Content command to follow a running instance. In the following example the log file is in the Desktop folder:

Get-Content .\Desktop\kinalistener.log -wait

In Linux and MacOS, you can use the tail command:

tail -f ~/Desktop/kinalistener.log

This will allow you track in real time detailed information about the Listener’s activities.