[ERM-391] Manage License term configuration Created: 11/Aug/19  Updated: 29/Oct/19  Resolved: 09/Sep/19

Status: Closed
Project: ERM Platform
Components: ui-licenses
Affects versions: None
Fix versions: None

Type: Story Priority: TBD
Reporter: Owen Stephens Assignee: steve.osguthorpe
Resolution: Done Votes: 0
Labels: erm
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original estimate: Not Specified

Attachments: PNG File License settings - terms.png     PNG File screenshot-1.png     PNG File separate-states.png    
Issue links:
Blocks
is blocked by ERM-417 /licenses/custprops cannot be sorted ... Closed
Cloners
is cloned by ERM-389 Manage License term value pick lists ... Closed
Defines
defines UXPROD-1521 UI for License term configuration Closed
Relates
relates to ERM-436 Licenses | Provide user friendly erro... Closed
relates to ERM-437 Local KB admin | External data source... Closed
relates to ERM-539 Licenses | Provide user friendly erro... Closed
Sprint: ERM Sprint 70, ERM Sprint 71
Development Team: Bienenvolk

 Description   

Administrators can add license terms for use in the tenant, as well as edit their details and remove them (as long as they are not in use).
Only users with access to License settings can view, edit or delete the list of available license terms in the tenant

Permission to edit these details are separate to those of other ERM permission sets

Workflow / UI Notes

  • Set from within Settings -> Licenses -> License terms
  • Display within Settings -> Licenses -> License terms
  • Sort by Weight (if sort available, sort not essential)

As per discussion in UXPROD-1960 Closed UI should use a card-based, three-pane UI

  • A card per term instead
  • The card would be styled like the editable cards we use when editing the documents or terms of a license.
  • Save/Delete buttons could be on the right side of each card's header.

Data stored for License terms:

  • Name (short test string <50 chars) (required)
    • Help/info text for 'name' (information in bold is the key information) : A license term 'name' is used when outputting the term data in a machine readable format. It is not intended to be displayed to users (staff or patrons). It should be a short text string that can be used by any external systems or programs that access the license term data. Use of camelCase is suggested but not required. Changes to the license term name would affect any external systems using license term data and changes should not be made without consulting those responsible for relevant external systems and software.
  • Label (short text string <255 chars) (required)
    • Help/info text for 'label' (information in bold is the key information): A license term 'label' is used when displaying the term to users within Folio and in any other systems that display license terms to users. It should be a short text string that clearly communicates what information is recorded in the term. The Description should be used where further explanation of the term is required for display to users.
  • Description (paragraph)
  • Order weight (positive or negative or zero integer) default to zero (required)
  • Primary term? (boolean) default to 'false' (required)
  • Default visibility (pick from "Internal" (default value) or "Public" - maps to defaultInternal boolean with Internal = true and Public = false) (required)
  • Type (choice of "Decimal", "Integer", "Pick List", "Text". NB "Pick List" is actually "Refdata" type, but should be labelled as "Pick List" in UI) (required)
  • Pick List to use (only active if "Pick List" is chosen as Type. If "Pick List" chosen as Type this field is required)

Business rules

  • A license term with "Primary" set to "true" cannot be deleted
  • A license term that has been used in the context of a license (i.e. there is a license with a value assigned to the term)
    • Cannot be deleted
    • Cannot have it's type edited
    • Cannot have it's Pick List to use edited


 Comments   
Comment by steve.osguthorpe [ 12/Aug/19 ]

https://github.com/folio-org/mod-licenses/blob/master/scripts/license_properties.jq#L25-L29 - Shows the shape of the terms expected by the controller.

https://github.com/folio-org/mod-licenses/blob/master/scripts/create_test_data.sh#L60-L66 - Does the actual post in bash.

Comment by Gill Osguthorpe [ 13/Aug/19 ]

I've added a mockup, after discussion with md331 about how this should work. The page is effectively an Edit pane with a single Save button (note the new position of the Save option in a fixed panel at the bottom of the screen). There is no Preview pane for terms. steve.osguthorpe can you confirm what is possible for "Last updated" please.

Owen Stephens are you ok with this?

Comment by Owen Stephens [ 13/Aug/19 ]

Gill Osguthorpe I'm OK with this

Comment by Gill Osguthorpe [ 14/Aug/19 ]

md331, Steve has confirmed that metadata for "Last updated" does not exist for license terms - neither the date nor "who". Owen Stephens, copying you in in case you think the additional work on the back end is worth following up separately.

Comment by Owen Stephens [ 14/Aug/19 ]

"Last updated" not required

Comment by Owen Stephens [ 15/Aug/19 ]

Question from md331 in Slack: "we’re not setting the `name` property on the terms we’re creating/editing. are we assuming that the backend will autogenerate one?"

My response: The reason I didn’t include in the `name` was I’m wasn't sure what the use of the ‘name’ is from the users perspective - I think they are only interested in the `label` (what displays in the UI). I’m happy for the user to set the `name` if that’s required

