Graph UI - recording user annotations

[elasticmachine]

Original comment by @markharwood:

Following a recent conversation with a user (he investigates things like LINK REDACTED). We discussed the option of allowing investigators to attach notes to vertices of interest as part of the investigation process. Other investigators working in different workspaces could then pull in notes from other investigations as part of "spidering around" the original data.

Index configuration

This could be achieved by having a side-index to the main content eg. if you had the panamapapers index you could have a panamapapers_notes index to record investigator notes.
The Graph UI could then be configured with an index pattern of panamapapers* to pull in content from both of these indices. The panama vertices and any associated notes would automatically be linked in the UI on the basis of sharing the same term.

Capturing annotations

As a result of the newLINK REDACTED feature we have a hook for performing custom actions on selections in the Graph UI. This issue proposes that we could use this feature to take a user to an "add annotation" page which could be used to enter content that is then added as fields in a new doc to the choice of index (e.g. panamapapers_notes) along with fields for the selected vertices passed in the URL. Once indexed, the user can then return to the Graph app and expanding from the selected vertices should then pull in the new content added to the panamapers_notes side index.

How far should we go in the first instance?

The question is to what extent we support this feature. In order of complexity/sophistication I see the following implementation options:

1. An example Graph-annotator plugin that has to be installed and then configured as a new drill-down url in every graph workspace that wants to use it (no changes to Graph core required)
2. An in-built service in the Graph UI to create new annotation documents (no need for drill-down urls) with automated refresh of the UI to patch in the new note to the workspace.
3. An in-built service in the Graph UI that can attach new annotation documents but also other forms of records that can be interpreted as performing special actions (vertex-grouping actions, custom icons for vertices).

For now option 1 feels like a "safe" option as it does not require any changes to core and could be open-sourced as an example annotator that can be customised in terms of what people want to capture in notes etc.

[elasticmachine]

Original comment by @markharwood:

Here's a demo of this working with a new annotator plugin: LINK REDACTED

Thoughts, @skearns64 ?

[elasticmachine]

Original comment by @markharwood:

@uboness can I open-source the "annotator" plugin used in LINK REDACTED ?

My assumption is that end-users will want to capture many and varied attributes as part of a Graph annotation (author, date, tags, risk flag, priority, completedYN ....) and they can use this plugin as the starter template for this data entry.

[elasticmachine]

Original comment by @markharwood:

Had a discussion 28/Oct/16 with @skearns64 and @uboness where we reached some conclusions but there are still a lot of issues to consider. Details below.

We dismissed option 1 in the proposal above (using a plugin outside of Graph, accessed via a drill-down link) and opted for option 2/3 where annotations are a new first-class feature of Graph.

Agreed principles of annotations design

1. "Metadata" for a vertex - associated with an index-pattern+field+value e.g. "people/name/mark"
2. Held in a new internal index which is automatically created e.g. ".graph-annotation"
3. CRUD operations are performed using a new extension to the existing elasticsearch Graph API. 4. Annotations are automatically-loaded and attached to Graph API results
4. Globally visible - annotations live outside of Kibana's saved workspaces and so should be thought of as representing a universally accepted truth rather than a private note. (So perhaps "annotation" is not the right word?)
5. There is no relationship life-cycle management e.g "cascading deletes". An annotation for an IP address might out-live the time-based index of event log data where the IP address was first recorded.

It can be helpful to think of systems as having event data (what makes the edges) and nouns (the real-world entities that we attach annotations to).

Things we haven't agreed: what should we record in an annotation?

1. A relationship? This was the original use case where annotations appeared as connected vertices in the Graph.
   !LINK REDACTED
2. Decorators? Flags that can be mapped to highlight risk or other points of interest. (Users really want this kind of thing!)
   !LINK REDACTED
3. Vertex labels / other metadata?
   !LINK REDACTED

These are all potentially useful features to consider but they lead us towards a general issue:

Problem: drawing the line between annotations and "reference data"

