This is a very important point. Those who use the API live and die by the documentation and by the API acting in a consistent manner. Most users of the API don't know Zabbix's inner workings.

To me it makes sense why adding a sort field would add one more data field to the output. After all for the sort to work inside Zabbix you have to add that field to the columns in the SQL call which is the basis for all API output. However I think Richlv is right, output should explicitly be controlled by the output parameter, not implicitly like it is now. I also think this should work across all API calls.

I think when you make a call and do not explicitly state what fields to output you should always get a set of default fields. This default list must be published in the documentation.

If it is decided not to go this route, then there needs to be a consistent way across all API calls to remove a field from output, and the documentation needs to be updated to denote parameters which can affect output. I think it would be a lot easier to make the output parameter explicit.

Fixed in development branch svn://svn.zabbix.com/branches/dev/ZBX-3366

trunk revision 23561

(4)
error:
Undefined variable: sortorder [api/classes/class.chistory.php:220]
on page:
Monitoring -> Screens

Broken rev 23561

<Eduard> RESOLVED

<zalex> It happened for "Plain text" screen elements. Dev branch tested. Problem is gone.
TESTED
<sasha> Please rewrite the code with usage of function zbx_db_sorting()
<Eduard> RESOLVED
<sasha> REOPENED
before ZBX-3366 implementation: "... ORDER BY h.itemid DESC,h.clock DESC ..."
after: "... ORDER BY h.clock DESC,h.itemid DESC ..."

<Eduard> RESOLVED
<sasha> REOPENED
now: "... ORDER BY h.clock DESC ..."
all calls of the method API::History()->get() with 'sortfield' => 'clock' should be replaced on 'sortfield' => array('itemid', 'clock');
<Eduard> RESOLVED
<Sasha> CLOSED

Fixed in development branch svn://svn.zabbix.com/branches/dev/ZBX-3366

(5) The table "profiles" in my trunk DB contains some previous values related to sorting settings for current user.
Starting from rev 23561 these errors are visible:

Configuration -> Discovery

• Sorting by field "d.name" not allowed.
• array_slice() expects parameter 1 to be array, boolean given [include/func.inc.php:1480]
• Invalid argument supplied for foreach() [discoveryconf.php:266]
  *the same sorting problems can be for "d.iprange" and "d.delay" values

Configuration -> Maintenance

• Sorting by field "status" not allowed. [CMaintenance.get -> zbx_db_sorting]
• Invalid argument supplied for foreach() [maintenance.php:456]
• array_slice() expects parameter 1 to be array, boolean given [include/func.inc.php:1480]
• Invalid argument supplied for foreach() [include/views/configuration.maintenance.list.php:53]

After clicking to the column's header to perform new sorting the errors are gone.

Main question - will these errors are visible for users first time after upgrade from 1.8?
Answer - YES. They will !
For the page Configuration -> Discovery they will for 100%, and for the page Configuration -> Maintenance they will if last sorting has been performed for "Status" column.

Possible solution: need to add this SQL statement to the upgrade patches:
DELETE FROM profiles WHERE idx IN ('web.maintenance.php.sort','web.discoveryconf.php.sort');

<Eduard> RESOLVED
<zalex> CLOSED
<sasha> Please review my changes in r23737.
<Eduard> CLOSED

<richlv> it should be listed here what solution was actually used. digging in a bunch of diffs is not good enough

<Eduard> We add SQL statement to the upgrade patches.

<richlv> i... might have been used to a different way to communicate and explain
what do those sql statements do ? users (or anybody else for that matter) shouldn't be forced to look up svn diffs to figure out such things - i eventually did take a quick look, and they drop some stuff from the profiles table.
what is the impact of that ? does that impact anything but sorting in some tables ? if so, do users who had set some specific sorting lose that sorting (it's reset to default) after the upgrade ?
if so, that should be documented in the upgrade notes.

<zalex> I support Rich, in general he is absolutely right. We have many examples where some minor (from a first look) changes/features are not documented but afterward we have noticeable problems with the our own understanding in "how it works/should work, etc".
Even in this example it's better to document more than less/nothing. At least here in the issue report an explanation of changes should be clean and sufficient to understanding without reading source code.
Sometimes in our forum I saw a link and I would like to mention it here as a good "analogy" to current case:
http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
(if the link will not work, try to google "How to Report Bugs Effectively")
Do you like my issue report (5) ? I hope yes, but I spent ~ 3 hours to find root of the problem, analyze this case from all point of view, to check all pages, possible sorting, etc and to finally describe the results cleanly.
Please, do spent 1-2 minutes too to describe how it has been fixed, document it, etc. Thanks.
At the end I would like to say "thank you" to Vladimir for last comment dated "2011 Dec 16 14:53" in the ZBX-2806. It's good example!

<Eduard> As I told previously we added SQL statement to the upgrade patches. This patches removes user sorting settings for all pages. It's very simple, so I don't know what can say more..

<richlv> after some additional discussion, my interpretation of user-visible effect added at http://www.zabbix.com/documentation/2.0/manual/installation/upgrade_notes - please, review
RESOLVED

<Eduard> CLOSED, thanks!

(6) After rev 23561 in the Configuration menu we lost possibility to sort by:
"Page -> Column(s)"
Maintenance -> State
Discovery -> IP range, Delay

Is it ok?

<Eduard> Yes, we decided to remove this sorting
<zalex> CLOSED
<richlv> any changes like these must be documented here : http://www.zabbix.com/documentation/2.0/manual/installation/upgrade_notes -> REOPENED
<richlv> i would also kindly ask to try to (we all can forget things, but not constantly ) mention any such decisions in the issue right away as they are made, if only to save testers'/code reviewers' time
<martins> added info on columns lost for sorting at: http://www.zabbix.com/documentation/2.0/manual/installation/upgrade_notes -> RESOLVED
<richlv> CLOSED

trunk revision 23902

see (5)

<Eduard> RESOLVED