elisctl is a set of tools for Rossum integrators that wrap the Rossum API to provide an easy way to configure and customize a Rossum account - either interactively or programmatically.
See the elisctl setup tutorial for detailed instructions.
Download an installation file from GitHub releases. Install it. And run it either from start menu or from command prompt.
Install the package from PyPI:
pip install elisctlThe elisctl library can be used to communicate with Rossum API,
instead of using requests library directly. The advantages of using elisctl:
- it contains a function that merges the paginated results into one list so the user does not need to get results page by page and take care of their merging,
- it takes care of login and logout for the user,
- in case the API version changes, the change will be implemented to the library by Rossum for all the users.
See the sample script using elisctl within a code to export the documents:
import json
import logging
from elisctl.lib.api_client import APIClient
from datetime import date, timedelta
queue_id = 12673
username = 'your_username'
password = 'your_password'
reviewed_documents = "exported,exporting,failed_export"
# This example downloads data for documents exported during the previous calendar day.
date_today = date.today()
date_end = date_today
date_start = date_today - timedelta(days=1)
def export_documents():
logging.info("Export started...")
with APIClient(context=None, user=username, password=password) as rossum:
annotations_list, _ = rossum.get_paginated(f"queues/{queue_id}/export",
{"status": reviewed_documents,
"format": "json",
"ordering": "exported_at",
"exported_at_after": date_start.isoformat(),
"exported_at_before": date_end.isoformat()})
with open('data.json', 'w') as f:
json.dump(annotations_list, f)
logging.info("...export finished.")
if __name__ == "__main__":
export_documents()The elisctl tool can be either used in a command line interface mode
by executing each command through elisctl individually by passing it as an argument,
or in an interactive shell mode of executing elisctl without parameters
and then typing the commands into the shown prompt.
Individual Rossum operations are triggered by passing specific commands to elisctl.
Commands are organized by object type in a tree-like structure and thus are composed
of multiple words (e.g. user create or schema transform).
So either get the list of commands and execute them immediately such as:
$ elisctl --help
$ elisctl configureor run the interactive shell by simply running
$ elisctlSee the sample using elisctl command line tool to create the main objects within an organization and
assign a user to a queue:
$ elisctl configure
API URL [https://api.elis.rossum.ai]:
Username: [email protected]
Password:
$ elisctl workspace create "My New Workspace"
12345
$ elisctl queue create "My New Queue Via Elisctl" -s schema.json -w 12345 --email-prefix my-queue-email --bounce-email [email protected]
50117, [email protected]
$ elisctl user create [email protected] -q 50117 -g annotator -p my-secret-password-154568
59119, my-secret-password-154568
$ elisctl user_assignment add -u 59119 -q 50117To run commands described below under a chosen user, it is possible to use profiles defined by configure function such as
$ elisctl --profile profile_name configureAfter defining necessary profiles and their credentials, the profile can be chosen the following way
$ elisctl --profile profile_name queue listSome of the most common advanced operations are related to setting up the sidebar-describing schema according to business requirements. Using elisctl you can edit schema easily as a JSON or XLSX file.
List queues to obtain schema id:
$ elisctl queue list
id name workspace inbox schema users
---- --------------------------- ----------- ---------------------------------------- -------- ----------------------
6 My Queue 1 6 [email protected] 7 27Download schema as a json:
$ elisctl schema get 7 -O schema.jsonOpen the schema.json file in you favourite editor and upload modified version back to Rossum.
$ elisctl schema update 7 --rewrite schema.jsonYou can also edit schema as an Excel (xlsx) file.
$ elisctl schema get 7 --format xlsx -O schema.xlsx
$ elisctl schema update 7 --rewrite schema.xlsxFrom now on, documents will follow new schema. (Warning! If you don't use --rewrite option,
the new schema will receive a new id - obtain it by queue list again.)
In addition, there is a scripting support for many common schema operations,
that may be easily used for schema management automation. See elisctl schema transform
and elisctl tools tools for further reference.
Run something like:
$ elisctl schema transform substitute-options default_schema.json centre <( \
elisctl tools xls_to_csv ~/Downloads/ERA_osnova_strediska.xlsx --header 0 --sheet 1 | elisctl tools csv_to_options - ) \
| elisctl schema transform substitute-options - gl_code <( \
elisctl tools xls_to_csv ~/Downloads/ERA_osnova_strediska.xlsx --header 0 | elisctl tools csv_to_options - ) \
| elisctl schema transform remove - contract \
> era_schema.jsonMIT
- Use
pre-committo avoid linting issues. - Submit a pull request from forked version of this repo.
- Select any of the maintainers as a reviewer.
- After an approved review, when releasing, a
CollaboratorwithAdminrole shall run inmasterbranch:bump2version minor git push git push --tags
- To build a Windows installer, run:
pynsist installer.cfg
- allow editing inbox attributes separately on queue-related commands
- add support for
can_collapsein xlsx schema - add sample usage of elisctl library in a Python code
- make queue option required on
user create
- Add webhook command
- Allow creating and changing inbox properties on
queue changecommand
- Improve documentation
- Add command
user_assignmentfor bulk assignment of users to queues - Change command
connector create:queue_idparameter needs to be specified, if there is more than one queue in organization - Support schema attribute
widthin XLSX schema format - Fixed: booleans, in XLSX schema format, can be specified as boolean types
- Internal: filename can be specified in
ELISClient.upload_document
- Enable passing custom filename with upload
- Add support for schema specified in XLSX when creating queue
- Remove the necessity to specify schema file type when uploading
- Fix XML and CSV formats of
elisctl document extract
- Add support for can_export in xlsx schema format
- Add document command
- Fix: annotator cannot use
elisctl connector listcommand
- Add connector command
- Update packages for windows build.
- Added support for
--profileoption to allelisctlcommands - Fix: remove extra whitespace in xlsx schema export/import
- Added support for
--output-filetoelisctl toolsandelisctl schema transform - Fix Schema Transformations description in README
- Fixed MS Windows application entry point (running elisctl from the start menu)
- Fixed parsing of boolean values in xlsx schema export/import
- Disable interpolation in config parsing, so that special characters are allowed in e.g. password
- Experimental support for schema modification using xlsx file format
- Allow to show help in schema transform add (backward incompatible change)
- Fixed bug with UnicodeDecodeError in
elisctl schema get ID -O file.jsonon Windows
- Added support for python 3.6
- Added
User-Agentheader (elisctl/{version} ({platform})) for every request to ELIS API - Improved error when login fails with the provided credentials