.. _trackme_admin_priority_management:

Priority Management
###################

About priority levels in TrackMe
================================

.. hint:: Priority levels are an important concept in TrackMe which can easily be leveraged to categorize the importance of your different Splunk feeds, and for instance redirect notifications depending on entities priority levels.

    - TrackMe supports the following priority levels:
        - **critical**
        - **high**
        - **medium**
        - **low**
    - The priority level of an entity is defined by default when **discovered**, can be updated **per entity** or defined by **policy** or **externally** managed.
    - Entities are usually filtered when forwarding alerts to a third party, such as emails or a ticketing system, based on their priority level.
    - The priority is a valuable concept that can be leveraged to reduce noise and alert fatigue, a frequent and recommended practice is to focus on high and critical priorities, while other priorities can be considered over time.
    
*view example from a Virtual Tenant:*

.. image:: img_v2/admin_priority_management/vtenant_view001.png
   :alt: vtenant_view001.png
   :align: center
   :width: 1000px
   :class: with-border

*preview in Virtual Tenant:*

.. image:: img_v2/admin_priority_management/vtenant_view002.png
   :alt: vtenant_view002.png
   :align: center
   :width: 1000px
   :class: with-border

*view in Home UI:*

.. image:: img_v2/admin_priority_management/home_view1.png
   :alt: home_view1.png
   :align: center
   :width: 1000px
   :class: with-border

*view of an entity:*

.. image:: img_v2/admin_priority_management/home_view2.png
   :alt: home_view2.png
   :align: center
   :width: 1000px
   :class: with-border

Priority at discovery time
==========================

**TrackMe applies the priority level at discovery time, which is configurable on a per Virtual Tenant basis:**

*When the Virtual Tenant is created, you can define the default priority which will be applied to entities that are discovered:*

.. image:: img_v2/admin_priority_management/config_tenant_level001.png
   :alt: config_tenant_level001.png
   :align: center
   :width: 1000px
   :class: with-border

*Once the Virtual Tenant is created, you can update the default priority level in the Virtual Tenant settings:*

.. image:: img_v2/admin_priority_management/config_tenant_level002.png
   :alt: config_tenant_level002.png
   :align: center
   :width: 1000px
   :class: with-border

.. image:: img_v2/admin_priority_management/config_tenant_level003.png
   :alt: config_tenant_level003.png
   :align: center
   :width: 1000px
   :class: with-border

Managing priority at the entity level
=====================================

Updating the entity priority level in the modification screen
--------------------------------------------------------------

In the main entity screen, you can update the priority in the modification screen:

.. image:: img_v2/admin_priority_management/per_entity_001.png
   :alt: per_entity_001.png
   :align: center
   :width: 1000px
   :class: with-border

.. image:: img_v2/admin_priority_management/per_entity_002.png
   :alt: per_entity_002.png
   :align: center
   :width: 1000px
   :class: with-border

Updating entities in bulk via the table view
--------------------------------------------

In the Home view, you can update one or multiple entities at once within the table:

.. image:: img_v2/admin_priority_management/per_table_001.png
   :alt: per_table_001.png
   :align: center
   :width: 1000px
   :class: with-border

Updating entities in bulk selection
-----------------------------------

You can also select one or multiple entities in the table and update their priority level:

.. image:: img_v2/admin_priority_management/bulk001.png
   :alt: bulk001.png
   :align: center
   :width: 1000px
   :class: with-border

.. image:: img_v2/admin_priority_management/bulk002.png
   :alt: bulk002.png
   :align: center
   :width: 1000px
   :class: with-border   

Updating entities in SPL and REST API
-------------------------------------

You can also update the priority level of entities using SPL and the REST API, or the REST API via any mean:

*Example of SPL:*

::

    | trackme url="/services/trackme/v2/splk_dsm/write/ds_update_priority" mode="post" body="{'tenant_id': 'demo-priority', 'priority': 'high', 'object_list': 'eventgen-waf:akamai:cm:json,eventgen-waf:websense:cg:kv'}"


.. image:: img_v2/admin_priority_management/rest001.png
   :alt: rest001.png
   :align: center
   :width: 1000px
   :class: with-border

.. _trackme_admin_priority_management_policies:

