RFC: Change productive consumption user flow

[sloschert]

I propose to change our productive consumption user flow, please let me know what you think about this.

Current user flow

For registering of productive consumption we currently have one route, where companies are registering productive consumption: company/register_productive_consumption. This route accepts GET and POST requests. The POST request requires three inputs: plan_id, amount and type_of_consumption. Companies have to make sure to specify the correct plan_id, because at no point of this flow the plan name or the "price" of the product is shown, which is error prone.

Proposed user flow

I propose to split the process of registering productive consumption into two stages:

STAGE 1: Selection of plan

---

In this stage, the company specifies the plan_id of the product that it wants to consume.

We can have different implementations of this stage. For example, the selection of the plan_id might be carried out by scanning a plan-specific QR-Code, by clicking a link somewhere in our web app or by manually entering the plan_id in a form. For now, I propose to add a new route, that lets the company specify the plan_id (see below for details).

If the selected plan is eligible, the company gets directed to stage two.

STAGE 2: Selection of amount and type of consumption

The user gets provided with information on the previously selected plan/product. This information might be the "price" of the product, name and description, and potentially many more.

The company then specifies amount and type_of_consumption and actually registers the consumption.

Technical implementation:

STAGE 1

• New company route /company/select_plan_for_consumption [GET, POST]
• New view SelectPlanForConsumptionView
• New form SelectPlanForConsumptionForm

GET:

• New form is shown with one field ("plan_id")

POST:

• New controller SelectPlanForConsumptionController
• New SelectPlanForConsumptionUseCase
  • Check that plan exists, that it's active, that it's not public, that consumer is not planner, etc.
• New presenter SelectPlanForConsumptionPresenter
  • On success, redirect to route /company/register_productive_consumption (stage 2)
  • On failure, show error notification to user.

STAGE 2

• Change existing route /company/register_productive_consumption [GET, POST]
• Change existing view RegisterProductiveConsumptionView
• Change existing form RegisterProductiveConsumptionForm

GET:

• New ProductiveConsumptionDetailsController
  • Accept plan_id as argument
  • Handle form
• New ProductiveConsumptionDetailsUseCase
  • get information of selected plan from repositories
• New ProductiveConsumptionDetailsPresenter

POST:

• Change existing controller RegisterProductiveConsumptionController
• Change existing use case RegisterProductiveConsumption
  • Check sufficient account coverage etc.
• Change existing presenter RegisterProductiveConsumptionPresenter

[4lm]

Thank you for this detailed RFC issue. I appreciate the idea of improving the productive consumption user flow.

I believe Stage 1 should pivot a little bit and could introduce a plan filter list view that displays all available plans from various companies and allows users to filter (search) for the correct plan. This way, users wouldn’t need to know the plan id beforehand, which is currently a cumbersome part of the productive consumption user flow. Additionally, Stage 1 wouldn't require any redirect flow to /company/register_productive_consumption; using simple links is in my opinion more native to the web and, therefore, the better choice. Here’s a structured breakdown of my suggestion:

STAGE 1: Plan Filter List View

• New company route: /company/list-consumption-plans [GET]
• New view: ListConsumptionPlans
• New form: ListConsumptionPlansFilterForm

• Features:

  • The list view displays all consumable plans from all companies
  • The displayed plans are defined by the view's filter parameters.
  • The filter form could include the following filters: plan (UUID), planner (UUID), query (string).
  • The query filter parameter uses a string to search within the plan data gateway in the prd_name (title) and description fields. The initial data gateway implementation could use PostgreSQL's text search feature to implement a simple SELECT statement together with SQLAlchemy (simplified):

  from flask_sqlalchemy import SQLAlchemy
  from sqlalchemy import text
  
  # [...]
  
  db = SQLAlchemy(app)
  
  # [...]
  
  query = request.args.get('query')
  if query:
      search_query = text("""
          SELECT * FROM public.plan
          WHERE to_tsvector('german', prd_name || ' ' || description) @@ websearch_to_tsquery('german', :query)
              OR prd_name ILIKE '%' || :query || '%'
              OR description ILIKE '%' || :query || '%';
          """)
      results = db.engine.execute(search_query, query=query).fetchall()
  
  # [...]

  ('german' could be replaced with 'english' or 'simpel' if there is no dominant language used. A proper i18n is in my opinion needed in the future (different PR). In this future i18n PR, all entities, like plan with plan.description would need to be adjusted to host descriptions in multiple languages)

  • Without filter parameters, the list view shows all plans (paginated).
  • Pagination could be set to 25 entries per page, adjustable via an URL page=<1,2,3, ... n> parameter (if omitted, page == 1)
  • The ListConsumptionPlansFilterForm could include three inputs: plan (text, validates to UUID), planner (select-option), query (text, used in query params).
  • The URL /company/list-consumption-plans should always reflect the current, representational state of the application by using filter parameters, for example, /company/list-consumption-plans?planner=ff5e8644-6316-48a8-b9e3-449600809da4&query=Saatgut would display only "Saatgut" plans by a specific planner (company).
  • Each list entry should link to /company/register_productive_consumption with the specific plan ID.
  • Each entry could display details like the title, ID, and part of the description.
  • Each entry should have two links: "Go to plan details" (/company/plan_details/<plan_id>) and "Register plan for consumption" (/company/register_productive_consumption?id=<plan_id>).
  • I also would add a "Filter" button to the ListConsumptionPlansFilterForm in order to send GET requests to the very same view and by this create and construct a new representational application state. This can later (another PR) be enhanced by some JavaScript which allows to change the state without the need of hitting submit buttons as a user which gracefully degrades to a submit button interface if JavaScript is not be present; this concept is known as progressive enhancement (not to be confused with Progressive Web Application (PWA)).

