[MODUSERS-119] Missing or incomplete documentation of data attributes in mod-users Created: 10/Oct/18  Updated: 14/Mar/22  Resolved: 14/Mar/22

Status: Closed
Project: mod-users
Components: None
Affects versions: None
Fix versions: 18.3.0

Type: Task Priority: P3
Reporter: Nassib Nassar Assignee: Julian Ladisch
Resolution: Done Votes: 1
Labels: back-end, documentation
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original estimate: Not Specified

Issue links:
Defines
defines UXPROD-1414 Complete the documentation of data at... Closed
Relates
relates to FOLIO-1551 Missing or incomplete documentation o... Closed
Sprint: CP: sprint 135
Story Points: 1
Development Team: Core: Platform

 Description   

High priority APIs:

  • mod-users: /groups
  • mod-users: /users

Acceptance criteria:

  • Documentation for each attribute should include:
    • A description of what the attribute means
    • The precise domain of the attribute (range of values, controlled vocabulary, etc.)
    • Whether the attribute is required or optional
    • Where to find referenced data, if the attribute is a foreign key
    • Any other constraints on the data, e.g. whether an attribute allows only unique values

Two examples of attribute documentation:

I.

Attribute name:     username
Description:        The user's login name.  This also serves as an unique,
                    human-readable identifier for the user.
Domain:             String of alphanumeric Unicode characters, beginning with
                    an alphabetic character.  Maximum of 16 characters.
Required:           Yes
References:         N/A
Other constraints:  Unique, but may be reused after the user is deleted.

II.

Attribute name:     patronGroup
Description:        The patron group that the user belongs to.
Domain:             UUID
Required:           Yes
References:         "User Groups" /groups/{groupId} (e.g. mod-users)
Other constraints:  None

These examples are intended not to prescribe a documentation format or style but to illustrate further the basic documentation content being requested.



 Comments   
Comment by Nassib Nassar [ 06/Nov/18 ]

For an initial round, the following interfaces would be most useful:

mod-users: /groups
mod-users: /users

Comment by Julian Ladisch [ 27/May/21 ]

Nassib Nassar: Please review.

Detailed documentation has been published on https://dev.folio.org/reference/api/#mod-users . This includes
https://s3.amazonaws.com/foliodocs/api/mod-users/users.html#users_post
https://s3.amazonaws.com/foliodocs/api/mod-users/groups.html#groups_post

Please review and give feedback whether this is sufficient and this issue can be closed, or list the information that is still missing.

Comment by Nassib Nassar [ 29/May/21 ]

Thank you.  We will ask the Reporting SIG (via Angela Zoss) if they would review this, as they are the consumers of the documentation.

Comment by Angela Zoss [ 13/Jul/21 ]

Thank you! We have reviewed and have a few suggestions, all for the mod-users/users interface:

  • active: Maybe instead of just documenting the results of being active/inactive, include information about what causes a user to be inactive (for example, expiration date has passed, which is what is suggested by the description for the expirationDate field). Current documentation might lead someone to believe that user is inactive if they have a block, since a block can prevent user from borrowing.
  • type: The description clarifies type as “class,” and both words are sort of equally vague, so that's not a very helpful description. Examples of what type is used for would be more helpful, and it would be good to distinguish this from patron group, since patron type and patron group are both used interchangeably by many libraries.  
  • departments: Typo at the beginning (says “A UUIDs”, instead of just "UUIDs" or "A list of UUIDs"). Maybe worth including the word list in the description to highlight that it is an array field.
  • preferredContactTypeId: More information would be helpful here. We're not clear what this field connects to, and the use of "Id" in the field title can be confusing when this doesn't contain a UUID. For that reason, it would be very helpful if the description could clarify where the values in this field come from/how they are specified in the FOLIO apps.
Comment by Charlotte Whitt [ 08/Mar/22 ]

Marc Johnson - based on the feed back from Angela Zoss 7/13/2021 (see above) then this ticket looks like it should be moved back In progress. Do you agree?

Comment by Marc Johnson [ 08/Mar/22 ]

Charlotte Whitt

based on the feed back from Angela Zoss 7/13/2021 (see above) then this ticket looks like it should be moved back In progress. Do you agree?

Sure.

Given that Julian Ladisch did the original work that the review was requested of, I don't think I (or the Prokopovych team) are the right audience to receive the feedback.

I suggest assigning this work to Julian Ladisch and the Core Platform team given they have taken an active interest in it.

Type of Documentation Requested

I will say that the API documentation format that the module users is not well suited to full documentation of the sort that Nassib Nassar and Angela Zoss are asking for.

The space available to use is a single piece of text that could get unwieldy if it is long.

It cannot provide the kind of structured documentation that Nassib Nassar uses in the issue description.

Maybe instead of just documenting the results of being active/inactive, include information about what causes a user to be inactive (for example, expiration date has passed, which is what is suggested by the description for the expirationDate field). Current documentation might lead someone to believe that user is inactive if they have a block, since a block can prevent user from borrowing.

I think this level of documentation about the domain being modelled by FOLIO is better suited to the official FOLIO documentation, that is intended to be user facing, rather than the brief API documentation.

Similarly, for the type field, I don't think developers (who tend to be asked to add fields without being given the context of the domain) are the appropriate folks to describe what kinds of types an organisation my define for it's users especially given this field is free entry text.

Comment by Julian Ladisch [ 10/Mar/22 ]

Angela Zoss Please review the pull request: https://github.com/folio-org/mod-users/pull/238/files

Generated at Thu Feb 08 23:14:17 UTC 2024 using Jira 1001.0.0-SNAPSHOT#100246-sha1:7a5c50119eb0633d306e14180817ddef5e80c75d.