Advanced Settings of Extensions in Rossum

When creating a new extension in Rossum, function or webhook, you may want the extension to perform more advanced behavior that might need extra setup. Such advanced setup might need access to:

• Metadata of extra objects such as username, name of the queue, etc.
• Access to the Rossum's API - when you need to update some object over the API
• Passing extra configuration to the Rossum extension

See the image below in order to find out what advanced settings can be set for an extension.

Passing extra metadata information to the extension

You might want to pass more information to the webhook / custom functions notifications. Such metadata could include:

• Username of the user who updated the annotation
• Taking the fields name from the Extraction schema when analyzing the user updates online in your custom extension.
• Queue name on which the document was updated

Such extra metadata can be enabled on the extension detail in the Rossum's UI.

Enabling access to the Rossum's API from the extension

In some cases you might want to access the Rossum's API from the custom extension. Such cases might include:

• Setting metadata of the annotation over the API
• Accessing the Data matching database over the API
• Getting the annotation content over the API, e.g. after you get notification about the status change of a specific annotation.

In each of the scenarios above, you need to access the Rossum's API from the extension. However, you do not want to hardcode your username and password into the extension code. A better practice is to tell Rossum to pass the authentication token as part of the notification payload. Afterwards, you can reuse the token for accessing the Rossum's API.

Passing extra configuration to the extension

In most cases you would like to maintain one webhook or custom function code for all your customers. However, usually such customers need to have slightly different configuration of the business logic. Therefore, we have enabled passing of extra configuration to the extension.

Secrets

Rossum provides a secure way to store sensitive information in your custom serverless function. This feature is called "Secrets" and is accessible through both the user interface and the API. You can find more information about it here: https://elis.rossum.ai/api/docs/#hook-secrets.

When using Secrets, you can only write information into the vault. There is no way to retrieve the values directly, except within the payload during the function's runtime execution.

{
  "request_id": "8acf581b-bcf2-4b1b-a1b9-5918f17fa9b5",
  "timestamp": "2023-07-24T11:03:12.055028Z",
  "hook": "https://elis.rossum.app/api/v1/hooks/xxx",
  "action": "initialize",
  "event": "annotation_content",
  "rossum_authorization_token": "[redacted...]",
  "base_url": "https://elis.rossum.app",
  "settings": {},
  "secrets": {
    "password": "[redacted...]",
    "username": "[redacted...]"
  },
  "document": {
    "id": xxx,
    "url": "https://elis.rossum.app/api/v1/documents/xxx",
    "s3_name": "[redacted...]",
    "parent": null,
    "email": null,
    "mime_type": "application/pdf",
    "creator": "https://elis.rossum.app/api/v1/users/xxx",
    "created_at": "2023-05-31T16:19:37.661547Z",
    "arrived_at": "2023-05-31T16:19:37.661547Z",
    "original_file_name": "[SAMPLE]_tax_invoice_eu_2.pdf",
    "content": "https://elis.rossum.app/api/v1/documents/xxx/content",
    "attachment_status": null,
    "metadata": {}
  },

If you need to make changes to the Secrets schema, you can do so by patching the hook object using the request described here: https://elis.rossum.ai/api/docs/#update-part-of-a-hook.
Consider updating the default schema to improve visibility within your custom function. Once you patch the secrets schema, you will be able to see keys that can be directly updated through the user interface. Remember that if you don't make any changes to the schema, the previously stored secrets will remain unaffected.

Here is an example of how to call the update hook endpoint for modifying the Secrets schema:

PATCH {{domain}}/v1/hooks/{{hook_id}}
Authorization: Bearer {{TOKEN}}
Content-Type: application/json


{"secrets_schema":
{
"type": "object",
"properties": {
"username": {
"type": "string",
"description": "Target system user"
},
"password": {
"type": "string",
"description": "Target system user password"
}
},
"additionalProperties": false
}
}