.. Netfiles API documentation master file, created by
   sphinx-quickstart on Fri Mar  6 11:42:21 2020.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Meeting Topic
=============

An **Meeting Topic** represent a single Meeting Topic in a meeting. It has various additional attributes.



HW Object
---------

An **Meeting Topic** is a HyperWave object of an ``NF_MeetingTopic`` ``documentClass`` and of ``type`` ``collection``.

+-----------------------+-----------------------+---------------------------------------------------------------+
| Attribute Name        | Attribute Type        | Comments                                                      |
+=======================+=======================+===============================================================+
| id                    | String                | The globally Unique ID of the object                          |
+-----------------------+-----------------------+---------------------------------------------------------------+
| documentClass         | String                | "NF_MeetingTopic"                                             |
+-----------------------+-----------------------+---------------------------------------------------------------+
| type                  | String                | "collection"                                                  |
+-----------------------+-----------------------+---------------------------------------------------------------+
| version               | String                | Current version of the object                                 |
+-----------------------+-----------------------+---------------------------------------------------------------+
| author                | String                | Name of the user who created this object                      |
+-----------------------+-----------------------+---------------------------------------------------------------+
| creationDate          | DateTime              | Date & Time of Creation                                       |
+-----------------------+-----------------------+---------------------------------------------------------------+
| modificationDate      | DateTime              | Date & Time of last modification                              |
+-----------------------+-----------------------+---------------------------------------------------------------+
| name                  | String                | The name of the object                                        |
+-----------------------+-----------------------+---------------------------------------------------------------+
| owner                 | List<NFParticipant>   | JSON Array representing a list of NFParticipant (s. below)    |
+-----------------------+-----------------------+---------------------------------------------------------------+
| title                 | String                | Title of the object usually shown to the users                |
+-----------------------+-----------------------+---------------------------------------------------------------+
| path                  | String                | Path relative to the server                                   |
+-----------------------+-----------------------+---------------------------------------------------------------+
| downloadProhibited    | Boolean               | Whether the download is prohibited or not                     |
+-----------------------+-----------------------+---------------------------------------------------------------+
| writeAccess           | Boolean               | Whether writing is allowed for the current user               |
+-----------------------+-----------------------+---------------------------------------------------------------+
| subDocs               | String                | As a string the number of documents below this level          |
+-----------------------+-----------------------+---------------------------------------------------------------+

Additionally to the standard HW_Object Attributes, we have the following attributes for
``NF_MeetingTopic``.

+-------------------------+---------------------+---------------------------------------------------------------+
| Attribute Name          | Attribute Type      | Comments                                                      |
+=========================+=====================+===============================================================+
| topic                   | String              | Topic of the Meeting Topic (if different from ``title``)      |
+-------------------------+---------------------+---------------------------------------------------------------+
| topicBegin              | DateTime            | Begin of the Meeting Topic (Date + Time / HWDateTime Format)  |
+-------------------------+---------------------+---------------------------------------------------------------+
| topicDuration           | Integer             | Duration in minutes                                           |
+-------------------------+---------------------+---------------------------------------------------------------+
| host                    | List<NFParticipant> | JSON Array representing a list of NFParticipant (s. below)    |
+-------------------------+---------------------+---------------------------------------------------------------+
| guests                  | List<NFParticipant> | AJSON Array representing a list of NFParticipant (s. below)   |
+-------------------------+---------------------+---------------------------------------------------------------+
| requiresVoting          | Boolean             | Whether this topic requires voting                            |
+-------------------------+---------------------+---------------------------------------------------------------+
| status                  | String              | S. below                                                      |
+-------------------------+---------------------+---------------------------------------------------------------+
| voted                   | Boolean             | Whether a voting did happen or not                            |
+-------------------------+---------------------+---------------------------------------------------------------+
| NF_VotingDetails        | String              | Voting result (s. below)                                      |
+-------------------------+---------------------+---------------------------------------------------------------+

This object has children, which can be retrieved using :doc:`Get Children </calls/getchildren>`. The children
of an object of ``documentClass`` ``NF_MeetingTopic`` can only be objects of class ``TBD-meetingtopicminutes`` as described
in :doc:`Meeting Topic Minutes <meetingtopicminutes>` or of class ``document``.

There can be no other types of objects, especially no further ``collection`` or such.

Explanation
-----------

NFParticipant
  Any data containing person information (host, participants, guests, etc.) consists of a json-structure per
  person of type described below.  If it contains a Hyperwave ID (``UObjname`` != ``""``), the user data is
  retrieved using :doc:`Get Object </calls/getobject>` call. Otherwise the ``UObjrealname`` is used as is.

.. code::

  NFParticipant := {
    UObjrealname: string,
    UObjname: string
  }


host | owner
  This is the owner of the meeting topic. If the entry is empty (== []), then the host of the meeting is also
  the host of this specific meeting topic. Though there is only one host/owner, the server returns an array
  with at most one entry - as specified.

  Examples:

.. code::

  owner: [
      {
        UObjrealname: "Tom Krempl",
        UObjname: "ID-29855.6518164830361-1"
      }
  ]

  host: [
      {
        UObjrealname: "Tom Krempl",
        UObjname: "ID-29855.6518164830361-1"
      }
  ]

guests
  This is the list of guests for this meeting topic. They can be empty list or lists of persons.
  Default value is empty array (== ``[]`` )

  Examples:

.. code::

  guests: [
    {
        UObjrealname: "Tom Krempl",
        UObjname: "ID-29855.6518164830361-1"
    },
    {
        UObjrealname: "Hans Meiser",
        UObjname: ""
    }
  ],

requiresVoting
  This describes whether there is a voting required by **participants** of the meeting on this topic.

  If a Meeting Topic requires voting, the voting result will be logged in the Meeting Topic Results.

status
  is any of ``none``, ``started``, or ``ended``. It represents the
  status of the Meeting Topic.
  Default (if the user hasn't changed anything) is ``none``.

voted
  If a voting was required on this Meeting Topic, this indicates whether a voting **did** happen. Sometimes a topic
  might just have been postponed. In this case, you can still close the Meeting Topic (and lock the result) even if
  a voting did not happen.

  If this is set to ``true``, there must be the log of votes in ``NF_VotingDetails`` below.

  This attribute is only used when status is ``ended`` or ``closed``. When the status is something else, this attribute
  is ignored.

NF_VotingDetails
  If voting was required for this Meeting Topic, this contains the result of the votes. It is a list of dictionaries.
  E.g.:

.. code::

    [
        {
            UObjrealname: "Tom Krempl",
            UObjname: "ID-29855.6518164830361-1",
            vote: "neutral"
        },
        {
            UObjrealname: "Imdat Solak",
            UObjname: "",
            vote: "positive"
        },
        {
            UObjrealname: "Hans Meiser",
            UObjname: "",
            vote: "negative"
        }
    ]

If no voting was required, this is an empty string.