PyOTRS Lib (all)

pyotrs

This is PyOTRS provide python access to OTRS

Note

Implements: https://doc.otrs.com/doc/api/otrs/8.0/Perl/

pyotrs.lib.Article

class pyotrs.lib.Article(dct)

Bases: object

PyOTRS Article class

classmethod _dummy()

dummy data (for testing)

Returns:

An Article object.

Return type:

Article

classmethod _dummy_force_notify()

dummy data (for testing)

Returns:

An Article object.

Return type:

Article

_parse_attachments()

parse Attachment from Ticket and return as list of Attachment objects

_parse_dynamic_fields()

parse DynamicField from Ticket and return as list of DynamicField objects

attachment_get(a_filename)

Parameters:

a_filename (str) – Filename of Attachment to retrieve

Returns:

Attachment or None

dynamic_field_get(df_name)

Parameters:

df_name (str) – Name of DynamicField to retrieve

Returns:

DynamicField or None

field_get(f_name)

to_dct(attachments=True, attachment_cont=True, dynamic_fields=True)

represent as nested dict compatible for OTRS

Parameters:

• attachments (bool) – if True will include, otherwise exclude: “Attachment” (default: True)

• attachment_cont (bool) – if True will include, otherwise exclude: “Attachment” > “Content” (default: True)

• dynamic_fields (bool) – if True will include, otherwise exclude: “DynamicField” (default: True)

Returns:

Article represented as dict for OTRS

Return type:

dict

validate(validation_map=None)

validate data against a mapping dict - if a key is not present then set it with a default value according to dict

Parameters:

• validation_map (dict) – A mapping for all Article fields that have to be set. During

• value (validation every required field that is not set will be set to a default) –

• dict. (specified in this) –

Note

There is also a blacklist (fields to be removed) but this is currently hardcoded to dynamic_fields and attachments.

pyotrs.lib.Attachment

class pyotrs.lib.Attachment(dct)

Bases: object

PyOTRS Attachment class

classmethod _dummy()

dummy data (for testing)

Returns:

An Attachment object.

Return type:

Attachment

classmethod create_basic(Content=None, ContentType=None, Filename=None)

create a basic Attachment object

Parameters:

• Content (str) – base64 encoded content

• ContentType (str) – MIME type of content (e.g. text/plain)

• Filename (str) – file name (e.g. file.txt)

Returns:

An Attachment object.

Return type:

Attachment

classmethod create_from_file(file_path)

save Attachment to a folder on disc

Parameters:

file_path (str) – The full path to the file from which an Attachment should be created.

Returns:

An Attachment object.

Return type:

Attachment

save_to_dir(folder='/tmp')

save Attachment to a folder on disc

Parameters:

folder (str) – The directory where this attachment should be saved to.

Returns:

True

Return type:

bool

to_dct(content=True)

represent Attachment object as dict :param content: if True will include, otherwise exclude: “Content” (default: True) :type content: bool

Returns:

Attachment represented as dict.

Return type:

dict

pyotrs.lib.Client

class pyotrs.lib.Client(baseurl=None, username=None, password=None, session_id_file=None, session_timeout=None, session_validation_ticket_id=1, webservice_config_ticket=None, webservice_config_faq=None, webservice_config_link=None, proxies=None, https_verify=True, ca_cert_bundle=None, auth=None, client_auth_cert=None, customer_user=False, user_agent=None, webservice_path='/otrs/nph-genericinterface.pl/Webservice/', use_legacy_sessions=False, request_timeout=None)

Bases: object

PyOTRS Client class - includes Session handling

Parameters:

• baseurl (str) – Base URL for OTRS System, no trailing slash e.g. http://otrs.example.com

• username (str) – Username

• password (str) – Password

• session_id_file (str) – Session ID path on disc, used to persistently store Session ID

• session_timeout (int) – Session Timeout configured in OTRS (usually 28800 seconds = 8h)

• session_validation_ticket_id (int) – Ticket ID of an existing ticket - used to perform several check - e.g. validate log in (defaults to 1)

• webservice_config_ticket (dict) – OTRS REST Web Service Name - Ticket Connector

