probesys / bileto Goto Github PK

Estimation: 2d

User story

As a commercial,
I want to create a contract associated to a customer
So I can track the time spent for a customer and don't work more than what was in the contract.

Overview

The contracts are listed and created in the organizations.
The contracts are listed in the sub-organizations as well.

A contract has a name, a start and an end dates, and a number of hours. It also has private notes.

The contracts are listed in descending order of end date.

At the moment, the list shows the name, the dates and the number of hours + a status:

• coming: start date is in the future
• ongoing: current date is between start and end date
• finished: end date is in the past

Technical

Entity

We need a new Contract entity:

• name (string 255)
• start_at (datetimetz, must be rounded to 00:00:00)
• end_at (datetimetz, must be rounded to 23:59:59)
• max_hours (int > 0)
• notes (text)

Permissions

Three new permissions are required:

• orga:see:contracts
• orga:see:contracts:notes
• orga:manage:contracts

As technical,
I want to answer to the requester through the interface,
so I can ask her missing info, inform her of the progress, or plan interventions.

Requirements:

• the answer is visible in the ticket as well as answers of the requester
• the answer is sent by email to the requester and observers
  • sending email must be possible through a dedicated mail server so it is not considered as spam

As technical,
I want to change the type of the ticket (i.e. incident or request),
so I can do statistics and ensure appropriate prioritization and billing.

Estimation: 2d

Overview

Tickets must be assigned to contracts.
Most of the time, a ticket is assigned to a single contract.
However, if a contract is ended, the ticket can be assigned to a new contract.

The ongoing contract appears in the column on the right, below the priority block.
It shows the name of the contract and the number of hours in the contract.
When there is no contract, it is suggested to assign an ongoing contract (only if there is at least one).

When a ticket is created, it is automatically assigned to the ongoing contract.
If there are several ongoing contracts, no contract is assigned (it must be done manually on the ticket page).

The contract of a ticket can be changed or removed.

Technical

Permissions

Two new permissions must be added:

• orga:see:tickets:contracts
• orga:update:tickets:contracts

Entity

The tickets and the contracts are linked via a ManyToMany relation.

As technical,
I want to add a confidential note to a ticket,
so I can give more information to other technical users.

As a user,
I want to filter tickets by their attributes,
so I quickly find those that interest me.

As a manager,
I want to validate tickets
So I can take my responsibilities and verify people work and requests.

Requirements / comments:

• it should be possible to have several people to validate (eventually in an order manner)
• people who are waiting for the validation should not be able to modify the ticket anymore (or maybe just to comment)

As technical, requester or observer,
I want to make a link between a ticket and the assets,
so I have a tickets history of an asset.

The command make i18n-extract doesn't delete the unused translations keys. We would need to add the --clean flag to the translation:extract command. Unfortunately, this flag also removes some keys that are used such as "Invalid credentials" (I think it's a bug on Symfony side).

• actions/checkout and actions/cache must use v3
• set-output must be replaced

I'll wait for actions/cache#953 to be resolved.

See warnings at https://github.com/Probesys/bileto/actions/runs/3241155029 for instance.

As technical,
I want to keep a ticket in its terminated status when I receive acknowledgments from the requester,
so I don't have to close it again.

Requirements / comments:

• it is not easy an easy ticket to do because the ticket should be reopened when the problem is not solved
  • we could provide a way in the email to directly acknowledge (some kind of link to click on)
  • an initial idea was to automatically close the ticket after X days (or to plan the closing)

As technical,
I want to mark a ticket as waiting from another actor (requester or observer),
so I don't see it any longer in my "in progress" list.

Requirements / comments:

• time spent in "pending" status doesn't count for SLAs
• it must be possible to answer to the requester and to change to "pending" in a single move

As technical,
I want to find a closed ticket,
so I can refer to it.

As technical,
I want to link tickets with each other,
so I can reference and close duplicated or related tickets with one action.

Requirements / comments:

• linked tickets can have different relations:
  • duplicated tickets
  • child/parent tickets
  • related? (default?)
  • other?

As technical,
I want to promote an answer as a solution to a ticket,
so I can see it at a glance and let to know the requester and observers about the solution.

