PyOTRS

https://pyotrs.readthedocs.io/en/stable/
Admin
PyOTRS is a Python wrapper for accessing the OTRS help desk and ticketing system via its...
Tokens:7,574
Snippets:90
Trust Score:9.6
Update:1 day ago
Show doc for...
Tokens:
Raw
### Quickstart: Get ticket by ID

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Creates a PyOTRS client, creates a session, and retrieves a ticket by ID.

```python
from pyotrs import Client
client = Client("https://otrs.example.com", "root@localhost", "password")
client.session_create()
client.ticket_get_by_id(1)
```

--------------------------------

### Install with Poetry (with or without dev/docs dependencies)

Source: https://pyotrs.readthedocs.io/en/stable/contributing.html

Commands to install the project using Poetry, either with development and documentation dependencies or without them.

```bash
pip3 install poetry  # or: python3 -m pip install poetry
poetry install --with dev,docs --compile

or

poetry install --without dev,docs --compile
```

--------------------------------

### Install PyOTRS in a virtual environment

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Creates a virtual environment, activates it, and installs PyOTRS.

```bash
virtualenv venv
source venv/bin/activate
pip install PyOTRS
```

--------------------------------

### Install PyOTRS with pip

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Installs the PyOTRS package using pip.

```bash
pip install PyOTRS
```

--------------------------------

### Sphinx Napoleon documentation links

Source: https://pyotrs.readthedocs.io/en/stable/contributing.html

Links to Sphinx Napoleon documentation and example.

```text
https://sphinxcontrib-napoleon.readthedocs.org/en/latest/
https://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html#example-google
```

--------------------------------

### PyOTRS CLI help output

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Shows the help output for the PyOTRS CLI and the 'get' subcommand, listing available options and commands.

```bash
$: pyotrs -h
Usage: PyOTRS [OPTIONS] COMMAND [ARGS]...

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

Commands:
  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

Options:
  -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:
                                  /tmp/pyotrs_<random_str>
  --store-attachments             store Article Attachments to
                                  /tmp/<ticket_id>
  --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 with PyOTRS CLI

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Interactive invocation of 'pyotrs get' that prompts for base URL, username, password, and ticket ID, then displays the ticket details.

```bash
$: pyotrs get
Starting PyOTRS CLI
No config file found at: /home/user/.pyotrs
Baseurl: http://otrs.example.com
Username: user
Password:
Ticket id: 1

Connecting to https://otrs.example.com as user..

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

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

--------------------------------

### pip dependency list

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Lists the Python package dependency for PyOTRS, which is installed automatically.

```text
- python-requests
```

--------------------------------

### Create Article with HTML Body

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Creates an Article with an HTML body by setting MimeType to 'text/html'. The example shows the expected response containing ArticleID, TicketID, and TicketNumber.

