Skip to main content
Connect OTRS (or Znuny) to Oleria to see which agents can work in your help desk and the groups and roles that grant their access. With ticket agent credentials, Oleria also collects ticket history activity. A single Oleria connection covers your entire OTRS instance - Oleria discovers every agent, group, and role the connection can reach.

​
What Oleria discovers

​
Prerequisites

  • A self-hosted Znuny 6.0 to 7.3 or ((OTRS)) Community Edition 6 instance, reachable from Oleria over HTTPS. OTRS Managed (SaaS) isn’t supported, because it doesn’t allow third-party packages.
  • An OTRS administrator who can install packages and change System Configuration settings.
  • The OleriaConnector package (OleriaConnector-1.0.0.opm). Stock OTRS and Znuny have no API for agents, groups, and roles, so Oleria reads them through this package. Contact support@oleria.com to get it.
  • Optional, for ticket activity: a dedicated ticket agent login and password, and the stock GenericTicketConnectorREST web service set up on the same instance.
Use a dedicated service agent (not a named employee account) for the optional ticket agent credentials, so the integration keeps working through personnel changes.

​
Set up the integration

Oleria authenticates to the OleriaConnector web service with an API token you set in OTRS, and (optionally) uses a separate session-based login for ticket history.
1

Install the OleriaConnector package

In OTRS, go to Admin -> Package Manager and install OleriaConnector-1.0.0.opm. You can also install it from the console as the otrs user:
Installing the package creates the OleriaConnector web service. On ((OTRS)) Community Edition 6, enable Package::AllowNotVerifiedPackages first.
2

Set the API token

Create a random token of at least 32 characters, for example with openssl rand -hex 32.In Admin -> System Configuration, open OleriaConnector::APIToken, enable it, enter the token, and deploy. Until this setting holds a token of at least 32 characters, the web service rejects every request.From the console, this takes two calls, because --valid ignores --value:
Copy the token - you will enter it in Oleria.
Oleria sends the token in the Authorization: Bearer header. Znuny’s standard Apache (mod_perl) and Plack setups pass it through. If OTRS runs as plain CGI, add CGIPassAuth On to the /otrs location so Apache hands the header to OTRS.
3

Allow changes (optional)

Only if you want Oleria to run remediation actions: in Admin -> System Configuration, turn on OleriaConnector::AllowWrite and deploy. Without it, the web service is read-only and remediation actions fail.
With OleriaConnector::AllowWrite on, the token can create agents and grant any group permission, including admin. Protect it like an administrator password.
Keep the OleriaConnector web service’s debugger at error (the default). At debug, OTRS’s GenericInterface log stores request data, including the initial password of agents Oleria creates.
4

Create a ticket agent for activity (optional)

If you want Oleria to collect ticket activity, create (or designate) an agent that can sign in with a login and password, and make sure the GenericTicketConnectorREST web service is set up on the same instance. Oleria signs in to that web service with a session; it doesn’t use the API token.
Ticket agent login and password are optional and independent of the API token. Provide both together or leave both blank - a login without a password (or vice versa) is rejected.

​
Connect OTRS to Oleria

1

Open the integration

Go to your Oleria workspace, select Integrations -> select OTRS.
2

Complete the connection form

Select Continue and fill in the connection form:
3

Save the integration

Select Authenticate to validate and save the integration.

​
Verify the integration

Confirm OTRS appears on the Connected tab of your Oleria Integrations page. After the first sync completes, you can review the discovered agents, groups, and roles in your Oleria workspace. If ticket agent credentials were provided, ticket activity appears alongside them.

​
Remediation actions

All actions need OleriaConnector::AllowWrite turned on in OTRS.

​
Known limitations

  • Activity is optional: ticket history requires the optional ticket agent credentials. Without them, Oleria still collects agents, groups, and roles normally.
  • Group hierarchy is inferred from group naming conventions, not a native OTRS parent/child relationship.
  • No dynamic tenant discovery: one connection maps to exactly one OTRS instance.
  • No bulk operations: remediation actions operate on one agent at a time.
  • No group-scoped roles: OTRS roles are assigned instance-wide, not per group.
  • OTRS Managed (SaaS) isn’t supported: it doesn’t allow third-party packages, so the OleriaConnector package can’t be installed.
  • Changes are recorded as user ID 1: in OTRS, changes Oleria makes appear as made by the initial administrator account.

​
Contact us

For questions about this integration, contact us at support@oleria.com.