Requirements / comments:

• a ticket may have only one solution (when a new answer is marked as the solution, the old one goes back to a "simple" answer)
• the solution could be promoted to the top of the ticket? (as in the forums)
• when marking an answer as a solution, the ticket must pass to resolve
• marking an answer as a solution should be possible during writing or afterward
• the requester should be able to refuse a solution (related to #34)
• marking an answer could send a specific notification: we talked about customers who want to receive the whole ticket by email so they can archive it in their emails. This specific use case might be resolved differently but I don't know yet if we need to open a specific issue / user story for that

As technical,
I want to assign someone to a ticket,
so the problem of the end-user is handled by someone.

Requirements:

• it must be possible to assign to oneself, or to other support users
• assignation is handled by only one person
• if someone intervenes in the ticket, it is automatically assigned to her

We have a public instance of Weblate (i18n.probesys.com) that we could use to welcome contributions to translations.

There is no official Symfony translation provider for Weblate, but we may want to use m2mtech/weblate-translation-provider (the project doesn't seem to be very active though).

HTTP defines the Accept-Language header. It can be used to select a default locale for the user.

It could be used in the LocaleSubscriber, e.g.:

$preferredLocale = self::getPreferredLocaleFromAcceptLanguage($request);
if (!$preferredLocale) {
    $preferredLocale = $this->defaultLocale;
}
$locale = $request->getSession()->get('_locale', $preferredLocale);
$request->setLocale($locale);

Alternatively, Symfony provides the set_locale_from_accept_language option to do this automatically. It seems not to be as simple as setting it to true because of the current setup with LocaleSubscriber.

References:

• https://tools.ietf.org/html/rfc7231#section-5.3.5
• https://github.com/Probesys/bileto/blob/main/src/EventSubscriber/LocaleSubscriber.php
• https://symfony.com/doc/current/reference/configuration/framework.html#set-locale-from-accept-language

Follow-up of #38

At the moment, the dates are formatted with format('Y-m-d') which is not very user friendly. I'd like to offer three different options :

• relative time (e.g. "today", "3 days ago") with full date on hover (title attribute)
• full date (e.g. "7 nov. 2022 11:45"), eventually without the time (but still visible on hover)
• auto mode (relative for close dates, full for older dates)

Dates also have to be translated.

References:

• https://twig.symfony.com/doc/3.x/filters/format_datetime.html
• https://www.php.net/manual/en/intldateformatter.format.php

As technical,
I want to add an answer that a requester or observer gave me by a different channel,
so the ticket history stays complete and coherent

Requirements / comments:

• it should be possible to precise the source channel

As a user,
I want to search in the tickets,
so I quickly find those that interest me.

Requirements / comments:

• search should happen at least on titles, ids and uids / URL
• but probably on messages too

Estimation: 2d

User story

As a commercial,
I want to renew a contract
So the tech know they can continue to work for a customer.

Overview

On the contract page, a button to renew the contract must be added.
Renewing the contract is like creating a new contract with the start date beginning the next day after the end date of the renewed contract, and with the same name, duration and hours.
The user must be able to change these settings though.

A contract can be renewed in advance.
If the contract is renewed for today or before, the contract must be started with the ContractStarter service (see #27).

Bonus:

A contract can be renewed by tacit agreement.
In this case, when the contracts ends, the contract is automatically renewed.
This requires a new checkbox when creating a contract.

As technical,
I want to reopen a ticket marked as resolved (because it wasn't a solution after all),
so I have it again in my list of "in progress" tickets and treat it again.

Requirements / comments:

• it is important to distinguish the "resolved" and "closed" status (closed tickets cannot be reopen)
• if the ticket has a solution, it should be possible to refuse it (
• if the ticket has no solutions, we should still be able to reopen the ticket via the "actions" button
• reopening a resolved ticket should not always be possible (e.g. after a certain time) → it should probably be an option set by admin
• users should also be able to mark a ticket as not resolved if the answer doesn't match their expectations

As assigned,
I want to see my assigned tickets,
so I know what I have to do and to be sure to answer all the problem I have the responsibility of.

Requirements / comments:

• the most important are the tickets "in progress"
• the best is when the list is empty
• the list can be very long and dynamic
• it must be possible to filter et sort the list by any of the ticket element, for instance:
  • creation date
  • requester
  • organization of the requester (i.e. customer)
  • state (e.g. "in progress", "resolved")
  • category
  • emergency

Depends on #43

Estimated time: 2 days

User story

As a requester or observer,
I want to answer to a ticket by email,
so I can give more information about my problem and answer to the questions of the support / assigned user.

Overview

Starting from now, users will be able to add answers to existing tickets.

At point 3 of #43:

1. extract an ID from the email
2. check the ID corresponds to an existing ticket in DB, that the ticket is not "closed" and that the user has permission to answer (and mark the MailboxEmail as failing if he can't)
3. extract the content from the email, and create a message in the ticket
4. mark the MailboxEmail as processed

Technical aspects

Tracking the ticket ID

To improve the chance to find the ID, we'll insert it in three places:

• in the Message-ID
• the title of the email (e.g. Re: [#42] It doesn't work)
• the content of the email (e.g. =-=-=-= Ticket #42 =-=-=-= , or in a <div id="ticket-number"> element)

As assigned,
I want to receive a notification when one of my tickets is updated
So I'm informed about the tickets which need my attention.

Requirements / comments:

• notifications can be: in the application, by email, phone, SMS, mattermost, etc.

Estimated time: 1 day

User story

As technical,
I want to assign a user to a default organization,
so I can assign automatically its ticket to the correct organization.

Technical aspects

The organization should be selectable when creating a user via a simple select box and can be set to empty value.

Specifying an "assignment organization" will not associate an authorization to this organization yet.
Otherwise, it would require a "default role" or to select a role, but we want to stick to the simplest approach at the moment.
See the related ticket #271

Also, it would be nice to be able to edit a user in order to assign them after creation.
I'll consider to include that in the 0.4-dev roadmap after having specifying all the rest.

As technical,
I want to change the history order of a ticket,
so I can adapt the timeline to my own needs.

As technical,
I want to hide events in the history of a ticket,
so I can see more clearly the answers.

As a commercial,
I want to see all the contracts
So I can easily find a contract without having to know its specific organization.

Comments / requirements:

• the list of contracts should be accessible from the head menu
• the list can be filtered

Depends on #17 and #331

Estimated time: 2 days

User story

As a requester,
I want to open a ticket by email,
so I can explain and be helped with a problem that I encounter directly from my email client.

Overview

We’ll only consider the creation of tickets for now.
It means that all emails collected by the Collector will create a new ticket.
This is obviously temporary, before #36 is implemented.

Once the MailboxEmail is saved (see #331):

1. get the sender email (From header, or Reply-To if it exists)
2. check that the address corresponds to a User (and mark the MailboxEmail as failing if it doesn't exist)
3. check the user is assigned to a default organization and that he has the permission to create tickets in it (and mark the MailboxEmail as failing if he can't)
4. extract the title and the content from the email, and create a ticket
5. mark the MailboxEmail as processed

Technical aspects

Extract the content

As a first approach, the content of the email will be done as following:

1. get the HTML body and sanitize it with the app HtmlSanitizer
2. if it doesn't exist, get the text body, escape the potential HTML tags and transform new lines in <br>

We we’ll not clean the content to remove eventual answers in the content yet.

Handle errors

We’ll need the new last_error and last_error_at fields in MailboxEmail in order to save the potential error and display them in the administration.

Later, the admins could be notified about these errors.

Process a MailboxEmail

Once finished, the MailboxEmail can be linked to the created ticket.
This will allow a better tracking of the tickets.
Later, the processed MailboxEmails (i.e. the ones with a related ticket_id) will be cleaned by a scheduled task after a certain time to be determined (related to the last paragraph of #331).

I’ve decided to simply delete the MailboxEmail for now.

Anonymous creation

We’ll consider allowing any email address to open tickets later.
This is out of scope of the current specification.
See #374
Related to #294

As technical,
I want to to be reminded to assign an unassigned ticket,
so the ticket is assigned to the correct person.

Requirements / comments :

• the reminder could be displayed at the top of the ticket page, with a button to assign the ticket to myself, and another to edit actors
• another solution would be to automatically assign the ticket if a user intervenes in a ticket, but I think it's too unexpected
• yet another idea would be to suggest to assign the ticket when answering (either at the top of the form, or by hidding it by default)

As technical,
I want to list all the tickets (except the closed ones),
so I have a global view of the work in progress.

As technical,
I want to add observers to a ticket,
so the problem can be followed by other people (e.g. the requester's hierarchy).

As technical, requester or observer,
I want to see the history of a ticket,
so I know who did what and when.

Requirements / comments:

• it is not an important need for us at Probesys, but it could be pretty complicated to add this feature in the future, so we need to think about it from the beginning
• some users may want to hide some items like automated actions

User story

As a commercial,
I want to receive a notification when a contract is about to end
So I can manage the business relationship with my customer peacefully and alert the techs

Overview

The alerts of a ticket (see #442) must be sent in two ways:

• a email for each individual alert when they start
• a single email to summarize the ongoing alerts

A user should opt-in for these notifications.

See: https://github.com/postcss/autoprefixer

This should allow to remove the at-rule-no-vendor-prefix and property-no-vendor-prefix config from the .stylelintrc.json file.

As technical,
I want to see the unassigned tickets
So I can make sure all the tickets are handled by someone.

Requirements / comments:

• the best is when the list is empty
• the list can be very long and dynamic
• it must be possible to filter et sort the list by any of the ticket element

As a commercial,
I want to end a contract
So the tech know they should no longer work for a customer.

Estimation: 3d

User story

As technical,
I want to indicate how much time I spent on an answer,
so it allows an appropriate billing and/or to provide an analysis of the support activity (e.g. the most time-consuming types of requests)

Overview

An new button is added to the answer form in order to enter spent time.
When clicking on the button, it's replaced by an input (number type).
This number is sent with the rest of the form and create a TimeSpent.

The TimeSpent is associated to the current contract if it's ongoing.

The individual spent time appears in the ticket timeline.

The total charged time must appear in the contracts list and in the contract block of the ticket.
When the charged time is above the contract max hours, the contract is considered as finished.

Rule idea

Configure the contract to charge by step (e.g. 30 minutes) to allow the tech to indicate the real spent time and let the app to calculate the charged time e.g. 12 minutes must be charged 30 minutes.

Technical

Organization of the answer form

The form to answer must be reorganized so it doesn't look cluttered.
The work has already begun (see #437), but there are still things to do:

• remove the "solution" checkbox (passing the status to "resolved" marks the answer as the solution)
• change the status select box by a menu on the right of the "Answer" button (to answer and change the status)

Entity

A new entity TimeSpent must be created:

• ticket (Ticket)
• time (int)
• real_time (int)
• contract (?Contract)

Permissions

Two new permissions must be added

• orga:create:tickets:time_spent
• orga:see:tickets:time_spent

Changing the ticket contract

When the contract of the ticket is changed, a checkbox must be added to ask the user if the time already spent must be reassigned to this contract.

As technical,
I want to plan a ticket intervention,
so I can detail what I will do, plan the spent time and have an event in my calendar.

Requirements / comments:

• the planned hours must not be deducted from the contract while they are not spent

As an admin,
I want to manage the organizations,
so organize the tickets in different structures.

As technical,
I want to save my current search and filters,
so I can reapply them quickly and save time when I need to use them often.

As a technical,
I want to open a ticket through the interface,
so I can record the users requests and ensure they are followed up.

As a requester,
I want to open a ticket through the interface,
so I can record a problem that I encounter and give more details than by email (e.g. by filling the emergency).

As technical,
I want to change the priority of a ticket,
so it gains importance in the things I have to do.

Requirements / comments:

• changing priority should be discouraged (priority = impact x urgency)
• but users think with priority in mind

As technical,
I want to access the previous or next ticket,
so I can navigate quickly between tickets.

As technical,
I want to be warned if I assign a ticket to myself while another user does the same,
so we are sure to not work at the same time on the same ticket.

• add login form + tests (https://symfony.com/doc/current/security.html#form-login)
• allow to logout (+ csrf ?)
• require authentication for all routes (except /login)