`tickets` (Ticket management)¶

The lino_xl.lib.tickets plugin adds functionality for managing tickets.

Side note: Code snippets (lines starting with >>>) in this document get tested as part of our development workflow. The following initialization snippet tells you which demo project is being used in this document.

>>> from lino import startup
>>> startup('lino_book.projects.noi1e.settings.demo')
>>> from lino.api.doctest import *

Overview ¶

This plugin also installs comments : The comments framework. Users can comment on a ticket.

Tickets are grouped into sites. Users must be subscribed to a site in order to report tickets on a site. All the subscribers of a site will get notified about new tickets, changes and new comments to a ticket. The site* of a ticket indicates who is going to watch changes on that ticket.

Tickets ¶

class lino_xl.lib.tickets.Ticket¶

The Django model used to represent a ticket.

A ticket has the following database fields.

Different relations to users:

user¶: The author or reporter of this ticket. The user who reported this ticket to the database and is responsible for managing it.

end_user¶: The end user who is asking for help. This may be an external person who is not registered as a system user.

assigned_to¶: The user who has been assigned to work on this ticket.

Descriptive fields:

description¶

A complete and concise description of the ticket. This should describe in more detail what this ticket is about. If the ticket has evolved during time, it should reflect the latest version.

The description can contain memo commands defined by the application.

order¶

The business document used by both partners as reference for invoicing this ticket.

This field is a dummy field when invoicing is not installed.

When this is empty, work on this ticket won’t be invoiced to anybody. Points to a invoicing.order_model.

site¶: The site this ticket belongs to. You can select only sites you are subscribed to.

ticket_type¶: The type of this ticket. The site manager can configure the list of available ticket types.

upgrade_notes¶: A formatted text field meant for writing instructions for the hoster’s site manager when doing an upgrade where this ticket is being deployed.

waiting_for¶: What to do next. An unformatted one-line text which describes what this ticket is waiting for.

state¶

The workflow state of this ticket.

The list of available states (TicketStates) is defined by the application developer but may have local modifications.

Relations to other tickets:

duplicate_of¶

A pointer to another ticket which is regarded as the first occurence of the same problem.

A ticket with a non-empty duplicate_of field can be called a “duplicate”. The number (primary key) of a duplicate is theoretically higher than the number of the ticket it duplicates.

The state of a duplicate does not automatically become that of the duplicated ticket. Each ticket continues to have its own state. Example: Some long time ago, with Mathieu, we agreed that ticket #100 can go to Sleeping. Now Aurélie reported the same problem again as #904. This means that we should talk about it. And even before talking with her, I’d like to have a look at the code in order to estimate whether it is difficult or not, so I set the state of #904 to ToDo.

deadline¶

Specify that the ticket must be done for a given date.

TODO: Triagers should have a table of tickets having this field non-empty and are still in an active state.

private¶: Whether this ticket is to be treated confidentially.

urgent¶: Whether this ticket is to be treated urgently.

priority¶: An integer value used in the order’s backlog and in the worker’s to-do list.

rating¶: How the author rates the work which has been done on this ticket.

reporting_type¶: An indication about who is going to pay for work on this site. See ReportingTypes.

quick_assign_to¶: Show the site user who is assigned to work on this ticket, along with other candidates. Click on another candidate in order to quickly reassign the ticket to that user.

Custom actions:

spawn_ticket¶

Create a new ticket that will be a child of this ticket.

The parent field of the new ticket will point to the current ticket.

quick_assign_to_action¶: Ask to pick another user and then assign that user to this ticket.

Ticket state ¶

The state of a ticket expresses in which phase of its life cycle this ticket is.

You can see which ticket states are defined on your site using Explorer ‣ Tickets ‣ Ticket states.

See lino_noi.lib.tickets.TicketStates for a real world example.

>>> rt.show(tickets.TicketStates)
======= =========== ========== ============= ========
 value   name        text       Button text   Active
------- ----------- ---------- ------------- --------
 10      new         New        ⚹             Yes
 15      talk        Talk       ☎             Yes
 20      opened      Open       ☉             Yes
 22      working     Working    ⚒             Yes
 30      sleeping    Sleeping   ☾             No
 40      ready       Ready      ☐             Yes
 50      closed      Closed     ☑             No
 60      cancelled   Refused    ☒             No
 70      waiting     Waiting    ⧖             No
======= =========== ========== ============= ========

class lino_xl.lib.tickets.TicketStates¶

The choicelist for the state of a ticket.

new¶: Somebody reported this ticket, but there was no response yet. The ticket needs to be triaged.

talk¶: Some worker needs discussion with the author. We don’t yet know exactly what to do with it.

todo¶: The ticket is confirmed and we are working on it. It appears in the todo list of somebody (either the assigned worker, or our general todo list)

testing¶: The ticket is theoretically done, but we want to confirm this somehow, and it is not clear who should do the next step. If it is clear that the author should do the testing, then you should rather set the ticket to talk. If it is clear that you (the assignee) must test it, then leave the ticket at todo.