Managing priority via policy
============================

.. admonition:: **TrackMe supports the management of priority levels via policy, which can be defined on a per Virtual Tenant basis:**

    - Policies are regex based expressions which are orchestrated by TrackMe automatically.
    - Matching entities get automatically updated with the priority level defined in the policy.
    - If multiple policies match a given entity, the highest level of priority takes precedence.
    - **Since TrackMe 2.1.10**, an entity which is managed by policies can still be updated manually, and the policy will not override the manual update.
    - TrackMe will show an informational message in the entity screen, displaying the policy that is managing the entity, the requested priority level, and the effective priority level.

*Accessing the policy management screen:*

.. image:: img_v2/admin_priority_management/policy001.png
   :alt: policy001.png
   :align: center
   :width: 1000px
   :class: with-border

*Defining a policy:*

.. image:: img_v2/admin_priority_management/policy002.png
    :alt: policy002.png
    :align: center
    :width: 1000px
    :class: with-border

.. image:: img_v2/admin_priority_management/policy003.png
    :alt: policy003.png
    :align: center
    :width: 1000px
    :class: with-border

*Modification screen when an entity is managed by a policy:*

.. image:: img_v2/admin_priority_management/policy004.png
    :alt: policy004.png
    :align: center
    :width: 1000px
    :class: with-border

*Modification screen when an entity is managed by a policy and manually updated:*

.. image:: img_v2/admin_priority_management/policy005.png
    :alt: policy005.png
    :align: center
    :width: 1000px
    :class: with-border

*Accessing entities managed by policies using trackmegetcoll:*

    - update the tenant_id
    - The following SPL can be accessed via the "Search table" button in TrackMe's UI, it leverages the real time decision maker and TrackMe REST API

::

    | trackmegetcoll tenant_id=feeds-secops component=dsm

    | where isnotnull(priority_policy_id)
    | table object, priority*    

.. image:: img_v2/admin_priority_management/policy006.png
    :alt: policy006.png
    :align: center
    :width: 1000px
    :class: with-border

.. _trackme_admin_priority_management_external:

Managing priority externally
============================

.. admonition:: **TrackMe supports the management of priority levels externally:**

    - External management is a way to update the priority level of entities using Splunk and any logic of your own.
    - Priority policies take precedence over external management.
    - If an entity is managed externally, the priority level can still be updated manually, and the external management will not override the manual update.
    - TrackMe will show an informational message in the entity screen, displaying the external management that is managing the entity, the requested priority level, and the effective priority level.
    - These instructions requires **TrackMe 2.1.10** or later.

*Example of SPL:*

    - Update the tenant_id
    - Update the search to match your needs, lookup files and logic 

::

    | inputlookup trackme_dsm_tenant_feeds-secops | eval keyid=_key

    ``` in this example, we leverage a Splunk lookup files referencing indexes and used to define the field priority_external ```
    | lookup feeds_priorities.csv index as data_index OUTPUT priority as priority_external
    | where isnotnull(priority_external)

    ``` the field priority_reason will be used by TrackMe to display an informational message ```
    | eval priority_reason="lookup: feeds_priorities.csv"

    ``` finally the KVstore records will be updated, schedule this search so that any newly discovered entity will retrieve the expected externally managed priority ```
    | outputlookup append=t key_field=keyid trackme_dsm_tenant_feeds-secops

*Modification screen when an entity is managed externally:*

.. image:: img_v2/admin_priority_management/external001.png
    :alt: external001.png
    :align: center
    :width: 1000px
    :class: with-border

*Modification screen when an entity is managed externally and manually updated:*

.. image:: img_v2/admin_priority_management/external002.png
    :alt: external002.png
    :align: center
    :width: 1000px
    :class: with-border

*Accessing entities managed by policies using trackmegetcoll:*

    - update the tenant_id
    - The following SPL can be accessed via the "Search table" button in TrackMe's UI, it leverages the real time decision maker and TrackMe REST API

::

    | trackmegetcoll tenant_id=feeds-secops component=dsm

    | where isnotnull(priority_external)
    | table object, priority*    

.. image:: img_v2/admin_priority_management/external003.png
    :alt: external003.png
    :align: center
    :width: 1000px
    :class: with-border