• webservice_config_faq (dict) – OTRS REST Web Service Name - FAQ Connector (FAQ code was deprecated in 0.4.0 and removed in 1.0.0 - parameter stays for compatibility)

• webservice_config_link (dict) – OTRS REST Web Service Name - Link Connector

• proxies (dict) – Proxy settings - refer to requests docs for more information - default to no proxies

• https_verify (bool) – Should HTTPS certificates be verified (defaults to True)

• ca_cert_bundle (str) – file path - if specified overrides python/system default for Root CA bundle that will be used.

• auth (tuple) – e.g. (“user”, “pass”) - see requests documentation (“auth”) for details

• client_auth_cert (str) – file path containing both certificate and key (unencrypted) in PEM format to use for TLS client authentication (passed to requests as “cert”)

• customer_user (bool) – flag to indicate that the username is for a “CustomerUser” (defaults to False)

• user_agent (str) – optional HTTP UserAgent string

• webservice_path (str) – OTRS REST Web Service Path part - defaults to “/otrs/nph-genericinterface.pl/Webservice/”

• use_legacy_sessions (bool) – if True, use sessions compatibility for OTRS < V8

• request_timeout (float or tuple) – optional How many seconds to wait for the server to send data before giving up, as a float, or a (connect timeout, read timeout) tuple

_build_url(data_id=None)

build url for request

Parameters:

data_id (optional[int]) –

Returns:

The complete URL where the request will be send to.

Return type:

str

_parse_and_validate_response(response)

Parameters:

response (requests.Response) – result of _send_request

Raises:

• OTRSAPIError –

• NotImplementedError –

• ResponseParseError –

Returns:

True if successful

Return type:

bool

_send_request(payload=None, data_id=None)

send the API request using the requests.request method

Parameters:

• payload (dict) –

• data_id (optional[dict]) –

Raises:

OTRSHTTPError –

Returns:

Response received after sending the request.

Return type:

requests.Response

Note

Supported HTTP Methods: DELETE, GET, HEAD, PATCH, POST, PUT

link_add(src_object_id, dst_object_id, src_object_type='Ticket', dst_object_type='Ticket', link_type='Normal', state='Valid')

Parameters:

• src_object_id (int) – Integer value of source object ID

• dst_object_id (int) – Integer value of destination object ID

• src_object_type (str) – Object type of source; e.g. “Ticket”, “FAQ”… (default: Ticket)

• dst_object_type (str) – Object type of destination; e.g. “Ticket”, “FAQ”… (default: Ticket)

• link_type (str) – Type of the link: “Normal” or “ParentChild” (default: Normal)

• state (str) – State of the link (default: Normal)

Returns:

True if successful, otherwise False.

Return type:

True or False

link_delete(src_object_id, dst_object_id, src_object_type='Ticket', dst_object_type='Ticket', link_type='Normal')

Parameters:

• src_object_id (int) – Integer value of source object ID

• src_object_type (str) – Object type of source; e.g. “Ticket”, “FAQ”… (default: Ticket)

• dst_object_id (int) – Integer value of source object ID

• dst_object_type (str) – Object type of source; e.g. “Ticket”, “FAQ”… (default: Ticket)

• link_type (str) – Type of the link: “Normal” or “ParentChild” (default: Normal)

Returns:

True if successful, otherwise False.

Return type:

True or False

link_delete_all(object_id, object_type='Ticket')

Parameters:

• object_id (int) – Integer value of source object ID

• object_type (str) – Object type of source; e.g. “Ticket”, “FAQ”… (default: Ticket)

Returns:

True if successful, otherwise False.

Return type:

True or False

link_list(src_object_id, src_object_type='Ticket', dst_object_type=None, state='Valid', link_type=None, direction=None)

Parameters:

• src_object_id (int) – Integer value of source object ID

• src_object_type (str) – Object type of source; e.g. “Ticket”, “FAQ”… (default: Ticket)

• dst_object_type (str) – Object type of destination; e.g. “Ticket”, “FAQ”… Optional restriction of the object where the links point to. (default: Ticket)

• state (str) – State of the link (default: Valid)

• link_type (str) – Type of the link: “Normal” or “ParentChild” (default: Normal)

• direction (str) – Optional restriction of the link direction (‘Source’ or ‘Target’).

