XML documentation error

Brian Gray · February 2020

The School API documentation for School.Model.RelationshipRead.Contact describes the returned value incorrectly. See attached image 001. The tooltip is shown by SKYLib. They said that the tool-tip comes directly from a Blackbaud file.

The documentation says that Contact "Returns True if No Contact is enabled in the UI." My testing shows that it returns FALSE if "No Contact" is enabled. Given the name of the field in the UI and the name of the field in the API, I believe that the return value is correct and the description in the XML file is incorrect.

These screenshots come from a test program that uses SKYLib. Protégé says that the tool-tip text is coming from a XML file produced by Blackbaud.

54f8d45d3e740934bb1842bd1272e6ec-huge-00

5c8fc59b38ab51ed3a346fec6871b8d6-huge-00

5360fd9f3b6b8e967a5e79fef9b33472-huge-00

Bryna Gleich · February 2020

Hi Brian,

Our product manager and developers are taking at closer look at this. We'll reply back to this thread when we have more info.

Thanks,

Bryna Gleich

Janet Wittenberg · March 2020

Hi all,

Can anyone post here who would find it a problem to flip this TRUE/FALSE flag on or soon after 3/31? We are researching the usage and impact of this endpoint.

Thanks for weighing in,

Janet Wittenberg

Senior Product Manager, K12

Brian Gray · March 2020

Please clarify - are you proposing to change the value that is returned or to change the wording of the documentation?

If you are proposing to change the documentation to correctly reflect what is returned, there should be no breaking change.

If you are proposing to change the value returned, then the result would be that a field named "Contact" would be true when the relationship is marked as "No contact". This would make no sense at all.

Steven Cinquegrana · March 2020

Hi Janet‍.

Further to Brian‍´s comments, he's right; changing the documentation only doesn't break any API functionality.

However, I question the fact that the UI and the API have opposite "polarity" for this flag. The API really should be a no_contact flag rather than a contact flag for consistency with the UI.

If you went down this track - and you could because the School API is still in beta - you would obviously create a breaking change. Another option is to add a no_contact property and retain contact as a deprecated property for a while before removing it.

Cheers,

Steve Cinquegrana | CEO and Principal Developer | Protégé Solutions

Janet Wittenberg · March 2020

Thank you both for clarifying. So even though it is awkward that the API doesn't match the UI, the API is much clearer, and the UI, well, won't be changed at this time.

So do we all agree that the best thing to do is

-Keep the API column as 'Contact'

-keep True and False values as they are returned today

-Fix the documentation


     "contact": {
            "description": "Returns True if No Contact is enabled in the UI. the user can be contacted.  Returns False if the user is marked as 'No Contact' in the UI. If enabled, the user cannot be contacted by the queried user",
            "type": "boolean"

Brian Gray · March 2020

I thank your revised language in the documentation has i right. Releasing that change should not cause any problem.

Thanks.

Steven Cinquegrana · March 2020

Yep, just fixing the doco is easiest/simplest.

XML documentation error

Comments

Categories