Onegov Ticket API

Models

class onegov.ticket.model.Ticket(**kwargs)[source]

Defines a ticket.

id

the internal number of the ticket -> may be used as an access key for anonymous users

number

the unique ticket number known to the end-user -> do not use this to access the ticket as an anonymous user, the number is unique, but it’s not unguessable!

title

the title of the ticket

subtitle

the subtitle of the ticket for extra information about it’s content

group

the group this ticket belongs to. used to differentiate tickets belonging to one specific handler (handler -> group -> title)

handler_code

the name of the handler associated with this ticket, may be used to create custom polymorphic subclasses of this class. See http://docs.sqlalchemy.org/en/improve_toc/ orm/extensions/declarative/inheritance.html.

handler_id

a unique id for the handler record

handler_data

the data associated with the handler, not meant to be loaded in a list, therefore deferred.

snapshot

a snapshot of the ticket containing the last summary that made any sense use this before deleting the model behind a ticket, lest your ticket becomes nothing more than a number.

last_state_change

a timestamp recorded every time the state changes

reaction_time

the time in seconds between the ticket’s creation and the time it got accepted (changed from open to pending)

process_time

the time in seconds a ticket was in the pending state - may be a moving target, so use current_process_time to get the adjusted process_time based on the current time. process_time itself is only accurate if the ticket is closed, so in reports make sure to account for the ticket state.

muted

true if the notifications for this ticket should be muted

state

the state of this ticket (open, pending, closed)

user_id

the user that owns this ticket with this ticket (optional)

property extra_localized_text

Maybe used by child-classes to return localized extra data that should be indexed as well.

property es_suggestion

Returns suggest-as-you-type value of the document. The field used for this property should also be indexed, or the suggestion will lead to nowhere.

If a single string is returned, the completion input equals the completion output. (My Title -> My Title)

If an array of strings is returned, all values are possible inputs and the first value is the output. (My Title/Title My -> My Title)

property handler

Returns an instance of the handler associated with this ticket.

create_snapshot(request)[source]

Takes the current handler and stores the output of the summary as a snapshot.

TODO: This doesn’t support multiple langauges at this point. The language of the user creating the snapshot will be what’s stored.

In the future we might change this by iterating over all supported languages and creating the summary for each language.

Collection

class onegov.ticket.collection.TicketCollectionPagination(session, page=0, state='open', handler='ALL', group=None, owner='*', extra_parameters=None)[source]
subset()[source]

Returns an SQLAlchemy query containing all records that should be considered for pagination.

property page_index

Returns the current page index (starting at 0).

page_by_index(index)[source]

Returns the page at the given index. A page here means an instance of the class inheriting from the Pagination base class.

class onegov.ticket.collection.TicketCount(open, pending, closed)
property closed

Alias for field number 2

property open

Alias for field number 0

property pending

Alias for field number 1

class onegov.ticket.collection.TicketCollection(session, page=0, state='open', handler='ALL', group=None, owner='*', extra_parameters=None)[source]
issue_unique_ticket_number(handler_code)[source]

Randomly generates a new ticket number, ensuring it is unique for the given handler_code.

The resulting code is of the following form:

XXX-0000-1111

Where XXX is the handler_code and the rest is a 12 character sequence of random numbers separated by dashes.

This gives us 10^8 or 100 million ticket numbers for each handler.

Though we’ll never reach that limit, there is an increasing chance of conflict with existing ticket numbers, so we have to check against the database.

Still, this number is not unguessable (say in an URL) - there we have to rely on the internal ticket id, which is a uuid.

In a social engineering setting, where we don’t have the abilty to quickly try out thousands of numbers, the ticket number should be pretty unguessable however.

open_ticket(handler_code, handler_id, **handler_data)[source]

Opens a new ticket using the given handler.

Handler

class onegov.ticket.handler.Handler(ticket, handler_id, handler_data)[source]

Defines a generic handler, responsible for a subset of the tickets.

onegov.ticket is meant to be a rather generic bucket of tickets, to which varying modules submit tickets with varying content and different actionables.

Each module wanting to submit tickets needs to implement a handler with a unique id and a unique short code. The short code is added in front of the ticket number.

Tickets submitted to the database are shown in a list, without handler involvement. When a ticket is displayed, the handler is called with whatever data the handler supplied during ticket submission.

The handler then uses the handler data to access whatever data it needs to display a summary as well as links to certain actions (possibly a link to the original item, links that change the state of the ticket as well as the data associated with the handler, etc.).

refresh()[source]

Updates the current ticket with the latest data from the handler.

property email

Returns the email address behind the ticket request.

property title

Returns the title of the ticket. If this title may change over time, the handler must call self.refresh() when there’s a change.

property group

Returns the group of the ticket. If this group may change over time, the handler must call self.refresh() when there’s a change.

property deleted

Returns true if the underlying model was deleted. It is best to never let that happen, as we want tickets to stay around forever.

However, this can make sense in certain scenarios. Note that if you do delete your underlying model, make sure to call onegov.ticket.models.Ticket.create_snapshot() beforehand!

property extra_data

An array of string values which are indexed in elasticsearch when the ticket is stored there.

property payment

An optional link to a onegov.pay payment record.

property undecided

Returns true if there has been no decision about the subject of this handler.

For example, if a reservation ticket has been accepted, but the reservation has been neither confirmed nor cancelled, the ticket can be seen as undecided.

This is an optional flag that may be implemented by handlers. If a ticket is undecided, the UI might show a special icon and it might warn the user if he closes the ticket without making a decision.

By default, the ticket is assumed to be decided for backwards compatibility and for tickets where this does not make sense (a simple form submission may not have any way of knowing if there has been a decision or not).

classmethod handle_extra_parameters(session, query, extra_parameters)[source]

Takes a dictionary of extra parameters and uses it to optionally modifiy the query used for the collection.

Use this to add handler-defined custom filters with extra query parameters. Only called if the collection is already limited to the given handler. If all handlers are shown in the collection, this method is not called.

If no extra paramaters were given, this method is not called.

Returns the modified or unmodified query.

get_summary(request)[source]

Returns the summary of the current ticket as a html string.

Returns the links associated with the current ticket in the following format:

[
    ('Link Title', 'http://link'),
    ('Link Title 2', 'http://link2'),
]

If the links are not tuples, but callables, they will be called with the request which should return the rendered link.