Returns:

List of found dict links if successful, if empty None.

Return type:

list or None

link_possible_link_list()

Returns:

List if successful, otherwise False.

Return type:

List or False

link_possible_objects_list(object_type='Ticket')

Parameters:

object_type (str) – Object type; e.g. “Ticket”, “FAQ”… (default: Ticket)

Returns:

List if successful, otherwise False.

Return type:

List or False

link_possible_types_list(src_object_type='Ticket', dst_object_type='Ticket')

Parameters:

• src_object_type (str) – Object type of source; e.g. “Ticket”, “FAQ”… (default: Ticket)

• dst_object_type (str) – Object type of destination; e.g. “Ticket”, “FAQ”… (default: Ticket)

Returns:

List if successful, otherwise False.

Return type:

List or False

session_check_is_valid(session_id=None)

check whether session_id is currently valid

Parameters:

session_id (str) – optional if set overrides the self.session_id

Raises:

ArgumentMissingError – if session_id is not set

Returns:

True if valid, otherwise False.

Return type:

bool

Note

Uses HTTP Method: GET

Deprecated since version 0.10.0: This will be removed in 2.0. This method was implemented with a “dirty” workaround and should not be called anymore. Use Client.session_get() instead. ATTENTION: Using session_get() requires the OTRS route for HTTP GET /Session to be configured (which is/was not the default).

session_create()

create new (temporary) session (and Session ID)

Returns:

True if successful, otherwise False.

Return type:

bool

Note

Session ID is recorded in self.session_id_store.value (non persistently)

Note

Uses HTTP Method: POST

session_get(session_id=None)

get/check/validate a Session ID

Returns:

True if successful, otherwise False.

Return type:

bool

Note

Uses HTTP Method: GET

session_restore_or_create()

Try to restore Session ID from file otherwise create new one and save to file

Raises:

• SessionCreateError –

• SessionIDFileError –

Note

Session ID is recorded in self.session_id_store.value (non persistently)

Note

Session ID is saved persistently to file: self.session_id_store.file_path

Returns:

True if successful, otherwise False.

Return type:

bool

session_restore_or_set_up_new()

Try to restore Session ID from file otherwise create new one and save to file

Raises:

• SessionCreateError –

• SessionIDFileError –

Note

Session ID is recorded in self.session_id_store.value (non persistently)

Note

Session ID is saved persistently to file: self.session_id_store.file_path

Returns:

True if successful, otherwise False.

Return type:

bool

Deprecated since version 0.10.0: This will be removed in 2.0. This method uses session_check_is_valid which was implemented with a “dirty” workaround and should not be called anymore. Use Client.session_restore_or_create() instead. ATTENTION: Using that also switches to session_get() which requires the OTRS route for HTTP GET /Session to be configured (which is/was not the default).

ticket_create(ticket=None, article=None, attachments=None, dynamic_fields=None, **kwargs)

Create a Ticket

Parameters:

• ticket (Ticket) – a ticket object

• article (Article) – optional article

• attachments (list) – Attachment objects

• dynamic_fields (list) – DynamicField object

• **kwargs – any regular OTRS Fields (not for Dynamic Fields!)

Returns:

dict if successful, otherwise False.

Return type:

dict or False

ticket_get_by_id(ticket_id, articles=False, attachments=False, dynamic_fields=True, html_body_as_attachment=False)

Parameters:

• ticket_id (int) – Integer value of a Ticket ID

• attachments (bool) – will request OTRS to include attachments (default: False)

• articles (bool) – will request OTRS to include all Articles (default: False)

• dynamic_fields (bool) – will request OTRS to include all Dynamic Fields (default: True)

• html_body_as_attachment (bool) – Optional, If enabled the HTML body version of each article is added to the attachments list

Returns:

Ticket object if successful, otherwise False.

Return type:

Ticket or False

ticket_get_by_list(ticket_id_list, articles=False, attachments=False, dynamic_fields=True, html_body_as_attachment=False)

Parameters:

• ticket_id_list (list) – List of either String or Integer values

• attachments (bool) – will request OTRS to include attachments (default: False)

• articles (bool) – will request OTRS to include all Articles (default: False)