STAGE 2

• I agree with the suggested changes in Stage 2 of this RFC. Additionally, I propose adjusting the view at /company/register_productive_consumption so that it can be linked from the Plan Filter List View using links of the form /company/register_productive_consumption?id=<plan_id> and therefore simple GET requests to populate the form of this view if a plan id is present in the plan id URL param . This ensures consistency with the architectural approach described in Stage 1.
• Following this approach, a plan would be pre-selected in the form. No need for a redirect.
• If a form is pre-selected a link to the detail view of this plan could be added also in this view (like for each entry in the Plan Filter List View), this would help a user to validate that they selected the correct plan
• A "Select" form button and a "Register" button would be needed. The "Select" button could be omitted via progressive enhancement techniques (as mentioned in the STAGE 1 section).

Implementing these suggestions would further improve the productive consumption user flow and help users make informed decisions when selecting plans for consumption. It would also instantly enable the creation of other methods of selection, mentioned in the RFC.), without changing a line of code in /company/register_productive_consumption.

What do you think?

If these concepts are too numerous or not clearly explained, I am available for assistance and would by happy to further discuss and help to implement these concepts during the development process of the concerning PR.

[seppeljordan]

I prefer @sloschert approach as it is much more focused on the problem that he outlined in the OP of this thread. I disagree though with the choice to have the amount selection and the kind of consumption selection in phase 2 and would prefer it if phase 2 was a simple confirmation step. Generating a pre-filled form (for example via a QR code) could "easily" be done via query parameters when rendering the form from phase 1.

[4lm]

I prefer @sloschert approach as it is much more focused on the problem that he outlined in the OP of this thread. [...] Generating a pre-filled form (for example via a QR code) could "easily" be done via query parameters when rendering the form from phase 1.

Maybe my suggestion tried to pack too much in there at once and therefore my actual point did not come across, sorry for that. Because what you propose essentially aligns with what I suggest we should do. Let me explain. QR codes can contain links as data that can be scanned and by this enable the user to browse to a page via a GET request, similar to how clicking a link on a page directs to another page (which is basically the same thing and just has a different user interface). @sloschert also discusses using links with various examples in the original post but then shifts in his implementation steps to a POST redirect workflow. This involves redirecting to another page to fill out another form, perform another POST, and then process and save data. This approach is unconventional. Normally, you wouldn’t use POST redirects just to fill out another form on a different page. Instead, you’d use links with parameters to autofill the form on the target page (in our case: /company/register_productive_consumption).

Therefore, my suggestion is to stick with the initial idea (of the given examples) in the original post and use links with parameters (stage 1) to fill a form on a POST page (stage 2). These links should at minimum carry the plan_id, and optionally amount (preferably) and type_of_consumption. This links are then used to pre-fill the form on the target page. My other suggestion was, to somehow improve the search- and select-ability of plans in stage 1. Which I think should be a filterable, paginated list of all available plans. But I'm OK with taking a more minimal approach implement the first iteration of such a (list, search and) select page.

[sloschert]

As discussed, we will keep it simple for now and implement the following steps:

• [x] /company/register_productive_consumption (GET): Accept query parameter "plan_id"

• [ ] Seperate RegisterProductiveConsumptionView into two different views/routes, one for GET and one for POST. The GET view should be called SelectProductiveConsumptionView, the POST view is still called RegisterProductiveConsumptionView.

• [ ] Do not send a POST request to RegisterProductiveConsumptionView, but a GET request with url query parameters. The GET route shows then a confirmation form with plan information. When the user confirms, a POST request gets send.

[Amittai-Aviram]

FWIW, I think both Sebas's OP and Alexis's suggestions have a lot of value. The user may already know the plan ID, but is likely not to know, at least on the first "order" (transfer), and I think the number of hours that the consumable product is worth is also likely to be unknown to the user — and may also change, right? So a UI that facilitates searching and browsing makes sense to me. But I am worried that a logic of presenting all plans and then offering the user filters is not very scalable. Surely, the initial results should be pre-filtered and only show active plans, for instance. Also, shouldn't the initial query, and therefore both the GET and the POST requests, specify the type of product the user (company) needs to consume? Are there other ways of pre-filtering to ensure that the initial view is scalable, both technically and from a UX perspective?

The proposal also raises further questions for me. Is a scenario possible in which the list of plans to produce a given commodity includes two different plans from different companies to produce the same (or roughly the same) commodity, but where hours worked per product (the "price") differs substantially? This puts the user in the position of "shopping for a bargain." Presumably, producers of the same or similar products would belong to the same cooperation, which would set a rational rate of hours per product (based on the average of actual experiences), but there is nothing to compel a company to join a cooperation. Or should the response page in Stage 1 actually be organized by cooperations that offer the desired commodity — a list of cooperations, with the plans under each cooperation?

In the real world, I would expect an employee of company A to need product X either as machinery or a raw material. So he/she goes online to look for a source of product X, both to look up how many hours would need to be transferred from company A to that producer (for internal planning) and to arrange to exchange the hours for the product. So I would expect the app's workflow to follow that logic. That's where Alexis's suggestions make sense to me. Am I missing something?

[sloschert]

Adding this flow chart by @4lm after talking about this issue on our last dev meeting.