```python
>>> first_article = Article({"Subject": "Subj",
                             "Body": "<html><body><h1>This is a header</h1>" \
                                     "<a href='https://pyotrs.readthedocs.io/'>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 Tickets by DynamicField with Like Operator

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Searches for tickets using a DynamicField with a wildcard pattern and the 'Like' search operator. The example uses search_patterns=['123*'] and search_operator='Like'.

```python
>>> df = DynamicField("ExternalTicket", search_patterns=["123*"], search_operator="Like")
>>> client.ticket_search([df])
[u'2']
```

--------------------------------

### Get Articles and Attachments

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Fetches ticket ID 1 with articles and attachments included, then accesses the result from client.result[0].

```python
>>> client.ticket_get_by_id(1, articles=1, attachments=1)
>>> my_ticket = client.result[0]
```

--------------------------------

### Get Tickets by List

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Fetches multiple tickets by their IDs using ticket_get_by_list(). The dynamic_fields parameter is set to False.

```python
>>> client.ticket_get_by_list([1, 3, 4], dynamic_fields=False)
[<Ticket: 1>, <Ticket: 3>, <Ticket: 4>]
```

--------------------------------

### Get Ticket by ID

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Fetches the ticket with ID 1 using ticket_get_by_id(). The result is a Ticket object.

```python
>>> my_ticket = client.ticket_get_by_id(1)
>>> my_ticket
<Ticket: 1>
```

--------------------------------

### Get a ticket with PyOTRS CLI

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Command-line invocation to retrieve a ticket by ID, showing the output with ticket details. Requires base URL, username, password, and ticket ID.

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

--------------------------------

### Get Ticket with Articles, Attachments, and Dynamic Fields

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Fetches ticket ID 1 with all related data (articles, attachments, dynamic fields) enabled.

```python
>>> client.ticket_get_by_id(1, articles=True, attachments=True, dynamic_fields=True)
<Ticket: 1>
```

--------------------------------

### Search Tickets Created Before a Date

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Searches for tickets created before a specific date using TicketCreateTimeOlderDate. The example uses datetime(2011, 1, 1) and returns a list of ticket IDs.

```python
>>> from datetime import datetime
>>> client.ticket_search(TicketCreateTimeOlderDate=datetime(2011, 1, 1))
[u'1']
```

--------------------------------

### Search Tickets by DynamicField Exact Match

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Searches for tickets using a DynamicField with a search pattern. The example uses DynamicField('ExternalTicket', search_patterns=['1234']) and returns a list of ticket IDs.

```python
>>> df = DynamicField("ExternalTicket", search_patterns=["1234"])
>>> client.ticket_search(dynamic_fields=[df])
[u'2']
```

--------------------------------

### Access as CustomerUser

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Creates a Client with customer_user=True to authenticate as a customer user. The session_create() method returns True on success.

```python
>>> from pyotrs import Client
>>> client = Client("http://otrs.example.com", "user@customer.example.com", "password", customer_user=True)
>>> client.session_create()
True
```

--------------------------------

### Run tests with tox (from project root)

Source: https://pyotrs.readthedocs.io/en/stable/contributing.html

Command to run the test suite using tox from the project root.

```bash
`poetry run tox`
```

--------------------------------

### Run full test suite with tox

Source: https://pyotrs.readthedocs.io/en/stable/contributing.html

Command to run the full test suite using tox.

```bash
tox
```

--------------------------------

### Run tests with make and clean up

Source: https://pyotrs.readthedocs.io/en/stable/contributing.html

Commands to run tests using make and then clean up after.

```bash
make test
# and to clean up after
```

--------------------------------

### Instantiate Client and Create Session

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Creates a Client object and logs in to the OTRS system. The session_create() method returns True on success.

```python
>>> from pyotrs import Article, Client, DynamicField, Ticket
>>> client = Client("http://otrs.example.com", "root@localhost", "password")
>>> client.session_create()
True
```

--------------------------------

### Ways to provide config values

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Lists the four ways to provide configuration values to PyOTRS: interactive prompts, command-line arguments, environment settings, and a config file.

```text
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)
```

--------------------------------

### Clean up with make

Source: https://pyotrs.readthedocs.io/en/stable/contributing.html

Command to clean up build artifacts.

```bash
make clean
```

--------------------------------

### Documentation dependencies (pip)

Source: https://pyotrs.readthedocs.io/en/stable/contributing.html

List of Python packages required for building documentation.

```text
- sphinx
- sphinxcontrib-napoleon
- sphinx_rtd_theme
```

--------------------------------

### Build and upload PyOTRS package

Source: https://pyotrs.readthedocs.io/en/stable/contributing.html

Commands to build the package and upload it to PyPI (requires credentials).

```bash
python setup.py sdist
```

```bash
python setup.py sdist bdist_wheel upload
```

--------------------------------

### Recommended session restore or create

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Uses session_restore_or_create to store the session ID in a temporary file, avoiding sending credentials on every API call.

```python
from pyotrs import Client
client = Client("https://otrs.example.com", "root@localhost", "password")
client.session_restore_or_create()
client.ticket_get_by_id(1)
```

--------------------------------

### Create ticket with required fields and article using client.ticket_create

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Creates a basic ticket with required fields and an initial article, then calls ticket_create. Returns ArticleID, TicketID, and TicketNumber.

```python
>>> new_ticket = Ticket.create_basic(Title="This is the Title",
                                     Queue="Raw",
                                     State=u"new",
                                     Priority=u"3 normal",
                                     CustomerUser="root@localhost")