sleeping¶: Waiting for some external event. We didn’t decide what to do with it.

ready¶: The ticket is basically done, but some detail still needs to be done by the user (e.g. testing, confirmation, documentation,..)

done¶: The ticket has been done.

cancelled¶: It has been decided that we won’t fix this ticket.

There is also a “modern” series of symbols, which can be enabled using the use_new_unicode_symbols site setting. When this is True, ticket states are represented using symbols from the Miscellaneous Symbols and Pictographs block, otherwise we use the more widely supported “classical” symbols from Miscellaneous Symbols

Sites ¶

A site is a place where work is being done. Sites can be anything your team uses for grouping their tickets into more long-term “tasks” or “projects”. Zulip calls them “streams”, Slack calls them “Channels”.

class lino_xl.lib.tickets.Site¶

The Django model representing a site.

description¶

reporting_type¶

state¶

ref¶

name¶

company¶

contact_person¶

deadline¶

class lino_xl.lib.tickets.Sites¶

Base class for all Sites tables.

watcher¶

show_exposed¶

state¶

class lino_xl.lib.tickets.MySites¶

Shows the sites for which I have a subscription.

Sleeping and closed sites are not shown by default.

class lino_xl.lib.tickets.AllSites¶: Shows all sites in explorer menu.

Ticket types ¶

A ticket type, or the type of a ticket, is a way to classify that ticket. This information may be used in service reports or statistics defined by the application.

You can configure the list of ticket types via Configure ‣ Tickets ‣ Ticket types.

class lino_xl.lib.tickets.TicketType¶

The Django model used to represent a ticket type.

name¶