It is difficult to rationalize why a system for pulling in hand-authored Graph annotations might not also generally be applied to tackling theLINK REDACTED of pulling in "reference data" in a normalized form of data. Why should Graph be the only Kibana plugin capable of labelling product "SKU 439026" in a meaningful way to end users? Why should this reference data be tied up in a .graph-annotations index?

There's a continuum of use cases here which range from:

1. An occasional link to show where someone thought two vertices looked similar
2. An occasional note that is used to flag only the closed-as-fraudulent bank accounts
3. A marker for every internal IP address (as opposed to external ones)
4. An English label for every product SKU code.

All of these are look-ups and it's hard to know where to draw the line here. Thoughts, @skearns64 and @uboness ?

[elasticmachine]

Original comment by @skearns64:

I suggest we start simple, with well-defined annotation types. I'm trying to imagine the Graph Annotation API, and I would guess that it accepts two types of annotations:

1. Metadata against an Entity/vertex. Doc specifies the vertex ID info (index pattern, field name, field value), plus a set of metadata. Initially, this could be just a free text "note" field (possibly with markdown support?). Then, in subsequent versions, we could decide to include other types of vertex annotations, like icon/image, key/value, etc.
   • I would imagine that this would be rendered as some kind of info box on a node. I don't have a sense of an appropriate UX (is it in the right side power panel, or a pop-up in-graph?). I don't view this type of data as being rendered as a separate "vertex".
2. New Linked Vertex: This type of annotation would specify a new vertex (index pattern, field name(?), field value), and one or more vertices that it links to. The new vertex could contain the same kinds of metadata as are in (1)

I wouldn't rush to have the vertex metadata contain a "display name," as I agree that this is something needed in Kibana more widely, and I don't think that it is (yet) the most important feature for Graph. If I'm wrong about that, we might have to do something special for Graph and adopt/adapt whatever method Kibana provides in the future.

[elasticmachine]

Original comment by @markharwood:

I agree that it is useful to think of the 2 annotation categories (vertex-metadata and linked-vertex). There is potentially an argument that an annotation designed to link 2 existing vertices may sometimes want to be shown as an edge (to expose details we may choose to add edge labels and edge drill-downs).

Link visualization is definitely "a graph thing" so I'm comfortable tackling the linked-vertex part of annotations but I feel uncomfortable about tackling vertex-metadata as a graph concept. This is arguably a more general noun-metadata and has applications across the whole of Kibana. Every visualization that shows terms (bars, pies, swim-lanes, line-charts ...) can benefit from offering noun-metadata for each of the terms it displays. It doesn't make sense to me to make this a graph-only thing.

[elasticmachine]

Original comment by @skearns64:

I see your point, and at a high-level, I agree.

However, I would imagine that in practice, you would want to annotate the linked-vertex object with some kind of metadata, otherwise, you would have no where to put notes, etc, and all you would be doing is adding a new type of connection. If you're going to be doing that, you are effectively implementing vertex-metadata, but without a nice, clear specification. That's the line of thinking that led me to believe that vertex-metadata is both necessary and a prerequisite to linked-vertex support.

[elasticmachine]

Original comment by @markharwood:

Following a conversation with @skearns64 we have agreed to park this feature for the moment.

Much of the functionality in associating metadata to vertices/terms has utility outside of the Graph plugin. Graph should not be the only Kibana feature that is capable of providing additional details behind the raw indexed terms we show in results. A more general framework is required for pulling in reference data regardless of the visualization tool used to show results.

This requires a common model definition and raises questions about how that is bundled into elasticsearch or xpack or kibana. There are many questions here so we need to think about this problem more broadly.

[elasticmachine]

Pinging @elastic/kibana-data-discovery (Team:DataDiscovery)

[elasticmachine]

Pinging @elastic/kibana-visualizations @elastic/kibana-visualizations-external (Team:Visualizations)

[timductive]

Closing this because it's not planned to be resolved in the foreseeable future. It will be tracked in our Icebox and will be re-opened if our priorities change. Feel free to re-open if you think it should be melted sooner.