>>> 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'}
```

--------------------------------

### Development dependencies (pip)

Source: https://pyotrs.readthedocs.io/en/stable/contributing.html

List of Python packages required for testing and development.

```text
- tox
- coverage
- unittest
- mock
- responses
```

--------------------------------

### Upgrade dependencies with Poetry

Source: https://pyotrs.readthedocs.io/en/stable/contributing.html

Command to update project dependencies managed by Poetry. Remember to commit the updated poetry.lock file.

```bash
poetry update
```

--------------------------------

### Environment variable names for PyOTRS config

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Shows the environment variable names used for configuration, matching the config file variable names.

```bash
PYOTRS_BASEURL=http://otrs.example.com
PYOTRS_USERNAME=root@localhost
PYOTRS_PASSWORD=otrs_password
PYOTRS_HTTPS_VERIFY=True
PYOTRS_CA_CERT_BUNDLE=
```

--------------------------------

### Sphinx and reStructuredText documentation links

Source: https://pyotrs.readthedocs.io/en/stable/contributing.html

Links to Sphinx and reStructuredText documentation for writing documentation.

```text
http://www.sphinx-doc.org/en/stable/markup/para.html
http://www.sphinx-doc.org/en/stable/rest.html
http://docutils.sourceforge.net/docs/user/rst/quickref.html#escaping
https://gist.github.com/dupuy/1855764
```

--------------------------------

### Access Ticket Fields and Convert to Dict

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Shows how to retrieve specific fields from a ticket and convert the entire ticket to a dictionary. The to_dct() method displays the complete ticket.

```python
>>> my_ticket.field_get("TicketNumber")
u'2010080210123456'
>>> my_ticket.field_get("Title")
u'Welcome to OTRS!'
>>> my_ticket.to_dct()  # Show complete ticket
```

--------------------------------

### Google Docstring format sections

Source: https://pyotrs.readthedocs.io/en/stable/contributing.html

List of sections to include in Google-style docstrings.

```text
- Args: (includes **kwargs)
- Returns:
- Raises:
- Examples:
```

--------------------------------

### ticket_create

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Creates a new ticket with the provided ticket object and an initial article. The ticket must have required fields set and an article must be present.

```APIDOC
## ticket_create

### Description
Creates a new ticket with the given ticket object and an initial article.

### Method
client.ticket_create

### Parameters
- **ticket** (Ticket) - Required - A Ticket object created with Ticket.create_basic, containing required fields.
- **article** (Article) - Required - An Article object to be added as the first article of the ticket.

### Request Example
```python
new_ticket = Ticket.create_basic(Title="This is the Title", Queue="Raw", State=u"new", Priority=u"3 normal", CustomerUser="root@localhost")
first_article = Article({"Subject": "Subj", "Body": "New Body"})
client.ticket_create(new_ticket, first_article)
```

### Response
Returns a dictionary with the new ticket and article IDs.