reporting_type¶: Which reporting type to use in a service report. See :class:ReportingTypes`.

class lino_xl.lib.tickets.TicketTypes¶: The list of all ticket types.

Plugin configuration ¶

See lino_xl.lib.tickets.Plugin.

Discussions ¶

Should we replace the Ticket.duplicate_of field by a link type (an additional choice in LinkTypes) called “Duplicated/Duplicated by”? No. We had this before and preferred the field, because a field is at least one click less, and because we want users to define a clear hierarchy with a clear root ticket. You can have a group of tickets which are all direct or indirect duplicates of this “root of all other problems”.

Sometimes there is nothing to do for a ticket, but it is not “sleeping” because it might become active at any moment when some kind of event happens. (e.g. a customer answers a callback, a server error occurs again). Should we introduce a new state “Waiting” to differentiate such tickets from those who went asleep due to lack of attention? Rather not. That’s what “Sleeping” (also) means. A sleeping ticket can wake up any time. We just don’t want to be reminded about it all the time. One challenge is that when the “trigger” occurs which would wake up the sleeping ticket. At that moment we don’t want to create a new ticket just because we forgot about the sleeping one. To avoid this we must currently simply search in “All tickets” before creating a new one.

Other languages ¶

The ticket states in German:

>>> rt.show(tickets.TicketStates, language="de")
====== =========== ================ ============= =======
 Wert   name        Text             Button text   Aktiv
------ ----------- ---------------- ------------- -------
 10     new         Neu              ⚹             Ja
 15     talk        Besprechen       ☎             Ja
 20     opened      Offen            ☉             Ja
 22     working     In Bearbeitung   ⚒             Ja
 30     sleeping    Schläft          ☾             Nein
 40     ready       Bereit           ☐             Ja
 50     closed      Abgeschlossen    ☑             Nein
 60     cancelled   Abgelehnt        ☒             Nein
 70     waiting     Wartet           ⧖             Nein
====== =========== ================ ============= =======

Views reference ¶

There are many tables used to show lists of tickets.

class lino_xl.lib.tickets.Tickets¶

Base class for all tables of tickets.

Filter parameters:

site¶: Show only tickets within this project.

show_private¶: Show only (or hide) tickets that are marked private.

show_todo¶: Show only (or hide) tickets that are todo (i.e. state is New or ToDo).

show_active¶: Show only (or hide) tickets which are active (i.e. state is Talk or ToDo).

show_assigned¶: Show only (or hide) tickets that are assigned to somebody.

has_site¶: Show only (or hide) tickets which have a site assigned.

feasable_by¶: Show only tickets for which the given supplier is competent.

class lino_xl.lib.tickets.AllTickets¶: Shows all tickets.

class lino_xl.lib.tickets.RefTickets¶: Shows all tickets that have a reference.

class lino_xl.lib.tickets.PublicTickets¶: Shows all public tickets.

class lino_xl.lib.tickets.TicketsToTriage¶: Shows tickets that need to be triaged. Currently this is equivalent to those having their state set to new.

class lino_xl.lib.tickets.TicketsToTalk¶

class lino_xl.lib.tickets.TicketsNeedingMyFeedback¶

Shows tickets that are waiting for my feedback.

These are tickets in state Talk where you are not the last commenter. Only tickets on sites that you are subscribed to. Includes tickets with no comments.

class lino_xl.lib.tickets.MyTicketsNeedingFeedback¶

Shows tickets assigned to me and waiting for feedback from others.

Shows tickets of sites that you are subscribed to which are in state Talk where you are the last commenter.

class lino_xl.lib.tickets.UnassignedTickets¶

class lino_xl.lib.tickets.ActiveTickets¶: Show all tickets that are in an active state.

class lino_xl.lib.tickets.MyTickets¶: Show all active tickets reported by me.

class lino_xl.lib.tickets.TicketsByEndUser¶

Show the tickets introduced on behalf of this end user.

In other words, the tickets having this person in their end_user field.

See also tickets.end_user_model

>>> alf = contacts.Person.objects.get(pk=114)
>>> rt.login('robin').show(tickets.TicketsByEndUser, alf, display_mode="grid")
===== ============================== ============ =====================================================
 ID    Summary                        Team         Workflow
----- ------------------------------ ------------ -----------------------------------------------------
 Foo never bars                 Sales team   [▶] **☾ Sleeping** → [⚹] [☎] [⧖]
 How can I see where bar?                    [▶] **☑ Closed** → [⚹] [☾] [☎] [☉]
  Bar cannot baz                              [▶] **☒ Refused** → [⚹] [☾] [☎] [☉]
  Cannot delete foo              Developers   [▶] **⚹ New** → [☾] [☎] [☉] [⚒] [☐] [☑] [⧖]
  Misc optimizations in Baz      Sales team   [▶] **☎ Talk** → [⚹] [☾] [☉] [⚒] [☐] [☑] [☒] [⧖]
  Foo never bars                 Sales team   [▶] **☾ Sleeping** → [⚹] [☎] [⧖]
  Irritating message when bar    Managers     [▶] **☐ Ready** → [⚹] [☾] [☎] [☑] [☒]
  Bar cannot baz                              [▶] **☒ Refused** → [⚹] [☾] [☎] [☉]
  No more foo when bar is gone                [▶] **⧖ Waiting** → [⚹] [☾] [☎] [☉]
  Misc optimizations in Baz      Sales team   [▶] **☎ Talk** → [⚹] [☾] [☉] [⚒] [☐] [☑] [☒] [⧖]
  Foo never bars                 Sales team   [▶] **☾ Sleeping** → [⚹] [☎] [⧖]
  Irritating message when bar    Managers     [▶] **☐ Ready** → [⚹] [☾] [☎] [☑] [☒]
  Bar cannot baz                              [▶] **☒ Refused** → [⚹] [☾] [☎] [☉]
  No more foo when bar is gone                [▶] **⧖ Waiting** → [⚹] [☾] [☎] [☉]
  Class-based Foos and Bars?     Sales team   [▶] **☎ Talk** → [⚹] [☾] [☉] [⚒] [☐] [☑] [☒] [⧖]
   Foo and bar don't baz                       [▶] **⚒ Working** → [⚹] [☾] [☎] [☉] [☐] [☑] [☒] [⧖]
===== ============================== ============ =====================================================

>>> rt.show(tickets.TicketsByEndUser, alf, display_mode="summary")
`#113 <…>`__, `#91 <…>`__, `#83 <…>`__, `#77 <…>`__, `#47 <…>`__, `#41 <…>`__, `#11 <…>`__

>>> rt.show(tickets.TicketsByEndUser, alf, display_mode="list")
- [#113 (Foo never bars)](…) (by [Jean](…) in [Sales team](…))

- [#91 (Cannot delete foo)](…) (by [Robin Rood](…) in [Developers](…) assigned
  to [Rolf Rompen](…))

- [#83 (Misc optimizations in Baz)](…) (by [Rolf Rompen](…) in [Sales team](…)
  assigned to [Luc](…))

- [#77 (Foo never bars)](…) (by [Robin Rood](…) in [Sales team](…) assigned to
  [Romain Raffault](…))

- [#47 (Misc optimizations in Baz)](…) (by [Romain Raffault](…) in [Sales
  team](…) assigned to [Romain Raffault](…))

- [#41 (Foo never bars)](…) (by [Rolf Rompen](…) in [Sales team](…))

- [#11 (Class-based Foos and Bars?)](…) (by [Mathieu](…) in [Sales team](…)
  assigned to [Romain Raffault](…))

class lino_xl.lib.tickets.TicketsByType¶

class lino_xl.lib.tickets.DuplicatesByTicket¶: Shows the tickets which are marked as duplicates of this (i.e. whose duplicate_of field points to this ticket.

class lino_xl.lib.tickets.TicketsSummary¶: Abstract base class for ticket tables with a summary.

class lino_xl.lib.tickets.MyTicketsToWork¶: Show all active tickets assigned to me.

class lino_xl.lib.tickets.TicketsBySite¶

tickets (Ticket management)¶

`tickets` (Ticket management)¶