<!-- 
RSS generated by JIRA (1001.0.0-SNAPSHOT#100246-sha1:7a5c50119eb0633d306e14180817ddef5e80c75d) at Thu Feb 08 23:14:18 UTC 2024

It is possible to restrict the fields that are returned in this document by specifying the 'field' parameter in your request.
For example, to request only the issue key and summary add field=key&field=summary to the URL of your request.
-->
<rss version="0.92" >
<channel>
    <title>FOLIO Jira</title>
    <link>https://folio-org.atlassian.net</link>
    <description>This file is an XML representation of an issue</description>
    <language>en-us</language>    <build-info>
        <version>1001.0.0-SNAPSHOT</version>
        <build-number>100246</build-number>
        <build-date>07-02-2024</build-date>
    </build-info>

<item>
            <title>[MODUSERS-119] Missing or incomplete documentation of data attributes in mod-users</title>
                <link>https://folio-org.atlassian.net/browse/MODUSERS-119</link>
                <project id="10158" key="MODUSERS">mod-users</project>
                    <description>&lt;p&gt;&lt;b&gt;High priority APIs:&lt;/b&gt;&lt;/p&gt;

&lt;ul&gt;
	&lt;li&gt;mod-users: /groups&lt;/li&gt;
	&lt;li&gt;mod-users: /users&lt;/li&gt;
&lt;/ul&gt;


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


&lt;p&gt;Two examples of attribute documentation:&lt;/p&gt;

&lt;div class=&quot;preformatted panel&quot; style=&quot;border-width: 1px;&quot;&gt;&lt;div class=&quot;preformattedContent panelContent&quot;&gt;
&lt;pre&gt;I.

Attribute name:     username
Description:        The user&apos;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:         &quot;User Groups&quot; /groups/{groupId} (e.g. mod-users)
Other constraints:  None
&lt;/pre&gt;
&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;These examples are intended not to prescribe a documentation format or style but to illustrate further the basic documentation content being requested.&lt;/p&gt;</description>
                <environment></environment>
        <key id="67633">MODUSERS-119</key>
            <summary>Missing or incomplete documentation of data attributes in mod-users</summary>
                <type id="10003" iconUrl="https://folio-org.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10318?size=medium">Task</type>
                                            <priority id="10002" iconUrl="https://dev.folio.org/assets/jira-priority/jira-p3.svg">P3</priority>
                        <status id="6" iconUrl="https://folio-org.atlassian.net/images/icons/statuses/closed.png" description="The issue is considered finished, the resolution is correct. Issues which are closed can be reopened.">Closed</status>
                    <statusCategory id="3" key="done" colorName="green"/>
                                    <resolution id="10003">Done</resolution>
                                                        <assignee accountid="5ee89462f7aa140abd82d11d">Julian Ladisch</assignee>
                                                                <reporter accountid="70121:8d96963c-ce4c-478d-9023-2de35bc14b67">Nassib Nassar</reporter>
                                    <labels>
                            <label>back-end</label>
                            <label>documentation</label>
                    </labels>
                <created>Wed, 10 Oct 2018 01:58:37 +0000</created>
                <updated>Mon, 14 Mar 2022 16:03:23 +0000</updated>
                            <resolved>Mon, 14 Mar 2022 16:03:23 +0000</resolved>
                                                    <fixVersion>18.3.0</fixVersion>
                                        <due></due>
                            <votes>1</votes>
                                    <watches>6</watches>
                                                                <comments>
                                                            <comment id="165305" author="70121:8d96963c-ce4c-478d-9023-2de35bc14b67" created="Tue, 6 Nov 2018 05:26:02 +0000"  >&lt;p&gt;For an initial round, the following interfaces would be most useful:&lt;/p&gt;

&lt;p&gt;mod-users: /groups&lt;br/&gt;
mod-users: /users&lt;/p&gt;</comment>
                                                            <comment id="165306" author="5ee89462f7aa140abd82d11d" created="Thu, 27 May 2021 06:26:38 +0000"  >&lt;p&gt;&lt;a href=&quot;https://folio-org.atlassian.net/secure/ViewProfile.jspa?accountId=70121%3A8d96963c-ce4c-478d-9023-2de35bc14b67&quot; class=&quot;user-hover&quot; rel=&quot;70121:8d96963c-ce4c-478d-9023-2de35bc14b67&quot; data-account-id=&quot;70121:8d96963c-ce4c-478d-9023-2de35bc14b67&quot; accountid=&quot;70121:8d96963c-ce4c-478d-9023-2de35bc14b67&quot; rel=&quot;noreferrer&quot;&gt;Nassib Nassar&lt;/a&gt;: Please review.&lt;/p&gt;

&lt;p&gt;Detailed documentation has been published on &lt;a href=&quot;https://dev.folio.org/reference/api/#mod-users&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;https://dev.folio.org/reference/api/#mod-users&lt;/a&gt; . This includes&lt;br/&gt;
&lt;a href=&quot;https://s3.amazonaws.com/foliodocs/api/mod-users/users.html#users_post&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;https://s3.amazonaws.com/foliodocs/api/mod-users/users.html#users_post&lt;/a&gt; &lt;br/&gt;
&lt;a href=&quot;https://s3.amazonaws.com/foliodocs/api/mod-users/groups.html#groups_post&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;https://s3.amazonaws.com/foliodocs/api/mod-users/groups.html#groups_post&lt;/a&gt; &lt;/p&gt;

&lt;p&gt;Please review and give feedback whether this is sufficient and this issue can be closed, or list the information that is still missing.&lt;/p&gt;</comment>
                                                            <comment id="165307" author="70121:8d96963c-ce4c-478d-9023-2de35bc14b67" created="Sat, 29 May 2021 01:22:45 +0000"  >&lt;p&gt;Thank you. &#160;We will ask the Reporting SIG (via &lt;a href=&quot;https://folio-org.atlassian.net/secure/ViewProfile.jspa?accountId=5d24ec917d35310c14407dda&quot; class=&quot;user-hover&quot; rel=&quot;5d24ec917d35310c14407dda&quot; data-account-id=&quot;5d24ec917d35310c14407dda&quot; accountid=&quot;5d24ec917d35310c14407dda&quot; rel=&quot;noreferrer&quot;&gt;Angela Zoss&lt;/a&gt;) if they would review this, as they are the consumers of the documentation.&lt;/p&gt;</comment>
                                                            <comment id="165308" author="5d24ec917d35310c14407dda" created="Tue, 13 Jul 2021 16:34:04 +0000"  >&lt;p&gt;Thank you! We have reviewed and have a few suggestions, all for the mod-users/users interface:&lt;/p&gt;
&lt;ul&gt;
	&lt;li&gt;&lt;b&gt;active&lt;/b&gt;: 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.&lt;/li&gt;
	&lt;li&gt;&lt;b&gt;type&lt;/b&gt;: The description clarifies type as &#8220;class,&#8221; and both words are sort of equally vague, so that&apos;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.&#160;&#160;&lt;/li&gt;
	&lt;li&gt;&lt;b&gt;departments&lt;/b&gt;: Typo at the beginning (says &#8220;A UUIDs&#8221;, instead of just &quot;UUIDs&quot; or &quot;A list of UUIDs&quot;). Maybe worth including the word list in the description to highlight that it is an array field.&lt;/li&gt;
	&lt;li&gt;&lt;b&gt;preferredContactTypeId&lt;/b&gt;: More information would be helpful here. We&apos;re not clear what this field connects to, and the use of &quot;Id&quot; in the field title can be confusing when this doesn&apos;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.&lt;/li&gt;
&lt;/ul&gt;
</comment>
                                                            <comment id="165309" author="557058:f80403de-e149-421e-8750-af45c853402f" created="Tue, 8 Mar 2022 14:07:42 +0000"  >&lt;p&gt;&lt;a href=&quot;https://folio-org.atlassian.net/secure/ViewProfile.jspa?accountId=63e2a2771b13d42998e4e706&quot; class=&quot;user-hover&quot; rel=&quot;63e2a2771b13d42998e4e706&quot; data-account-id=&quot;63e2a2771b13d42998e4e706&quot; accountid=&quot;63e2a2771b13d42998e4e706&quot; rel=&quot;noreferrer&quot;&gt;Marc Johnson&lt;/a&gt; - 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?&lt;/p&gt;</comment>
                                                            <comment id="165310" author="63e2a2771b13d42998e4e706" created="Tue, 8 Mar 2022 14:30:14 +0000"  >&lt;p&gt;&lt;a href=&quot;https://folio-org.atlassian.net/secure/ViewProfile.jspa?accountId=557058%3Af80403de-e149-421e-8750-af45c853402f&quot; class=&quot;user-hover&quot; rel=&quot;557058:f80403de-e149-421e-8750-af45c853402f&quot; data-account-id=&quot;557058:f80403de-e149-421e-8750-af45c853402f&quot; accountid=&quot;557058:f80403de-e149-421e-8750-af45c853402f&quot; rel=&quot;noreferrer&quot;&gt;Charlotte Whitt&lt;/a&gt;&lt;/p&gt;

&lt;blockquote&gt;&lt;p&gt;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?&lt;/p&gt;&lt;/blockquote&gt;

&lt;p&gt;Sure.&lt;/p&gt;

&lt;p&gt;Given that &lt;a href=&quot;https://folio-org.atlassian.net/secure/ViewProfile.jspa?accountId=5ee89462f7aa140abd82d11d&quot; class=&quot;user-hover&quot; rel=&quot;5ee89462f7aa140abd82d11d&quot; data-account-id=&quot;5ee89462f7aa140abd82d11d&quot; accountid=&quot;5ee89462f7aa140abd82d11d&quot; rel=&quot;noreferrer&quot;&gt;Julian Ladisch&lt;/a&gt; did the original work that the review was requested of, I don&apos;t think I (or the Prokopovych team) are the right audience to receive the feedback.&lt;/p&gt;

&lt;p&gt;I suggest assigning this work to &lt;a href=&quot;https://folio-org.atlassian.net/secure/ViewProfile.jspa?accountId=5ee89462f7aa140abd82d11d&quot; class=&quot;user-hover&quot; rel=&quot;5ee89462f7aa140abd82d11d&quot; data-account-id=&quot;5ee89462f7aa140abd82d11d&quot; accountid=&quot;5ee89462f7aa140abd82d11d&quot; rel=&quot;noreferrer&quot;&gt;Julian Ladisch&lt;/a&gt; and the Core Platform team given they have taken an active interest in it.&lt;/p&gt;

&lt;p&gt;&lt;b&gt;Type of Documentation Requested&lt;/b&gt;&lt;/p&gt;

&lt;p&gt;I will say that the API documentation format that the module users is not well suited to full documentation of the sort that &lt;a href=&quot;https://folio-org.atlassian.net/secure/ViewProfile.jspa?accountId=70121%3A8d96963c-ce4c-478d-9023-2de35bc14b67&quot; class=&quot;user-hover&quot; rel=&quot;70121:8d96963c-ce4c-478d-9023-2de35bc14b67&quot; data-account-id=&quot;70121:8d96963c-ce4c-478d-9023-2de35bc14b67&quot; accountid=&quot;70121:8d96963c-ce4c-478d-9023-2de35bc14b67&quot; rel=&quot;noreferrer&quot;&gt;Nassib Nassar&lt;/a&gt; and &lt;a href=&quot;https://folio-org.atlassian.net/secure/ViewProfile.jspa?accountId=5d24ec917d35310c14407dda&quot; class=&quot;user-hover&quot; rel=&quot;5d24ec917d35310c14407dda&quot; data-account-id=&quot;5d24ec917d35310c14407dda&quot; accountid=&quot;5d24ec917d35310c14407dda&quot; rel=&quot;noreferrer&quot;&gt;Angela Zoss&lt;/a&gt; are asking for.&lt;/p&gt;

&lt;p&gt;The space available to use is a single piece of text that could get unwieldy if it is long.&lt;/p&gt;

&lt;p&gt;It cannot provide the kind of structured documentation that &lt;a href=&quot;https://folio-org.atlassian.net/secure/ViewProfile.jspa?accountId=70121%3A8d96963c-ce4c-478d-9023-2de35bc14b67&quot; class=&quot;user-hover&quot; rel=&quot;70121:8d96963c-ce4c-478d-9023-2de35bc14b67&quot; data-account-id=&quot;70121:8d96963c-ce4c-478d-9023-2de35bc14b67&quot; accountid=&quot;70121:8d96963c-ce4c-478d-9023-2de35bc14b67&quot; rel=&quot;noreferrer&quot;&gt;Nassib Nassar&lt;/a&gt; uses in the issue description.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;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.&lt;/p&gt;&lt;/blockquote&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;Similarly, for the &lt;tt&gt;type&lt;/tt&gt; field, I don&apos;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&apos;s users especially given this field is free entry text.&lt;/p&gt;</comment>
                                                            <comment id="165311" author="5ee89462f7aa140abd82d11d" created="Thu, 10 Mar 2022 08:54:24 +0000"  >&lt;p&gt;&lt;a href=&quot;https://folio-org.atlassian.net/secure/ViewProfile.jspa?accountId=5d24ec917d35310c14407dda&quot; class=&quot;user-hover&quot; rel=&quot;5d24ec917d35310c14407dda&quot; data-account-id=&quot;5d24ec917d35310c14407dda&quot; accountid=&quot;5d24ec917d35310c14407dda&quot; rel=&quot;noreferrer&quot;&gt;Angela Zoss&lt;/a&gt; Please review the pull request: &lt;a href=&quot;https://github.com/folio-org/mod-users/pull/238/files&quot; class=&quot;external-link&quot; rel=&quot;nofollow noreferrer&quot;&gt;https://github.com/folio-org/mod-users/pull/238/files&lt;/a&gt;&lt;/p&gt;</comment>
                    </comments>
                <issuelinks>
                            <issuelinktype id="10008">
                    <name>Defines</name>
                                            <outwardlinks description="defines">
                                        <issuelink>
            <issuekey id="10921">UXPROD-1414</issuekey>
        </issuelink>
                            </outwardlinks>
                                                        </issuelinktype>
                            <issuelinktype id="10003">
                    <name>Relates</name>
                                                                <inwardlinks description="relates to">
                                        <issuelink>
            <issuekey id="80888">FOLIO-1551</issuekey>
        </issuelink>
                            </inwardlinks>
                                    </issuelinktype>
                    </issuelinks>
                <attachments>
                    </attachments>
                <subtasks>
                    </subtasks>
                <customfields>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                <customfield id="customfield_10000" key="com.atlassian.jira.plugins.jira-development-integration-plugin:devsummarycf">
                        <customfieldname>Development</customfieldname>
                        <customfieldvalues>
                            
                        </customfieldvalues>
                    </customfield>
                                                                <customfield id="customfield_10057" key="com.atlassian.jira.plugin.system.customfieldtypes:select">
                        <customfieldname>Development Team</customfieldname>
                        <customfieldvalues>
                                <customfieldvalue key="10144"><![CDATA[Core: Platform]]></customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        <customfield id="customfield_10019" key="com.pyxis.greenhopper.jira:gh-lexo-rank">
                        <customfieldname>Rank</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>0|hzxafz:</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    <customfield id="customfield_10020" key="com.pyxis.greenhopper.jira:gh-sprint">
                        <customfieldname>Sprint</customfieldname>
                        <customfieldvalues>
                                <customfieldvalue id="469">CP: sprint 135</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                                            <customfield id="customfield_10044" key="com.atlassian.jira.plugin.system.customfieldtypes:float">
                        <customfieldname>Story Points</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>1.0</customfieldvalue>
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                <customfield id="customfield_10024" key="com.atlassian.jira.ext.charting:firstresponsedate">
                        <customfieldname>[CHART] Date of First Response</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>Thu, 27 May 2021 06:26:38 +0000</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                <customfield id="customfield_10025" key="com.atlassian.jira.ext.charting:timeinstatus">
                        <customfieldname>[CHART] Time in Status</customfieldname>
                        <customfieldvalues>
                            
                        </customfieldvalues>
                    </customfield>
                                    </customfields>
    </item>
</channel>
</rss>