TISGraph & MDA Documentation

# Comments

See also

# Concept

"Comments" in MDA are a vital part of the database due to how flexible they are in adressing other data objects (like measure points and time series) or events. They are highly customizable due to the comment metadata system which allows you to specify your desired fields for any kind of comment type.

# Huge data structure

To realize this flexibility, comments in MDA make up a large part of the database structure, including several m:n relations. These will be described in more detail below.

# Topic (Subject / Detail)

Each comment has to be assigned exactly one category, or topic, which in turn are distinguished by "subject" and "detail". We recommend to use the "subject" field for a broader generalization of different command types (such as "Observation", "Maintainence" or "Rule Violation").

"detail" is recommended to be used for a more granular distinction within the subject. Examples could be "Observation / Erosion Downfall", or "Maintenance / Electric Circuits".

On the comment page, you will be able to filter for specific topics when searching for comments, and topic is a mandatory field when creating new comments.

The topic also determines which additional properties can be set for comments which use it. Which those are can be configured on the comment category admin subpage. Upon having them configured, these fields will then be available in the edit dialog as soon as the category is selected.

# Extra MetaData

It might be desirable to add specific additional information for any comment of a specific category. This could include information such as who performed an inspection, which date is was conducted etc.

For this purpose, you can define comment property keys, by specifying a name/descriptor as well as a data type. Currently, the only data types supported are "Text", "Date" and "Decimal Number".

It is also possible to add a placeholder(default) value which serves as a hint in the edit dialog regarding the input.

WARNING

Be mindful that the placeholder only serves as a hint, and does not actually enforce anything. The only thing that is enforced is the value adhering to the configured data type.

You can manage available comment property keys on the comment metadata admin subpage. Existing keys can then be assigned to categories in the category admin subpage.

TIP

You can assign the same property key to multiple different categories. This helps avoid redundancy between similar topics and keeps the number of properties managable.

# Attachments / Images

It is also possible to attach files, such as images or pdfs, to comments.

Any common mime type is accepted, and the same file can be attached to multiple different comments. An attachment can(and probably should) have a description for it, as well as an upload timestamp.

For attachments which were asynchronously added by an external source(such as HWE), the database can also store the text 'id' of that source. No specific source is stored for comments manually created in the MDA interface.

# Standard Properties

comment standard props in edit dialog

All comments have certain default properties, most of which are mandatory:

  • Topic: See above. Each comment needs to be assigned exactly one category.
  • Event timestamp: Optional, by default the current timestamp is entered. If the comment is related to a particular event(like an inspection), you can set that date here.
  • Event timezone: Optional. The timezone of the event timestamp.
  • Created: Automatically filled with the current date when adding a new comment.
  • Last edited: Automatically filled with the current date when saving a comment.
  • Creating user: Automatically filled with the given name of the creating user
  • Text: A description which constitutes the actual comment. Users can search for substrings of the text entered here.
  • Summary: A more brief description, which is usually used when displaying this comment in documents, i.e. TISGraph.

See above for the possibility to add additional properties to categories.

# Assignments

Comments can be linked to different MDA data objects, mainly to indicate that the content of it refers to said object(s), or that these objects are important in context. These links may be used to filter out comments being part of a measure-round and therefore being a measure-round based comment instead of for an unrelated event. Each comment-to-object assignment is an m:n relationship, and a comment can be assigned to different types of objects. For more information, see the main comments page. Additionally, you will be able to create comments on the pages of said objects. See below for details.

The object types a comment can be assigned to are:

# HWE "remarks"

  • A general remark of the measure round protocol is assigned to both the measure round and the mentioned protocol object.
  • A remark for the station is assigned to both the measure round and the measure point this remark was done in.
  • For a remark to a special parameter of the station, it is parsed to being starting with "dry", "moist", "droplets". If so, it is set as the "estimate" of this parameter and, if it was exactly that string, no comment is generated. Otherwise, the resulting comment is assigned to the measure round and time series of the paramter with all their depending (calculating) ones.

Note: The calculated assignments are not updated after the measureround was inserted once, even if one tries "recalculate".

# Ways to define / reach comments

There are multiple ways to access comments in MDA - The root comments page on the side bar, configuration pages as well as HWE.

# Root comments page

This can be reached in the top level sidebar. Comments sidebar icon

It serves as a general-purpose comments page which allows you to retrieve comments based on filter criteria, and then edit them or add new ones. For more details see the here.

# MeasurePoint - comments page

Upon selecting a measure point or time series in the measure point tree, you are by default redirected to the "Values" tab. By switching to the "Comments" tab, you are given the same search GUI as the one on the root page.

MP comment page

While on this page, all searches will automatically have the additional filter to only show comments assigned to the selected measure point or time series.

# Daily protocols and measure round protocols

On the daily protocols page, you can add comments by simply clicking the plus sign in the "Comments" column.

The comment dialog opened here will automatically have assignments set to both the protocol and time series in question.

# HWE (see above)

Comments assigned to historic measure rounds and some time series or measure point are downloaded and (the last one) shown in HWE's historic data view.

Historic value table in HWE

# Bind comment into TISGraph document / graph

You can add a comment into your TISGraph document which binds a comment shape to the average time of the comment in your data graph. The summary text is shown in TISGraph and moved with the time period as long as the average time of the comment is within the graph.

← Devices and Users →