Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

Python wrapper for OTRS (using REST API)

Project description


|version| Build Status Coverage Report Docs Build Status MIT licensed python: 2.7, 3.4, 3.5, 3.6, 3.7, 3.8

PyOTRS is a Python wrapper for accessing OTRS (Version 5, 6, 7) using the (GenericInterface) REST API.


Please upgrade PyOTRS to at least version 0.7.1 if you are using OTRS 6.0.27, 7.0.16 or newer. See issue 27 and issue 29 for more details.

OTRS has introduced a new API in version 8 and with this also changed the API endpoint from “Session::SessionCreate” to “AccessToken::Create”. At the moment PyOTRS does not support OTRS v8. See issue 28 for progress and discussions.


Access an OTRS instance to:

* create a new Ticket
* get the data of a specific Ticket
* search for Tickets
* update existing Tickets
* access as a "Customer User"

Some of the most notable methods provided are:

* Client.session_create (Use credentials to "log in")
* Client.ticket_create
* Client.ticket_get_by_list  (takes a list)
* Client.ticket_get_by_id  (takes an int)
* Client.ticket_search
* Client.ticket_update

More details can be found here


OTRS Prerequisite

You have to enable the webservices in your OTRS instance. It is recommended to use the provided template. This YAML configuration template includes the Route: /TicketList endpoint that is required for PyOTRS but which is not included in the default OTRS webservice setup.


Dependencies are installed automatically


- python-requests

There also is a (completely optional and rudimentary) interactive CLI which requires click. This dependency can be installed by calling pip install PyOTRS[cli].



pip install PyOTRS

or consider using a virtual environment:

virtualenv venv
source venv/bin/activate
pip install PyOTRS

Python Usage


Get Ticket with TicketID 1 from OTRS over the REST API:

from pyotrs import Client
client = Client("", "root@localhost", "password")

The usage of Client.session_restore_or_create is recommended. It uses a temporary file on the hard drive to store the Session ID (just like cookies in a browser) and avoids sending the username+password (and therefore creating a new session) on every API call:

from pyotrs import Client
client = Client("", "root@localhost", "password")

Method Client.session_restore_or_set_up_new is deprecated as of v0.10.

More Examples

  • instantiate a Client object called client
  • create a session (“login”) on client
  • get the Ticket with ID 1
>>> from pyotrs import Article, Client, DynamicField, Ticket
>>> client = Client("", "root@localhost", "password")
>>> client.session_create()
>>> my_ticket = client.ticket_get_by_id(1)
>>> my_ticket
<Ticket: 1>
>>> my_ticket.field_get("TicketNumber")
>>> my_ticket.field_get("Title")
u'Welcome to OTRS!'
>>> my_ticket.to_dct()  # Show complete ticket
  • access as a CustomerUser
>>> from pyotrs import Client
>>> client = Client("", "", "password", customer_user=True)
>>> client.session_create()
  • add an Article to Ticket with ID 1
>>> my_article = Article({"Subject": "Subj", "Body": "New Body"})
>>> client.ticket_update(1, article=my_article)
{u'ArticleID': u'3',
 u'TicketID': u'1',
 u'TicketNumber': u'2010080210123456'}
  • get Articles and Attachments