#### Response Example
```python
{u'ArticleID': u'9', u'TicketID': u'7', u'TicketNumber': u'2016110528000013'}
```
```

--------------------------------

### Update ticket with attachment using client.ticket_update

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Creates an Attachment from a file and passes it along with an article to ticket_update. Returns ArticleID, TicketID, and TicketNumber.

```python
>>> 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'}
```

--------------------------------

### Search Tickets with No Matching Results

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Searches for tickets with a title that does not exist, returning an empty list. Demonstrates a successful search with no matches.

```python
>>> client.ticket_search(Title="no such ticket")
[]
```

--------------------------------

### Access Ticket Articles

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Shows the articles associated with the ticket. The output is a list of ArticleID objects.

```python
>>> my_ticket.articles
[<ArticleID: 3>, <ArticleID: 4>
```

--------------------------------

### Search Tickets by State and Queue with Date Filter

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Searches for tickets older than a week in Queue 12 with states 'open' or 'new'. Uses TicketCreateTimeOlderDate, States, and QueueIDs parameters.

```python
>>> from datetime import datetime
>>> from datetime import timedelta
>>> week = datetime.utcnow() - timedelta(days=7)
>>> client.ticket_search(TicketCreateTimeOlderDate=week, States=['open', 'new'], QueueIDs=[12])
```

--------------------------------

### Update ticket with dynamic field using client.ticket_update

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Creates a DynamicField object and passes it to ticket_update. Returns TicketID and TicketNumber.

```python
>>> df = DynamicField("ExternalTicket", "1234")
>>> client.ticket_update(1, dynamic_fields=[df])
{u'TicketID': u'1', u'TicketNumber': u'2010080210123456'}
```

--------------------------------

### Access Ticket Dynamic Fields

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Shows the dynamic fields associated with the ticket. The output is a list of DynamicField objects.

```python
>>> my_ticket.dynamic_fields
[<DynamicField: ProcessManagementActivityID: None>, <DynamicField: ProcessManagementProcessID: None>]
```

--------------------------------

### Update ticket queue with client.ticket_update

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Updates the Queue of ticket 1. Returns a dictionary with TicketID and TicketNumber.

```python
>>> client.ticket_update(1, Queue="New Queue")
{u'TicketID': u'1', u'TicketNumber': u'2010080210123456'}
```

--------------------------------

### Update ticket queue and state with client.ticket_update

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Updates both Queue and State of ticket 1. Returns a dictionary with TicketID and TicketNumber.

```python
>>> client.ticket_update(1, Queue="New Queue", State="closed")
{u'TicketID': u'1', u'TicketNumber': u'2010080210123456'}
```

--------------------------------

### Disable urllib3 platform insecurity warnings

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Use this snippet to turn off platform insecurity warnings from urllib3. The comment notes to verify the disable_warnings() call.

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

--------------------------------

### Search Tickets Created Within Last Week

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Searches for tickets created within the last week using TicketCreateTimeNewerDate with a timedelta of 7 days. Returns a list of ticket IDs.

```python
>>> 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']
```

--------------------------------

### Add Article to Ticket

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Creates an Article object and updates ticket ID 1 with it. The response contains the ArticleID, TicketID, and TicketNumber.

```python
>>> 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'}
```

--------------------------------

### Include private members in Sphinx docs

Source: https://pyotrs.readthedocs.io/en/stable/contributing.html

Directive to include private methods in automatically generated Sphinx documentation.

```rst
:private-members:
```

--------------------------------

### Update ticket title with client.ticket_update

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Updates the Title of ticket 1. Returns a dictionary with TicketID and TicketNumber.

```python
>>> client.ticket_update(1, Title="New Title")
{u'TicketID': u'1', u'TicketNumber': u'2010080210123456'}
```

--------------------------------

### ticket_update

Source: https://pyotrs.readthedocs.io/en/stable/readme.html

Updates an existing ticket. Can update ticket fields such as Title and Queue, set the State, add an Article, attach files, and set Dynamic Fields.

```APIDOC
## ticket_update

### Description
Updates an existing ticket with new values for fields, state, article, attachments, or dynamic fields.

### Method
client.ticket_update

### Parameters
- **ticket_id** (int) - Required - The ID of the ticket to update.
- **Title** (str) - Optional - New title for the ticket.
- **Queue** (str) - Optional - New queue for the ticket.
- **State** (str) - Optional - New state for the ticket (e.g., "closed").
- **article** (Article) - Optional - An Article object to add to the ticket.
- **attachments** (list) - Optional - List of Attachment objects to attach to the article.
- **dynamic_fields** (list) - Optional - List of DynamicField objects to set on the ticket.

### Request Example
```python
client.ticket_update(1, Title="New Title")
```

### Response
Returns a dictionary with the updated ticket information.

#### Response Example
```python
{u'TicketID': u'1', u'TicketNumber': u'2010080210123456'}
```
```
Tokens:
Raw