• dynamic_fields (bool) – will request OTRS to include all Dynamic Fields (default: True)

• html_body_as_attachment (bool) – Optional, If enabled the HTML body version of each article is added to the attachments list

Returns:

Ticket objects (as list) if successful, otherwise False.

Return type:

list

ticket_get_by_number(ticket_number, articles=False, attachments=False, dynamic_fields=True, html_body_as_attachment=False)

Parameters:

• ticket_number (str) – Ticket Number as str

• attachments (bool) – will request OTRS to include attachments (default: False)

• articles (bool) – will request OTRS to include all Articles (default: False)

• dynamic_fields (bool) – will request OTRS to include all Dynamic Fields (default: True)

• html_body_as_attachment (bool) – Optional, If enabled the HTML body version of each article is added to the attachments list

Raises:

ValueError –

Returns:

Ticket object if successful, otherwise False.

Return type:

Ticket or False

ticket_search(dynamic_fields=None, **kwargs)

Search for ticket

Parameters:

• dynamic_fields (list) – List of DynamicField objects for which the search should be performed

• **kwargs – Arbitrary keyword arguments (not for DynamicField objects).

Returns:

The search result (as list) if successful (can be an

empty list: []), otherwise False.

Return type:

list or False

Note

If value of kwargs is a datetime object then this object will be converted to the appropriate string format for OTRS API.

ticket_search_full_text(pattern)

Wrapper for search ticket for full text search

Parameters:

pattern (str) – Search pattern (a ‘%’ will be added to front and end automatically)

Returns:

The search result (as list) if successful,

otherwise False.

Return type:

list or False

ticket_update(ticket_id, article=None, attachments=None, dynamic_fields=None, **kwargs)

Update a Ticket

Parameters:

• ticket_id (int) – Ticket ID as integer value

• article (Article) – optional one Article that will be add to the ticket

• attachments (list) – list of one or more Attachment objects that will be added to ticket. Also requires an Article!

• dynamic_fields (list) – DynamicField objects

• **kwargs – any regular Ticket Fields (not for Dynamic Fields!)

Returns:

A dict if successful, otherwise False.

Return type:

dict or False

ticket_update_set_pending(ticket_id, new_state='pending reminder', pending_days=1, pending_hours=0)

ticket_update_set_state_pending

Parameters:

• ticket_id (int) – Ticket ID as integer value

• new_state (str) – defaults to “pending reminder”

• pending_days (int) – defaults to 1

• pending_hours (int) – defaults to 0

Returns:

A dict if successful, otherwise False.

Return type:

dict or False

Note

Operates in UTC

property _session_key

pyotrs.lib.DynamicField

class pyotrs.lib.DynamicField(name, value=None, search_patterns=None, search_operator='Equals')

Bases: object

PyOTRS DynamicField class

Parameters:

• name (str) – Name of OTRS DynamicField (required)

• value (str) – Value of OTRS DynamicField

• search_operator (str) – Search operator (defaults to: “Equals”) Valid options are: “Equals”, “Like”, “GreaterThan”, “GreaterThanEquals”, “SmallerThan”, “SmallerThanEquals”

• search_patterns (list) – List of patterns (str or datetime) to search for

Warning

PyOTRS only supports OTRS 5 style! DynamicField representation changed between OTRS 4 and OTRS 5.

classmethod _dummy1()

dummy1 data (for testing)

Returns:

A list of DynamicField objects.

Return type:

DynamicField

classmethod _dummy2()

dummy2 data (for testing)

Returns:

A list of DynamicField objects.

Return type:

DynamicField

classmethod from_dct(dct)

create DynamicField from dct

Parameters:

dct (dict) –

Returns:

A DynamicField object.

Return type:

DynamicField

to_dct()

represent DynamicField as dict

Returns:

DynamicField as dict.

Return type:

dict

to_dct_search()

represent DynamicField as dict for search operations

Returns:

DynamicField as dict for search operations

Return type:

dict

SEARCH_OPERATORS = ('Equals', 'Like', 'GreaterThan', 'GreaterThanEquals', 'SmallerThan', 'SmallerThanEquals')

pyotrs.lib.SessionStore