Comment by Owen Stephens [ 15/Aug/19 ]

From Steve on Slack:
>Custom property `name` is the name of the property itself. It's what appears as the property in the JSON and what is set aganst the object.

Based on this, I'm updating the story to include the `name` as an editable field, and also adding information how `name` and `label` should be used

Comment by md331 (Inactive) [ 15/Aug/19 ]

Owen Stephens, there's no real issue with implementing it, but "A license term with "Primary" set to "true" cannot be deleted" seems a bit unnecessary. The user can edit Primary so they'd just change it to "false" and then delete it if they wanted to, but that process seems unnecessarily involved and could be confusing if the user isn't sure why they can't delete a given term.

Comment by Owen Stephens [ 15/Aug/19 ]

md331 the reason I thought we should prevent terms with Primary set to true from being deleted is that they display on all licenses even when the value hasn't been set - so it feels like removing these is (a bit) like removing a term with a value set - it will affect the terms that appear on existing licenses & agreements

Gill Osguthorpe what's your view? I'm happy to go the other way on this if you agree with Mark that it is just getting the user to jump through a hoop

Comment by md331 (Inactive) [ 16/Aug/19 ]

Gill Osguthorpe and Owen Stephens, I've been running into performance issues having the entire list of terms being editable. The form becomes much slower when inputting data, and I'd hate to see it on underpowered machines or with even more terms. Additionally, it's simply not proving feasible to correctly indicate which fields are dirty when a new term is prepended to the list. As a result, I've trialed an earlier mockup of Gill's with separate view and edit states. See below:

Also visible:

Comment by Owen Stephens [ 16/Aug/19 ]

I'm absolutely happy with this being done in the most practical and workable way (from the development and user perspective). In reality this is not a screen that will be used very often - but it clearly shouldn't be unusable - what you propose is fine by me.

Comment by Gill Osguthorpe [ 19/Aug/19 ]

Mark Deutsch the reason I thought we should prevent terms with Primary set to true from being deleted is that they display on all licenses even when the value hasn't been set - so it feels like removing these is (a bit) like removing a term with a value set - it will affect the terms that appear on existing licenses & agreements

Gill Osguthorpe what's your view? I'm happy to go the other way on this if you agree with Mark that it is just getting the user to jump through a hoop

In answer to Owen Stephens's question, my understanding was that the user needs to be able to delete terms from both the Primary and the Non-primary lists. What md331has implemented makes sense to me, as long as we're warning users of the implications when they do delete.

md331 some comments about the screenshot you shared. Is it possible to:

1. make the Save button bg blue and the Cancel button bg white when a term's data is dirtied?

2. keep the delete behaviour of each repeating group consistent with the usual - where the Delete option is available when in Preview mode rather than in Edit mode (i.e. display the Trash Can icon in preview)?

3. switch around the Name and Label fields so that the Label and Description fields are above one another (and hence make the form easier to scan)?

Comment by Gill Osguthorpe [ 19/Aug/19 ]

md331 A suggestion for how help should be presented. I've added a draft License Terms help page to the Wiki: https://folio-org.atlassian.net/wiki/display/FOLIOtips/License+terms. We could link to this in as per the data import app, so instead of "Profiles " we'd have "Terms " and the Learn more button would link to the wiki.

We'll need text for the pop-over too. A suggestion: "You can manage the terms which are available for licenses. When you update a term, all the licenses that use it are automatically updated."

We shouldn't need to worry about keeping the pop-over text and the wiki inline with one another as the detail will just be contained within the wiki and the pop-over text will be very general and unlikely to change. Does this sound ok?

Comment by Peter Murray [ 23/Aug/19 ]

md331: Could you encode the plural handling in the `settings.terms.termCount` please?

settings.terms.termCount: "{count, number} saved {count, plural, one {term} other {terms}}"

Thanks!

Comment by md331 (Inactive) [ 23/Aug/19 ]

Gotcha Peter Murray. Didn't bother to start since a single-term system didn't even come into my thought process, but I added it here.

Comment by Peter Murray [ 23/Aug/19 ]

Thanks!

Comment by Gill Osguthorpe [ 27/Aug/19 ]

QA:

Non-critical UX (will raise separate tickets)

1. "New" button should be filled blue, with white text.
2. "Edit" button should be filled white, with blue text.
3. An active "Cancel" button should be filled white.

Not possible to implement

Sort by Weight (if sort available, sort not essential)

There's a lot of help text displayed in the pop-overs for the Label and Name fields. This has been left in the system rather than in the help Wiki to be sure that the text can be translated.

Unable to test

Only users with access to License settings can view, edit or delete the list of available license terms in the tenant

Permission to edit these details are separate to those of other ERM permission sets

Generated at Fri Feb 09 00:20:02 UTC 2024 using Jira 1001.0.0-SNAPSHOT#100246-sha1:7a5c50119eb0633d306e14180817ddef5e80c75d.