Ticketsystem

A TicketSystem object represents a connection definition to a space in an external ticket system. Part of this is a base URL, and some system specific identifier for e.g. a project on that system. If the access needs some kind of authentication, this has to be configured in this object on creation.

create new instance

The constructor of TicketSystem is not publicly callable. Acquiring an instance has to be done either by passing an URI or using the builder mechanism.

by URI

This library has a global definition, for how an URI has to start. The end of it is defined by each system specific implementation.

global URI definition

unifiedticketing:<system identifier>:<additional information>
For system specific details look into the systems part of this docs

To instantiate a TicketSystem from an URI, call the static method fromUri(String):

TicketSystem ts = TicketSystem.fromUri(<uri>);

Warning

If the given String does not match the criteria for a valid URI, or the system identifier is unknown, it throws an AssertionException

by builder

The library has a builder mechanism defined to instantiate a new TicketSystem object, using fluent-api. To start it, call the static method fromBuilder().
The returning object gives you all supported systems as choice, which then brings you to the system specific builder mechanism.

At the end, you'll have to finish the building process with a call to build().

Warning

If not all mandatory information where given before calling build(), it will throw an AssertionException

configuration options

You can set configurations of two kinds:

• simple boolean switches to enable/disable a behaviour/feature
• string values

To set a configuration, call the instance method config. It provides two signatures:

• config(TicketSystem.ConfigurationOption, boolean)
• config(TicketSystem.ConfigurationOption, String)

currently available configuration options

ConfigurationOption	type	default	description
RETURN_NULL_ON_ERROR	boolean	false	If true, don't throw exception on error, but return null or the calling object, if in fluent-api.

Warning

option RETURN_NULL_ON_ERROR is not fully implemented and tested yet.
Expect it still throws Exceptions sometimes, but returns null/self also sometimes.

list tickets

Tickets are requested by using the filter mechanism. To get all Tickets just don't define any filters before calling get(). They are returned as List<Ticket>.

default pagination

many systems have an implicit default pagination enabled, which could block you from simply getting all tickets.

you can ask the TicketSystem object, to tell you if it uses a default pagination:

ts.hasDefaultPagination();

assignees

Tickets have a field of type Assignee. These have final String fields, where the system implementation puts values if supported.

requesting tickets

ts.find()
    .setPage(1)
    .setPageSize(10)
    .get();

You can add various filter options, before finally calling get(). Each supported systems implementation is free to define special filter options. These are only callable, if your variable has the dedicated child-type.

The globally available ones are listed below. They are marked single or multi types. A single typed filter will override previous values, whereas multi typed ones will be added to the previous values.

filter option method definition	type	description
isClosed()	single	returns only tickets closed, or considered closed by the system specific implementation
isOpen()	single	returns only tickets open, or considered open by the system specific implementation
setPage(int)	single	page number of pagination to request
setPageSize(int)	single	page size of request to paginate with
withAssigneeId(String)	multi	tickets with given assigneeId as assignee. On multiple calls ticket must have ALL given ids as assignees
withAssigneeName(String)	multi	same as assigneeId above
withDescriptionContain(String)	single	substring the description has to contain
withDescriptionMatch(String)	single	fully qualified regular expression, the whole description has to match
withId(String)	multi	id a ticket must have. multiple calls keeps tickets matching any of the set ids
withLabel(String)	multi	label a ticket must have. Multiple calls a ticket must have all given labels
withTitleContain(String)	single	substring the title has to contain
withTitleMatch(String)	single	fully qualified regular expression, the whole title has to match

get single ticket

To request a single ticket the method getTicketById is provided, available with two signatures: - getTicketById(String) - getTicketById(int)

The integer variant is just for convenience, if you have the id as number. It calls the String one with your number transformed.

Example

Ticket t = ts.getTicketById("5");

create new ticket

The creation of a new Ticket is started by calling createTicket().
This starts another fluid-api chain, in which you can set everything your new ticket should contain. The chain finishes calling create() at the end.

Warning

if a mandatory information for ticket creation is not given, prior calling create(), an AssertionException is thrown.

Example

Ticket t = ts.createTicket()
    .title("some title")
    .create();

Global available setters for ticket creation are:

method	additional information
assignees(String[])	array of assignee identifiers, check system specific part, what to pass
description(String)
labels(Set<String>) labels(String[])
title(String)