class pyotrs.lib.SessionStore(file_path=None, session_timeout=None, value=None, created=None, expires=None, is_legacy=False)

Bases: object

Session ID: persistently store to and retrieve from to file

Parameters:

• file_path (str) – Path on disc

• session_timeout (int) – OTRS Session Timeout Value (to avoid reusing outdated session id

• value (str) – A Session ID as str

• created (int) – seconds as epoch when a session_id record was created

• expires (int) – seconds as epoch when a session_id record expires

• is_legacy (bool) – whether the Session ID is for an older OTRS Version (<=7)

Raises:

ArgumentMissingError –

static _validate_file_owner_and_permissions(full_file_path)

validate SessionStore file ownership and permissions

Parameters:

full_file_path (str) – full path to file on disc

Returns:

True if valid and correct (or running on Windows), otherwise False…

Return type:

bool

delete()

remove session id file (e.g. when it only contains an invalid session id)

Raises:

NotImplementedError –

Returns:

True if successful, otherwise False.

Return type:

bool

Todo

(RH) implement this _remove_session_id_file

read()

Retrieve a stored Session ID from file

Returns:

Retrieved Session ID or None (if none could be read)

Return type:

str or None

write(new_value)

Write and store a Session ID to file (rw for user only)

Parameters:

new_value (str) – if none then empty value will be writen to file

Returns:

True if successful, False otherwise.

Return type:

bool

pyotrs.lib.Ticket

class pyotrs.lib.Ticket(dct)

Bases: object

PyOTRS Ticket class

Parameters:

• tid (int) – OTRS Ticket ID as integer

• fields (dict) – OTRS Top Level fields

• articles (list) – List of Article objects

• dynamic_fields (list) – List of DynamicField objects

classmethod _dummy()

dummy data (for testing)

Returns:

A Ticket object.

Return type:

Ticket

_parse_articles()

parse Article from Ticket and return as list of Article objects

_parse_dynamic_fields()

parse DynamicField from Ticket and return as list of DynamicField objects

article_get(aid)

Parameters:

aid (str) – Article ID as either int or str

Returns:

Article or None

classmethod create_basic(Title=None, QueueID=None, Queue=None, TypeID=None, Type=None, StateID=None, State=None, PriorityID=None, Priority=None, CustomerUser=None)

create basic ticket

Parameters:

• Title (str) – OTRS Ticket Title

• QueueID (str) – OTRS Ticket QueueID (e.g. “1”)

• Queue (str) – OTRS Ticket Queue (e.g. “raw”)

• TypeID (str) – OTRS Ticket TypeID (e.g. “1”)

• Type (str) – OTRS Ticket Type (e.g. “Problem”)

• StateID (str) – OTRS Ticket StateID (e.g. “1”)

• State (str) – OTRS Ticket State (e.g. “open” or “new”)

• PriorityID (str) – OTRS Ticket PriorityID (e.g. “1”)

• Priority (str) – OTRS Ticket Priority (e.g. “low”)

• CustomerUser (str) – OTRS Ticket CustomerUser

Returns:

A new Ticket object.

Return type:

Ticket

static datetime_to_pending_time_text(datetime_object=None)

Parameters:

datetime_object (Datetime) –

Returns:

The pending time in the format required for OTRS REST interface.

Return type:

str

dynamic_field_get(df_name)

Parameters:

df_name (str) – Name of DynamicField to retrieve

Returns:

DynamicField or None

field_get(f_name)

to_dct(articles=True, article_attachments=True, article_attachment_cont=True, article_dynamic_fields=True, dynamic_fields=True)

represent as nested dict

Parameters:

• articles (bool) – if True will include, otherwise exclude: “Article” (default: True)

• article_attachments (bool) – if True will include, otherwise exclude: “Article” > “Attachment” (default: True)

• article_attachment_cont (bool) – if True will include, otherwise exclude: “Article” > “Attachment” > “Content” (default: True)

• article_dynamic_fields (bool) – if True will include, otherwise exclude: “Article” > “DynamicField” (default: True)

• dynamic_fields (bool) – if True will include, otherwise exclude: “DynamicField” (default: True)

Returns:

Ticket represented as dict.

Return type:

dict

Note

Does not contain Articles or DynamicFields (currently)