Merge tag '0.1.0' into develop

Release 0.1.0

CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+Thank you for being interested in contributing to Jicket!
+Please read this document carefully to avoid creating unnecessary work.
+
+# Project structure
+This project is structured like a basic python project.
+The root folder contains some files necessary for packaging, the docs folder and jicket itself.
+
+## Project files
+* `setup.py`
+
+  Python setup file
+
+* `requirements.txt`
+
+  List of all python requirements that need to be installed for development. Install with `pip install -r requirements.txt`
+
+## docs
+The docs folder contains the documentation hosted on [readthedocs](https://docs.readthedocs.io/en/latest/getting_started.html).
+
+## jicket
+Jicket package root. It contains the script in `bin`, unit tests in `tests` and the actual jicket module in `jicket`.

README.md

@@ -1 +1,15 @@
-# jicket
+[![Documentation Status](https://readthedocs.org/projects/jicket/badge/?version=stable)](https://jicket.readthedocs.io/en/latest/?badge=stable)
+
+# Jicket
+
+Jicket allows you to use Jira as a simple service helpdesk.
+It creates new issues for incoming mails and automatically adds email replies as comments to issues.
+
+# Documentation
+You can find the documentation [here](https://jicket.readthedocs.io/en/latest/).
+
+# Contributing
+See [CONTRIBUTING](CONTRIBUTING.md)
+
+# License
+MIT License, see [LICENSE](LICENSE) for the full license.

docs/conf.py

@@ -26,7 +26,7 @@
 # The short X.Y version
 version = ''
 # The full version, including alpha/beta/rc tags
-release = '0.0.1'
+release = '0.1.0'
 
 
 # -- General configuration ---------------------------------------------------
@@ -75,7 +75,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/configuration.rst

@@ -0,0 +1,264 @@
+Configuration
+==================================
+
+Jicket can be configured using both environment variables and command line arguments.
+Command line arguments take precedence over environment variables.
+
+.. warning:: Using environment variables for configuring the username and password is highly recommended.
+             If you pass them as command line arguments, they show up in the process list and will be readable for
+             anyone with even basic access to the server.
+
+
+IMAP
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Configuration of the IMAP mailbox that is used to read incoming mails from.
+
+Host
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_IMAP_HOST``
+:CLI:           ``--imaphost``
+:Type:          ``str``
+:Required:      Yes
+:Description:   URL of IMAP mailbox that is receiving new ticket emails
+:Example:       ``imap.example.com``
+
+Port
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_IMAP_PORT``
+:CLI:           ``--imaphost``
+:Type:          ``int``
+:Default:       ``993``
+:Required:      No
+:Description:   Port of IMAP host
+:Example:       ``993``
+
+User
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_IMAP_USER``
+:CLI:           ``--imapuser``
+:Type:          ``str``
+:Required:      Yes
+:Description:   Username for IMAP mailbox
+:Example:       ``foo@example.com``
+
+Password
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_IMAP_PASS``
+:CLI:           ``--imappass``
+:Type:          ``str``
+:Required:      Yes
+:Description:   Password for IMAP user
+:Example:       ``correcthorsebatterystaple``
+
+
+
+SMTP
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Configuration of the SMTP server that is used to send emails from.
+
+Host
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_SMTP_HOST``
+:CLI:           ``--smtphost``
+:Type:          ``str``
+:Required:      Yes
+:Description:   URL of SMTP server used to send out emails
+:Example:       ``smtp.example.com``
+
+Port
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_SMTP_PORT``
+:CLI:           ``--smtphost``
+:Type:          ``int``
+:Default:       ``587``
+:Required:      No
+:Description:   Port of SMTP server
+:Example:       ``587``
+
+User
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_smtp_USER``
+:CLI:           ``--smtpuser``
+:Type:          ``str``
+:Required:      No
+:Description:   Username for SMTP server. If it is not explicitly provided, IMAP username will be used.
+:Example:       ``foo@example.com``
+
+Password
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_SMTP_PASS``
+:CLI:           ``--smtppass``
+:Type:          ``str``
+:Required:      No
+:Description:   Password for SMTP user.  If it is not explicitly provided, IMAP password will be used.
+:Example:       ``correcthorsebatterystaple``
+
+
+
+Jira
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Configuration of jira instance on which new issues shall be created from incoming emails.
+
+Host
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_JIRA_URL``
+:CLI:           ``--jiraurl``
+:Type:          ``str``
+:Required:      Yes
+:Description:   URL of Jira instance that shall be used
+:Example:       ``jira.example.com``
+
+Port
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_JIRA_USER``
+:CLI:           ``--jirauser``
+:Type:          ``str``
+:Required:      Yes
+:Description:   Username for Jira access
+:Example:       ``foo@example.com``
+
+User
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_JIRA_PASS``
+:CLI:           ``--jirapass``
+:Type:          ``str``
+:Required:      Yes
+:Description:   Password for Jira user
+:Example:       ``correcthorsebatterystaple``
+
+Password
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_JIRA_PROJECT``
+:CLI:           ``--jiraproject``
+:Type:          ``str``
+:Required:      Yes
+:Description:   The Project key in which new issues shall be created. It can be found in the URL of your project.
+:Example:       ``SHD``
+
+Email
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Configuration regarding the mailbox and emails in general
+
+Inbox
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_FOLDER_INBOX``
+:CLI:           ``--folderinbox``
+:Type:          ``str``
+:Default:       ``INBOX`` (This is the name for the default IMAP inbox)
+:Required:      No
+:Description:   Folder from which emails shall be fetched for parsing. Using the default IMAP inbox is recommended
+                unless you know what you're doing.
+:Example:       ``mycoolfolder``
+
+Success
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_FOLDER_SUCCESS``
+:CLI:           ``--foldersuccess``
+:Type:          ``str``
+:Default:       ``jicket``
+:Required:      No
+:Description:   Imap folder to which successfully imported emails shall be moved. The folder must exist and must not be
+                the same as ``JICKET_FOLDER_INBOX``.
+:Example:       ``myothercoolfolder``
+
+Thread template
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_THREAD_TEMPLATE``
+:CLI:           ``--threadtemplate``
+:Type:          ``str``
+:Required:      Yes
+:Description:   Path to HTML file containing template for ticket thread emails. Can be absolute or relative path.
+:Example:       ``/etc/jicket/threadtemplate.html``
+
+Ticket Address
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_TICKET_ADDRESS``
+:CLI:           ``--ticketaddress``
+:Type:          ``str``
+:Required:      Yes
+:Description:   Email address of ticket system. This is the address your customers should contact, and from which they
+                will in turn receive the ticket creation confirmation.
+:Example:       ``support@example.com``
+
+
+
+Operation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Configuration of jicket operation
+
+Loopmode
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_LOOPMODE``
+:CLI:           ``--loopmode``
+:Type:          ``str``
+:Default:       ``dynamic``
+:Required:      No
+:Description:   How the main loop shall operate.
+
+                dynamic
+                  After finishing with fetching and processing the main loop will sleep for ``JICKET_LOOPTIME`` before
+                  fetching again.
+
+                interval
+                  Tries to run the main loop exactly every ``JICKET_LOOPTIME`` seconds. If main loop execution takes
+                  longer than that, there is no break betwene subsequent executions.
+:Example:       ``interval``
+
+
+Looptime
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_LOOPTIME``
+:CLI:           ``--looptime``
+:Type:          ``float``
+:Default:       ``60``
+:Required:      No
+:Description:   Length between loop execution. Also see ``JICKET_LOOPMODE`` how exactly this time is applied.
+:Example:       ``120``
+
+
+
+Ticket ID
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Miscellaneous configuration
+
+Prefix
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_ID_PREFIX``
+:CLI:           ``--idprefix``
+:Type:          ``str``
+:Default:       ``JI-``
+:Required:      No
+:Description:   A prefix that is prepended to ticket IDs. This could for example be your company initials.
+:Example:       ``EC-`` will produce ticket IDs like ``[#EC-XXXXX]``
+
+Hash salt
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_ID_SALT``
+:CLI:           ``--idsalt``
+:Type:          ``str``
+:Default:       ``JicketSalt``
+:Required:      No
+:Description:   The salt for hashing ticket IDs. Only needs to be set if you don't want your users to be able to find
+                out the true ID of the ticket (which is the email's UID).
+:Example:       ``VerySecretSalt``
+
+Hash alphabet
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_ID_ALPHABET``
+:CLI:           ``--idalphabet``
+:Type:          ``str``
+:Default:       ``ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890``
+:Required:      No
+:Description:   Alphabet for hashing. The generated hash will only consist of letters from this alphabet.
+:Example:       ``ABCD1234``
+
+Hash minimum length
+""""""""""""""""""""""""""""""""""
+:Environment:   ``JICKET_ID_ALPHABET``
+:CLI:           ``--idalphabet``
+:Type:          ``int``
+:Default:       ``6``
+:Required:      No
+:Description:   Minimum length of generated hash. If the email uid is low, a hash might consist of only one character if
+                no minimum length is set. Must be positive or zero.
+:Example:       ``0``

docs/howitworks.rst

@@ -0,0 +1,38 @@
+Overview
+==================================
+The goal of jicket was to create a stateless email importer to turn a Jira issue board into a very simple service
+helpdesk. Stateless means that all necessary information for operating is inferred from the emails themselves
+and Jira. This makes updating or migrating your jicket instance very easy, as you don't have to migrate any state data.
+
+Ticket process
+----------------------------------
+Jicket is continuously monitoring a mailbox for incoming emails. It parses those emails and then processes the email
+depending on the content. If the processing and subsequent import in Jira was successful, the email is moved into a
+specified folder from where on your service staff can interact with them.
+
+When a mail is processed, jicket checks if the subject contains a ``X-Jicket-HashID`` header or if the subject line
+contains a ticket ID. If it does, the email is imported as a reply to an existing issue. If not, a new issue is created
+from the email.
+
+
+New issue
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+When an email is identified as a new communication, jicket generates a new ticket ID and adds a new issue to the
+configured project. To confirm the creation of the ticket, an email is sent out to the customer and the ticket address
+which is meant to start an email thread. Also included is a modified subject which contains the ticket ID for this
+issue.
+
+An example conversation could look like this:
+::
+    Feature XY broken                                       Customer <foo@customer.com>
+    ├── [#JI-ZOZ2P6] Feature XY broken                      Jicket <support@company.com>
+    │   ├── RE: [#JI-ZOZ2P6] Feature XY broken              Fred Bobber <f.bobber@company.com>
+    │   │   ├── RE: RE: [#JI-ZOZ2P6] Feature XY broken      Customer <foo@customer.com>
+    │   │   ├── RE: RE: [#JI-ZOZ2P6] Feature XY broken      Samantha Else <s.else@company.com>
+
+
+
+Reply to existing Issue
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+If the email is identified as a reply to an existing issue, a comment with the email's content is added to the issue.
+No further confirmation is sent to the customer.

docs/index.rst

@@ -3,13 +3,25 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Jicket's documentation!
+Welcome to Jicket
 ==================================
 
+Jicket enables you to create a basic service helpdesk in Jira using Emails.
+It automatically creates issues for incoming emails and appends responses as comments.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: General
+
+   howitworks
+
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: Setup
 
+   installation
+   configuration
 
 
 Indices and tables