Using a connector extension, you can do many extra activities that Rossum application does not do by default, such as cross-checking sums, pairing extracted data against your database or modifying the export data to meet the needs of your external ERP system. We have published a few sample connectors on the Rossum GitHub that can help you to understand the implementation structure and functional possibilities of connector extensions. This article will provide you with information on how to set up and run your first connector. To try out the workflow on an example, you can use our Sample Python Connector.
Start the webserver on localhost by running the main connector script, for example:
$ python3 connector.py
Expose a web server on a port of your local machine to the internet, for example:
$ ngrok http 5042
A new tunnel produced by ngrok will be created with URL such as
https://123456e7.ngrok.io. You will use this address in the following step as a service URL of your connector.
Like this, every time a request will be sent from Rossum to your connector, it will be tunneled to the port 5042 on your localhost. You can test if the requests are tunneled correctly by typing the new URL to your browser and see if your request was displayed correctly in the command line where your main connector script is running.
You can use elisctl tool to configure a Rossum queue to use the connector.
Create a connector object with basic attributes:
elisctl connector create "Python Example Connector" --service-url http://hostname:5000 --auth-token wuNg0OenyaeK4eenOovi7aiF
There are two attributes that you should always assign to the connector -
The authorization token is a secret combination chosen by yourself, passed in an Authorization HTTP header as
Authorization: secret_key your_auth_token_here
This token may also uniquely identify the organization when multiple Rossum organizations share the connector running on the same URL.
service_url is your remote URL where the connector is running. In this example, it is the
Query parameters in URL
If the service URL of the connector contains query parameters, you should pass them via
params attribute of a connector object. Passing them directly in the
service_url parameter would not work.
In the response from elisctl, you will receive the ID of the connector. Next, choose an existing queue and deploy the connector to it:
elisctl queue change 29582 --connector-id 1506
Or create a new queue and attach the connector to it:
elisctl queue create "Python Connector Queue" --connector-id 1506 -s schema.json
You can also configure the connector using API.
To use the connector for production, try to follow our best practices. The connector should:
- communicate securely by running via HTTPS with a valid public certificate (using, for example, Nginx proxy with Let's encrypt TLS/SSL certificate)
- authenticate the caller to prevent impersonation by another party, by requiring Rossum side to authenticate using an authentication token; do not restrict the source IP address as that may change over time
- be fast enough to keep up the pace with Rossum interactive behavior
For more detailed information on connector extensions see our API documentation.
Updated 2 months ago