from parsons.utilities import check_env
from parsons.utilities.api_connector import APIConnector
import re
from parsons.etl import Table
import logging
logger = logging.getLogger(__name__)
PAGE_SIZE = 100
[docs]class Freshdesk:
"""
Instantiate Freshdesk class
`Args:`
domain: str
The subdomain of the Freshdesk account. Not required if ``FRESHDESK_DOMAIN``
env variable set.
api_key: str
The Freshdesk provided application key. Not required if ``FRESHDESK_API_KEY``
env variable set.
`Returns:`
Freshdesk class
"""
def __init__(self, domain, api_key):
self.api_key = check_env.check("FRESHDESK_API_KEY", api_key)
self.domain = check_env.check("FRESHDESK_DOMAIN", domain)
self.uri = f"https://{self.domain}.freshdesk.com/api/v2/"
self.client = APIConnector(self.uri, auth=(self.api_key, "x"))
def _get_request(self, endpoint, params=None):
base_params = {"per_page": PAGE_SIZE}
if params:
base_params.update(params)
r = self.client.request(endpoint, "GET", params=base_params)
self.client.validate_response(r)
data = r.json()
# Paginate
while "link" in r.headers.keys():
logger.info(f"Retrieving another page of {PAGE_SIZE} records.")
url = re.search("<(.*)>", r.headers["link"]).group(1)
r = self.client.request(url, "GET", params=params)
self.client.validate_response(r)
data.extend(r.json())
return data
@staticmethod
def _transform_table(tbl, expand_custom_fields=None):
if tbl.num_rows > 0:
tbl.move_column("id", 0)
tbl.sort()
if expand_custom_fields:
tbl.unpack_dict("custom_fields", prepend=False)
return tbl
[docs] def get_tickets(
self,
ticket_type=None,
requester_id=None,
requester_email=None,
company_id=None,
updated_since="2016-01-01",
expand_custom_fields=False,
):
"""
List tickets.
See the `API Docs <https://developers.freshdesk.com/api/#list_all_tickets>`_
for more information.
.. warning::
Deleted and Spam tickets are not included. However they can be pulled separately
by utilizing the ``ticket_type`` parameter.
.. warning::
Freshdesk will return a maximum of 9,000 tickets. By default, only tickets created in
the past 30 days are returned. To access additional tickets, utilize the
``updated_since`` parameter.
`Args:`
ticket_type: str
Filter by type of ticket to filter by. Valid fields include ``new_and_my_open``,
``watching``, ``spam`` and ``deleted``.
requester_id: int
Filter by requester id.
requester_email: str
Filter by requester email.
company_id: int
Filter by company_id.
updated_since: str
Earliest date to include in results.
expand_custom_fields: boolean
Expand nested custom fields to their own columns.
`Returns:`
Parsons Table
See :ref:`parsons-table` for output options.
"""
params = {
"filter": ticket_type,
"requester_id": requester_id,
"requester_email": requester_email,
"company_id": company_id,
"updated_since": updated_since,
}
tbl = Table(self._get_request("tickets", params=params))
logger.info(f"Found {tbl.num_rows} tickets.")
return self._transform_table(tbl, expand_custom_fields)
[docs] def get_companies(self, expand_custom_fields=False):
"""
List companies.
See the `API Docs <https://developers.freshdesk.com/api/#list_all_companies>`_
for more information.
`Args:`
expand_custom_fields: boolean
Expand nested custom fields to their own columns.
`Returns:`
Parsons Table
See :ref:`parsons-table` for output options.
"""
tbl = Table(self._get_request("companies"))
logger.info(f"Found {tbl.num_rows} companies.")
return self._transform_table(tbl, expand_custom_fields)
[docs] def get_agents(self, email=None, mobile=None, phone=None, state=None):
"""
List agents.
See the `API Docs <https://developers.freshdesk.com/api/#list_all_agents>`_
for more information.
`Args:`
email: str
Filter by email address.
mobile: str
Filter by mobile phone number
phone: str
Filter by phone number
state: str
Filter by state
`Returns:`
Parsons Table
See :ref:`parsons-table` for output options.
"""
params = {"email": email, "mobile": mobile, "phone": phone, "state": state}
tbl = Table(self._get_request("agents", params=params))
logger.info(f"Found {tbl.num_rows} agents.")
tbl = self._transform_table(tbl)
tbl = tbl.unpack_dict("contact", prepend=False)
tbl.remove_column("signature") # Removing since raw HTML might cause issues.
return tbl