>>> client.ticket_get_by_id(1, articles=1, attachments=1)
>>> my_ticket = client.result[0]
>>> my_ticket.articles
[<ArticleID: 3>, <ArticleID: 4>
>>> my_ticket.dynamic_fields
[<DynamicField: ProcessManagementActivityID: None>, <DynamicField: ProcessManagementProcessID: None>]

Get Tickets

>>> client.ticket_get_by_id(1, articles=True, attachments=True, dynamic_fields=True)
<Ticket: 1>
>>> client.ticket_get_by_list([1, 3, 4], dynamic_fields=False)
[<Ticket: 1>, <Ticket: 3>, <Ticket: 4>]

Update Tickets

>>> client.ticket_update(1, Title="New Title")
{u'TicketID': u'1', u'TicketNumber': u'2010080210123456'}
>>> client.ticket_update(1, Queue="New Queue")
{u'TicketID': u'1', u'TicketNumber': u'2010080210123456'}
>>> client.ticket_update(1, Queue="New Queue", State="closed")
{u'TicketID': u'1', u'TicketNumber': u'2010080210123456'}
>>> my_article = Article({"Subject": "Subj", "Body": "New Body"})
>>> client.ticket_update(1, article=my_article)
{u'ArticleID': u'3',
 u'TicketID': u'1',
 u'TicketNumber': u'2010080210123456'}
>>> att = Attachment.create_from_file("./test_data/asd.txt")
>>> client.ticket_update(ticket_id=1, article=my_article, attachments=[att])
{'ArticleID': '7927', 'TicketID': '1', 'TicketNumber': '2010080210123456'}
>>> df = DynamicField("ExternalTicket", "1234")
>>> client.ticket_update(1, dynamic_fields=[df])
{u'TicketID': u'1', u'TicketNumber': u'2010080210123456'}

Create Tickets

OTRS requires that new Tickets have several fields filled with valid values and that an Article is present for the new Ticket.

>>> new_ticket = Ticket.create_basic(Title="This is the Title",
                                     Priority=u"3 normal",
>>> first_article = Article({"Subject": "Subj", "Body": "New Body"})
>>> client.ticket_create(new_ticket, first_article)
{u'ArticleID': u'9', u'TicketID': u'7', u'TicketNumber': u'2016110528000013'}

Article body with HTML

PyOTRS defaults to using the MIME type “text/plain”. By specifying a different type it is possible to e.g. add a HTML body.

>>> first_article = Article({"Subject": "Subj",
                             "Body": "<html><body><h1>This is a header</h1>" \
                                     "<a href=''>Link to PyOTRS Docs</a></body></html>",
                             "MimeType": "text/html"})
>>> client.ticket_update(10, first_article)
{u'ArticleID': u'29', u'TicketID': u'10', u'TicketNumber': u'2017052328000034'}

Search for Tickets

  • get list of Tickets created before a date (e.g. Jan 01, 2011)
>>> from datetime import datetime
>>> client.ticket_search(TicketCreateTimeOlderDate=datetime(2011, 1, 1))
  • get list of Tickets created less than a certain time ago (e.g. younger than 1 week)
>>> from datetime import datetime
>>> from datetime import timedelta
>>> client.ticket_search(TicketCreateTimeNewerDate=datetime.utcnow() - timedelta(days=7))
[u'66', u'65', u'64', u'63']
  • show tickets with either ‘open’ or ‘new’ state in Queue 12 created over a week ago
>>> from datetime import datetime
>>> from datetime import timedelta
>>> week = datetime.utcnow() - timedelta(days=7)
>>> client.ticket_search(TicketCreateTimeOlderDate=week, States=['open', 'new'], QueueIDs=[12])
  • empty result (search worked, but there are no matching tickets)
>>> client.ticket_search(Title="no such ticket")
  • search for content of DynamicFields
>>> df = DynamicField("ExternalTicket", search_patterns=["1234"])
>>> client.ticket_search(dynamic_fields=[df])
>>> df = DynamicField("ExternalTicket", search_patterns=["123*"], search_operator="Like")
>>> client.ticket_search([df])


When using ipython you could run into UTF8 encoding issues on Python2. This is a workaround that can help:

import sys

If needed the insecure plattform warnings can be disabled:

# turn off platform insecurity warnings from urllib3
from requests.packages.urllib3 import disable_warnings
disable_warnings()  # TODO 2016-04-23 (RH) verify this


The PyOTRS Shell CLI is a kind of “proof-of-concept” for the PyOTRS wrapper library.

Attention: PyOTRS can only retrieve Ticket data at the moment!


Get a Ticket:

pyotrs get -b -u root@localhost -p password -t 1
Starting PyOTRS CLI
No config file found at: /home/user/.pyotrs
Connecting to as user..
Ticket:         Welcome to OTRS!
Queue:          Raw
State:          closed successful
Priority:       3 normal

Get usage information:

$: pyotrs -h

  --version      Show the version and exit.
  --config PATH  Config File
  -h, --help     Show this message and exit.

  get  PyOTRS get command

$:pyotrs get -h
Starting PyOTRS CLI
No config file found at: /home/user/.pyotrs
Usage: PyOTRS get [OPTIONS]

  PyOTRS get command

  -b, --baseurl TEXT              Base URL
  -u, --username TEXT             Username
  -p, --password TEXT             Password
  -t, --ticket-id INTEGER         Ticket ID
  --store-path TEXT               where to store Attachments (default:
  --store-attachments             store Article Attachments to
  --attachments                   include Article Attachments
  --articles                      include Articles
  --https-verify / --no-https-verify
                                  HTTPS(SSL/TLS) Certificate validation
                                  (default: enabled)
  --ca-cert-bundle TEXT           CA CERT Bundle (Path)
  -h, --help                      Show this message and exit.

Get a Ticket “interactively":

$: pyotrs get
Starting PyOTRS CLI
No config file found at: /home/user/.pyotrs
Username: user
Ticket id: 1

Connecting to as user..

Ticket:         Welcome to OTRS!
Queue:          Raw
State:          closed successful
Priority:       3 normal

Full Ticket:
{u'Ticket': {u'TypeID': 1  [...]

Provide Config

There are four ways to provide config values:

1. interactively when prompted
2. as commandline arguments when calling (checkout -h/--help)
3. as settings in the environment
4. in a config file (default location: ~/.pyotrs)

Both the config file and the environment use the same variable names:



MIT License

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for PyOTRS, version 0.10.0
Filename, size File type Python version Upload date Hashes
Filename, size PyOTRS-0.10.0-py2.py3-none-any.whl (23.7 kB) File type Wheel Python version 3.6 Upload date Hashes View
Filename, size PyOTRS-0.10.0.tar.gz (30.4 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page