--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/ticket.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,72 @@
+=================================
+ticket: create and manage tickets
+=================================
+
+Ticket is a generic tools to create items with metadata and states (where state can be
+``queued``, ``done``, etc). This can be used for many things, from TODO list to bugs
+management.
+
+get
+===
+
+Retrieve one or more tickets and display them. A project may use magic string in README to
+indicate PubSub service and node to use, in which case use just need to be in the
+directory of the project.
+
+examples
+--------
+
+Retrieve last 5 tickets (ordered by creation) from a project using magic string in README::
+
+  $ jp ticket get -m 5 -o creation
+
+Retrieve the ticket with id ``123`` on service ``pubsub.example.org``::
+
+  $ jp ticket get -s pubsub.example.org -i 123
+
+
+
+import
+======
+
+Import tickets from an external source. This works in the same way as
+:ref:`jp-blog_import`: you need to specify an importer and a data location. If you let
+both positional argument empty, you'll get list of importers, if you specify importer but
+not data location, you'll get a description on how the importer works.
+
+If you want to see a progress bar for the import, use the ``-P, --progress`` option, this
+is recommended for most imports.
+
+Some importers may have specific option (check description for details), you can specify
+them with ``o NAME VALUE, --option NAME VALUE``
+
+When you import a ticket, the ticket will be created according to the schema of the PubSub
+node. By default, the metadata of the original ticket will be put to the one of the same
+name in the dest PubSub item. But of course the schema of your destination PubSub node may
+differ from the original metadata. In this case, you can use ``-m IMPORTED_FIELD
+DEST_FIELD, --map IMPORTED_FIELD DEST_FIELD`` to specify how the mapping mus be done
+(``IMPORTED_FIELD is the name of the field in the original ticket, while ``DEST_FIELD`` if
+the name of the field in your node schema).
+
+
+examples
+--------
+
+Get list of ticket importers::
+
+  $ jp ticket import
+
+Get description of ticket importer for Bugzilla::
+
+  $ jp ticket import bugzilla
+
+Import tickets from a Bugzilla XML export file at ``~/bugzilla_export.xml`` to the
+``pubsub.example.org`` PubSub service. We use default tickets node and want a progression
+bar::
+
+  $ jp ticket import -P -s pubsub.example.org ~/bugzilla_export.xml
+
+Same import, but this time we want to map the field ``assigned_to_name`` from Bugzilla to
+the field ``assigned_to`` in our schema::
+
+  $ jp ticket import -P -s pubsub.example.org -m assigned_to_name assigned_to ~/bugzilla_export.xml