.. _dynamic_app_rest_api: Usage ===== 1) Overview ----------- Endpoints ^^^^^^^^^ - ``GET /lce/api/powerpacks/{powerpack_identifier}`` *(GUID, ID, or name)* - ``GET /lce/api/dynamic_applications/{app_identifier}`` *(GUID, ID or name)* - ``POST /lce/api/dynamic_applications`` *(normalized request form)* - ``GET /lce/api/dynamic_applications`` *(filter required)* - ``GET /lce/api/event_policies/{event_identifier}`` *(GUID, ID, or name)* - ``GET /lce/api/event_policies`` *(filter required)* - ``POST /lce/api/event_policies`` *(normalized request form)* The Dynamic Applications API supports retrieving and bulk updating a Dynamic Application (DA) and its related entities: - **Dynamic Application** - **Snippets** - **Collection Objects** - **Presentation Objects** *(performance DAs only)* - **Threshold Objects** - **Alert Objects** *(including triggered-alert chaining)* - **Event Policies** The **POST** endpoints are designed to support "single payload" Snippet Framework workflows: - Create/update one or more Dynamic Applications and all their entities in **one POST** - Create/update one or more Event Policies in **one POST** - Allow in-request linking for new entities using **``reference``** - Enforce strict "which fields are legal" rules for: - performance vs configuration dynamic applications - discovery collection objects - enum collection objects - event-policy source-specific fields Query parameters ^^^^^^^^^^^^^^^^ ``pretty`` (GET + POST) """"""""""""""""""""""" All endpoints support a ``pretty`` boolean query parameter. Defaults to true. - ``pretty=true`` - Enums are serialized as their **string names** (e.g., ``"ENABLED"``, ``"PERFORMANCE_GAUGE"``, ``"SYSLOG"``) - Output is intended to be more human-readable (debugging, documentation, examples) - ``pretty=false`` - Enums are serialized as their **integer values** - Output is more compact and better suited for programmatic diffing .. note:: Regardless of ``pretty``, request payloads accept enums as either integers or string names (case-insensitive). ---- ``fields`` (GET + POST) """"""""""""""""""""""" All endpoints support an optional ``fields`` query parameter that controls **which fields are included** in the response payload. This parameter supports: - **Wildcards** (e.g. ``*.guid, dynamic_applications.*.id``) - **Nested paths** - **Pydantic-style include behavior** (i.e., "include only these fields") When ``fields`` is provided, the response is treated as an **allowlist**: - Only the requested fields will be returned - Any fields not explicitly included will be omitted - ``validation_errors`` (stored values that fail validation) is always included when present, see `Validation phases`_ Examples '''''''' - Return only the Dynamic Application identifiers: - ``fields=guid,id,name`` - Return the name of all entities in all Dynamic Applications in a PowerPack: - ``fields=dynamic_applications.*.name`` - Return the identifiers for all nested entities in a Dynamic Application: - ``fields=*.name,*.guid,*.id`` - Return only Event Policy identifiers: - ``fields=guid,id,name`` ---- ``exclude`` (GET + POST) """""""""""""""""""""""" All endpoints support an optional ``exclude`` query parameter that controls **which fields are excluded** from the response payload. This parameter supports: - **Wildcards** (e.g. ``entities.*.internal_state``) - **Nested paths** - **Pydantic-style exclude behavior** (i.e., "return everything except these fields") When ``exclude`` is provided, the response is treated as a **blocklist**: - All fields are returned by default - The excluded fields are removed from the output Examples '''''''' - Exclude large fields that are noisy in diffs: - ``exclude=dynamic_applications.release_notes,dynamic_applications.snippets.snippet`` - Exclude identifiers for all entities in a Dynamic Application when wanting to create new entities from an example PowerPack: - ``exclude=dynamic_applications.*.guid,dynamic_applications.*.id,*.id,*.guid`` - Exclude noisy Event Policy fields: - ``exclude=description`` ---- Combined behavior (``fields`` + ``exclude``) """""""""""""""""""""""""""""""""""""""""""" Both parameters are optional and default to ``None``. 1) Neither provided (default) ''''''''''''''''''''''''''''' If neither ``fields`` nor ``exclude`` is provided: - The response returns the **full default payload** - No additional filtering is applied 2) Only ``fields`` provided ''''''''''''''''''''''''''' If only ``fields`` is provided: - The response returns **only** the fields requested by ``fields`` - All other fields are omitted This is the strictest / smallest output mode. 3) Only ``exclude`` provided '''''''''''''''''''''''''''' If only ``exclude`` is provided: - The response returns the full payload - Any matching excluded fields are removed This is the safest mode for "everything except the huge/noisy parts." 4) Both ``fields`` and ``exclude`` provided ''''''''''''''''''''''''''''''''''''''''''' If both are provided: 1. The response is first filtered using ``fields`` (includes allowlist) 2. Then ``exclude`` is applied to remove any excluded fields from that included result In other words: - ``fields`` defines the maximum set of fields that *may* appear - ``exclude`` removes a subset of those fields 5) Notes / expected behavior '''''''''''''''''''''''''''' - ``fields`` and ``exclude`` affect **response serialization only**. - They do **not** affect request validation - They do **not** change what is stored - They do **not** change normalization rules - Wildcards apply at any nesting level, including ``collection_objects.*``. - If a requested ``fields`` path does not exist on an object, it is ignored (no error). - If a requested ``exclude`` path does not exist on an object, it is ignored (no error). ---- ``retrieve`` (POST only) """""""""""""""""""""""" ``POST /lce/api/dynamic_applications`` and ``POST /lce/api/event_policies`` support a ``retrieve`` boolean query parameter. Defaults to false. - ``retrieve=true`` - The response includes a fully-expanded ``entities`` list containing the stored/normalized objects - This is useful for: - retrieving newly assigned ``guid`` and ``id`` values - seeing canonical ``reference`` rewrites (``o_``, ``snip_``, ``a_``, etc.) - ``retrieve=false`` - The response includes only the ``results`` array (per-entity identifiers + created/updated flags) - This is the default mode for bulk updates where the client does not need the full entity payload ---- ``commit`` (POST only) """""""""""""""""""""" ``POST /lce/api/dynamic_applications`` and ``POST /lce/api/event_policies`` support a ``commit`` boolean query parameter. Defaults to true. - ``commit=true`` - This is the default mode where all entities are upserted - ``commit=false`` - The process of upserting behaves identically except nothing will actually be altered on the system. This means no entities will actually be changed or created. - This is useful for: - validating payloads to ensure they will output the expected results before committing (``retrieve=true``) - running the API in testing frameworks without having to clean up the system after ---- ``require_all_filters`` (all filtered endpoints) """""""""""""""""""""""""""""""""""""""""""""""" When multiple filter query parameters are provided, ``require_all_filters`` controls how they are combined. - ``require_all_filters=true`` - All filters must match (**AND** logic) - ``require_all_filters=false`` - Any filter may match (**OR** logic) If not provided, the default is ``True`` (all filters must match). Example ''''''' - Match applications where **name contains** ``cpu`` **and** ``state`` is 1: - ``?require_all_filters=true&filter[name][contains]=cpu&filter[state][is]=1`` - Match applications where **name contains** ``cpu`` **or** ``state`` is 1: - ``?require_all_filters=false&filter[name][contains]=cpu&filter[state][is]=1`` .. note:: The join behavior applies to the set of filters provided in the request. If only one filter is provided, ``require_all_filters`` has no practical effect. ---- Filtering (``filter[...]`` query parameters for filtered endpoints) """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" Filtering is expressed using query parameters of the forms: filter[][]= filter[][not][]= Multiple ``filter[...]`` parameters may be supplied in a single request. Each filter contributes one SQL predicate, and predicates are joined according to ``require_all_filters``. Supported operators ''''''''''''''''''' The following operators are supported: - ``is`` - ``contains`` - ``gt`` (only single value is allowed) - ``lt`` (only single value is allowed) - ``search`` (only single value is allowed; not negatable) All of the operators support the use of ``not`` to negate the statement unless otherwise specified. If an unsupported operator is provided, the request is rejected with a validation error. Value format '''''''''''' Filter values are parsed as strings and may contain **comma-separated** values (Except when using the ``gt`` or ``lt`` operators): - ``filter[id][is]=1,2,3`` - ``filter[name][contains]=cpu,memory`` - ``filter[name][not][contains]=cpu_max`` - ``filter[state][is]=ENABLED`` *(case-insensitive enum values are supported)* - ``filter[type][is]=SNIPPET_CONFIGURATION,SNIPPET_PERFORMANCE`` - ``filter[cu_affinity][is]=1,ASSIGNED_COLLECTOR`` *(can mix and match enum and integer values)* Whitespace around comma-separated values is ignored. Operator semantics '''''''''''''''''' ``[is]`` ~~~~~~~~ Matches when the field equals the provided value, or matches **any** of the values if multiple are provided. - Single value: - ``filter[name][is]=router`` → ``name = "router"`` - Multiple values: - ``filter[id][is]=1,2,3`` → ``id IN (1,2,3)`` - Special case: ``null`` (case-insensitive) is treated as a SQL NULL check: - ``filter[description][is]=null`` → ``description IS NULL`` - Mixed null + values produces a combined expression: - ``filter[description][is]=null,foo`` .. note:: The ``null`` special case only applies when the field accepts ``null`` values. Otherwise, it will be treated as the string literal ``"null"``. Optional enum fields (for example the Event Policy ``syslog_facility``, ``syslog_severity`` and ``override_identifier_type``) accept ``null``, so ``filter[syslog_severity][is]=null`` matches the Event Policies without a value. ``[not][is]`` ~~~~~~~~~~~~~ Negated form of ``is``. - Single value: - ``filter[name][not][is]=router`` → ``name != "router"`` - Multiple values: - ``filter[id][not][is]=1,2,3`` → ``id NOT IN (1,2,3)`` - ``null`` support: - ``filter[description][not][is]=null`` → ``description IS NOT NULL`` - Mixed null + values combines with the appropriate negation logic. .. note:: The ``null`` special case only applies when the field accepts ``null`` values. Otherwise, it will be treated as the string literal ``"null"``. ``[contains]`` ~~~~~~~~~~~~~~ Substring match. Each value is converted to a SQL ``LIKE`` pattern with wildcards automatically added on both sides: - ``filter[name][contains]=cpu`` → ``name LIKE "%cpu%"`` - Multiple values match if **any** pattern matches: - ``filter[name][contains]=cpu,memory`` → ``(name LIKE "%cpu%" OR name LIKE "%memory%")`` ``[not][contains]`` ~~~~~~~~~~~~~~~~~~~ Negated substring match. Wildcards are still applied: - ``filter[name][not][contains]=test`` → ``name NOT LIKE "%test%"`` - Multiple values require **all** patterns to not match: - ``filter[name][not][contains]=test,dev`` → ``(name NOT LIKE "%test%" AND name NOT LIKE "%dev%")`` ``[gt]`` ~~~~~~~~ Matches when the field is greater than the provided value. - Single value: - ``filter[version][gt]=1`` → ``version > 1`` - Multiple values: - Will raise an error because multiple values are not supported for the ``gt`` operator. ``[not][gt]`` ~~~~~~~~~~~~~ Negated form of ``gt``. - Single value: - ``filter[version][not][gt]=1`` → ``version <= 1`` - Multiple values: - Will raise an error because multiple values are not supported for the ``gt`` operator. ``[lt]`` ~~~~~~~~ Matches when the field is less than the provided value. - Single value: - ``filter[version][lt]=1`` → ``version < 1`` - Multiple values: - Will raise an error because multiple values are not supported for the ``lt`` operator. ``[not][lt]`` ~~~~~~~~~~~~~ Negated form of ``lt``. - Single value: - ``filter[version][not][lt]=1`` → ``version >= 1`` - Multiple values: - Will raise an error because multiple values are not supported for the ``lt`` operator. ``[search]`` ~~~~~~~~~~~~ Fuzzy text search that finds approximate matches using string similarity algorithms. This operator performs fuzzy matching against all existing values in the specified database column and returns results that meet the minimum similarity threshold. - Single value (required): - ``filter[name][search]=Account`` → Finds fuzzy matches like "Accounts Discovery", "Account Performance", "Account Configuration" - Multiple values: - Will raise an error because multiple values are not supported for the ``search`` operator. - Non-string values: - Will raise an error because the ``search`` operator requires a string value. - No relevant match found: - Will raise an error because the ``search`` operator intends to find matching values. The search operator uses token-based similarity scoring and automatically converts matching results into equality-based SQL WHERE clauses. If no relevant matches are found above the similarity threshold, the filter returns no results. .. note:: The ``search`` operator cannot be negated with ``[not]`` and does not support the ``null`` special case. Putting it together ''''''''''''''''''' Example: AND across different fields ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: text GET /lce/api/dynamic_applications ?require_all_filters=true &filter[name][contains]=cpu &filter[state][is]=1 Example: OR across filters ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: text GET /lce/api/dynamic_applications ?require_all_filters=false &filter[name][contains]=cpu &filter[state][is]=1 Example: Event Policy filtering ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: text GET /lce/api/event_policies ?require_all_filters=true &filter[source][is]=SYSLOG &filter[name][contains]=interface Error behavior '''''''''''''' - If no valid ``filter[...]`` parameters are provided, the request fails with a validation error. - If a filter field is invalid for the entity, the request fails with a validation error. - If a filter key does not match ``filter[][]`` or ``filter[][not][]``, the request fails with a validation error. ---- 2) Authentication & Authorization --------------------------------- Authentication ^^^^^^^^^^^^^^ Requires a valid Skylar One user session. Access Hooks ^^^^^^^^^^^^ To call ``GET /lce/api/dynamic_applications/{app_identifier}`` or ``GET /lce/api/dynamic_applications`` you must have the following Access Hooks: - ``DYN_APP_VIEW`` - ``EVT_POLICY_VIEW`` To call ``GET /lce/api/powerpacks/{powerpack_identifier}`` you must have the following Access Hooks: - ``DYN_APP_VIEW`` - ``EVT_POLICY_VIEW`` - ``SYS_POWERPACK_REG_PAGE`` To call ``POST /lce/api/dynamic_applications`` you must have the following Access Hooks: - ``SYS_DYN_APP_EDIT`` - ``DYN_APP_EDIT`` - ``DYN_APP_VIEW`` - ``DYN_APP_FORMULA_EDIT`` - ``EVT_POLICY_VIEW`` - ``EVT_POLICY_EDIT`` To call ``GET /lce/api/event_policies/{event_identifier}`` or ``GET /lce/api/event_policies`` you must have the following Access Hook: - ``EVT_POLICY_VIEW`` To call ``POST /lce/api/event_policies`` you must have the following Access Hooks: - ``EVT_POLICY_VIEW`` - ``EVT_POLICY_EDIT`` ---- 3) Identifiers & request-scoped linking --------------------------------------- 3.1 ``guid`` (globally persistent identifier) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Uppercase 32-hex string (``^[A-F0-9]{32}$``) - Marks an entity as **existing** (update semantics) - Immutable once created **Rule:** If you supply a ``guid``, the system treats the entity as *existing* and will update it. An exception will be raised if the entity with the GUID cannot be found. Updates are applied on top of the stored state of the entity: - any field you omit keeps its stored value, including the discovery fields of collection objects and list fields such as ``component_identifiers``, ``auto_clear_events`` and ``component_mapping_dynamic_applications`` (send an empty list to clear a list field) - a reference field sent without its ID field (``snippet_reference`` without ``snippet_id``, ``triggered_alert_reference`` without ``triggered_alert_id``, ``link_reference`` without ``link_id``) replaces the stored ID; sending one of these reference fields as ``null`` is rejected (HTTP 422), omit it to keep the stored ID - the ``id`` of an existing entity is taken from its ``guid``; a provided ``id`` is ignored - a payload that provides the same Dynamic Application GUID more than once (``POST /lce/api/dynamic_applications``) or the same Event Policy GUID more than once (``POST /lce/api/event_policies``) is rejected (HTTP 422) - the complete resulting entity is validated, including the stored values you do not provide, so a stored value that violates a rule (for example, a stored ``execution_environment`` that no longer exists) rejects the update until the request fixes it (see `Validation phases`_) 3.2 ``reference`` (request-scoped identifier) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - A string label used to link **new** entities inside the same request - Any string value (e.g., ``"cpu"``, ``"snippet_1"``, ``"alert_base"``, ``"event_1"``) - Must be **unique across the entire payload** (across all entity types) - Returned back on response objects as ``reference`` **Rule:** ``reference`` does *not* persist as identity; it's only for request wiring and reporting. Reference auto-defaulting """"""""""""""""""""""""" - If a model has ``guid`` and you omit ``reference``, the base mixin sets ``reference = guid``. - Some entities override ``set_reference()`` after DB insert to set canonical references: - ``CollectionObject.reference = "o_"`` - ``PresentationObject.reference = "pres_"`` - ``AlertObject.reference = "a_"`` - ``Snippet.reference = "snip_"`` - ``ThresholdObject.reference = "t_"`` .. note:: Practical guidance: **always provide** ``reference`` for new objects you want to wire by reference in the same request. 3.3 ``id`` (DB numeric identifier) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Returned in responses; not a stable external identifier for clients as it's not globally unique - All ``id`` fields are **locked** (cannot be set) - If an ``id`` is provided in a **POST** request, it is ignored - Generally not accepted/required for requests except in a few internal linkage fields (e.g., ``snippet_id``, ``triggered_alert_id``, ``link_id``) ---- 4) Enum values: what you can send --------------------------------- Your enums inherit flexible enum behavior, which means request payloads accept **both**: - integer values (e.g., ``1``) - string enum names (e.g., ``"ENABLED"``, ``"PERFORMANCE_COUNTER"``, ``"SYSLOG"``) — case-insensitive Examples: .. code-block:: json { "state": 1 } { "state": "ENABLED" } { "source": "SYSLOG" } Responses will typically emit the **string** as *pretty* serialization is the default. ---- 5) Request structure -------------------- ``POST /lce/api/dynamic_applications`` expects the **normalized** form of all the Dynamic Application specific keys at the root level and other entities such as ``snippets`` nested within. The endpoint also accepts multiple Dynamic Applications in a list, or wrapped in an object with a ``dynamic_applications`` key. Single Dynamic Application ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: json { "guid": "96AA113228DCF8E1396C45DFE2EAB9C0", "name": "Dynamic Application Name", "type": "SNIPPET_PERFORMANCE", "snippets": [ ... ], "collection_objects": [ ... ], "presentation_objects": [ ... ], "threshold_objects": [ ... ], "alert_objects": [ ... ], "event_policies": [ ... ] } Multiple Dynamic Applications (Array) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: json [ { "guid": "96AA113228DCF8E1396C45DFE2EAB9C0", "name": "Dynamic Application Name", "type": "SNIPPET_PERFORMANCE", "snippets": [ ... ], "collection_objects": [ ... ], "presentation_objects": [ ... ], "threshold_objects": [ ... ], "alert_objects": [ ... ], "event_policies": [ ... ] }, { "type": "SNIPPET_CONFIGURATION", "snippets": [ ... ], "collection_objects": [ ... ], "threshold_objects": [ ... ], "alert_objects": [ ... ], "event_policies": [ ... ] } ] Multiple Dynamic Applications (Wrapped Object) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This wrapped object could come from another endpoint such as the PowerPack retrieval endpoint. .. code-block:: json { "dynamic_applications": [ { "guid": "96AA113228DCF8E1396C45DFE2EAB9C0", "name": "Dynamic Application Name", "type": "SNIPPET_PERFORMANCE", "snippets": [ ... ], "collection_objects": [ ... ], "presentation_objects": [ ... ], "threshold_objects": [ ... ], "alert_objects": [ ... ], "event_policies": [ ... ] }, { "type": "SNIPPET_CONFIGURATION", "snippets": [ ... ], "collection_objects": [ ... ], "threshold_objects": [ ... ], "alert_objects": [ ... ], "event_policies": [ ... ] } ], "ignored_additional_field": "ignored_value" } Event Policy POST Payload ^^^^^^^^^^^^^^^^^^^^^^^^^ ``POST /lce/api/event_policies`` accepts either a single Event Policy object or a list of Event Policy objects. Single Event Policy """"""""""""""""""" .. code-block:: json { "name": "Interface Down", "message": "Interface is down", "source": "SYSLOG" } Multiple Event Policies """"""""""""""""""""""" .. code-block:: json [ { "name": "Interface Down", "message": "Interface is down", "source": "SYSLOG" }, { "name": "Trap Example", "message": "Trap received", "source": "TRAP", "trap_oid": ".1.3.6.1.4.1.8072.2.3.0.1" } ] ---- 6) Formula conventions & reference rewrites ------------------------------------------- 6.1 Collection object references in formulas ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Canonical runtime references are: - ``o_`` Example: .. code-block:: text (o_123) * 100 6.2 Referencing newly-created objects in the same request ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Because new collection objects do not yet have IDs, you can use your own ``reference`` label as a placeholder and the system rewrites it after insert. Recommended pattern: .. code-block:: text (cpu1) * 100 Where the collection object was created with: .. code-block:: json { "reference": "cpu1", "name": "CPU", "class_type": "PERFORMANCE_GAUGE" } The service rewrites ``cpu1`` to ``o_`` automatically during processing once an ID is assigned. .. note:: **Recommendation:** Always wrap entity references in formulas with parentheses: ``(cpu1)``. ---- 7) Application type constraints ------------------------------- 7.1 Allowed DA types ^^^^^^^^^^^^^^^^^^^^ Only Snippet Framework application types are supported: - ``SNIPPET_PERFORMANCE`` - ``SNIPPET_CONFIGURATION`` - ``BULK_SNIPPET_PERFORMANCE`` - ``BULK_SNIPPET_CONFIGURATION`` 7.2 Snippet Framework App Type toggle (``is_sf_app_type``) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - If ``is_sf_app_type == TRUE``: ``type`` must be **SNIPPET_PERFORMANCE** or **SNIPPET_CONFIGURATION** - If ``is_sf_app_type == FALSE``: ``type`` must be one of the allowed SF types listed above 7.3 Performance vs configuration object classes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If the DA is **performance**: - Any unspecified ``class_type`` for a collection object is auto-set to ``PERFORMANCE_COUNTER`` - Any non-allowed ``class_type`` raises a validation error - Allowed ``class_type`` values: - ``PERFORMANCE_COUNTER`` - ``PERFORMANCE_PERCENT`` - ``PERFORMANCE_KILOBYTE`` - ``PERFORMANCE_GAUGE`` - ``DISCOVERY`` - ``LABEL_HOURLY_POLLED`` - ``LABEL_ALWAYS_POLLED`` - ``INDEX`` - ``LABEL_IP_ALWAYS_POLLED`` If the DA is **configuration**: - Any unspecified ``class_type`` for a collection object is auto-set to ``CONFIG_CHARACTER`` - Any non-allowed ``class_type`` raises a validation error - Allowed ``class_type`` values: - ``CONFIG_CHARACTER`` - ``CONFIG_ENUM`` - ``CONFIG_TIMETICKS`` - ``CONFIG_GAUGE`` - ``CONFIG_NUMERIC`` - ``CONFIG_TIMESTAMP`` - ``CONFIG_MAC_ADDRESS`` - ``CONFIG_IP_ADDRESS`` - ``CONFIG_DATETIME`` - ``DISCOVERY`` - ``LABEL_HOURLY_POLLED`` - ``LABEL_ALWAYS_POLLED`` - ``INDEX`` - ``INDEX_LABEL`` - ``LABEL_CONFIG_GROUP`` ---- 8) Collection Object field legality (exact behavior) ---------------------------------------------------- Collection objects have *three* "gating systems": 1. **Performance vs Configuration Application Type** 2. **Discovery Class Type** 3. **Enum Class Type** 8.1 Always-allowed fields (apply everywhere) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following fields are always available for each collection object: - ``guid`` *(immutable)* - ``name`` *(required on create)* - ``reference`` - ``class_type`` - ``snippet_id`` - ``snippet_reference`` - ``snippet_argument`` 8.2 Discovery object rules (``class_type = DISCOVERY``) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Discovery-allowed fields: - ``tabular`` - ``alignment_condition`` If ``alignment_condition == IF_OID_PRESENT``, then the following fields are also allowed: - ``validity_check_pattern`` - ``validity_check_operator`` 8.3 Enum object rules (``class_type = CONFIG_ENUM``) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Enum-allowed fields: - ``string_type`` - ``group`` - ``usage_type`` - ``change_alerting`` - ``table_alignment`` - ``hide_object`` - ``disable_maintenance`` - ``description`` - ``enum_values`` - ``formula`` 8.4 Performance-only vs configuration-only fields ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Configuration-allowed fields: - ``string_type`` - ``group`` - ``usage_type`` - ``asset_link`` - ``asset_link_precedence`` - ``change_alerting`` - ``table_alignment`` - ``hide_object`` - ``disable_maintenance`` - ``description`` - ``component_identifiers`` - ``formula`` PERFORMANCE_ONLY fields: - ``group`` - ``usage_type`` - ``enable_deviation_alerting`` - ``min_weeks_data`` - ``max_weeks_data`` - ``disable_maintenance`` ---- 9) Entity schemas ----------------- 9.1 Dynamic Application (``dynamic_app``) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Required on create: - ``name`` (string, 1–64) Optional: - ``guid`` (GUID) *(required for existing Dynamic Applications)* - ``pp_guid`` (GUID; optional - can be null if no aligned PowerPack) - ``is_sf_app_type`` (BooleanToggle, default ``FALSE``) - ``abandon_collection_limit`` (int optional; coerces; default 0; ≥0) - ``max_devices`` (int; default 50; ≥1; plus extra guard: if not SF app type, must be ≤500) - ``version`` (float; default 1.0; ≥0.1) - ``state`` (EnabledToggle; default ENABLED) - ``poll_interval`` (PollInterval; default EVERY_15_MINUTES) - ``cu_affinity`` (CUAffinity; default ASSIGNED_COLLECTOR) - ``execution_environment`` (ExecutionEnvironment GUID or the default, ``"sl1_default_ee"``) - ``component_mapping`` (EnabledToggle; default DISABLED) - ``description`` (string) - ``disable_rollup_of_data`` (BooleanToggle; default FALSE) - ``release_notes`` (string) - ``null_row_option`` (MissingTableDataOption) - ``null_column_option`` (MissingTableDataOption) - ``type`` (ApplicationType, default ``SNIPPET_CONFIGURATION``; If guid is provided (update), the service derives type from the database and ignores any supplied value) - ``component_mapping_dynamic_applications`` (array of GUIDs or DA references; only include when component_mapping = EnabledToggle.ENABLED) - ``collection_objects`` (array of CollectionObject) - ``snippets`` (array of Snippet) - ``presentation_objects`` (array of PresentationObject; optional - include only if you want to manually define presentation objects and disable auto-generation) - ``threshold_objects`` (array of ThresholdObject) - ``alert_objects`` (array of AlertObject) - ``event_policies`` (array of EventPolicy) 9.2 Snippet (``snippets[]``) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Required on create: - ``name`` (string, 1–64) Optional: - ``guid`` (GUID; immutable) - ``reference`` (string) - ``snippet`` (string; python code) - ``state`` (EnabledToggle; default ENABLED) - ``required`` (RequiredToggle; default REQUIRED) 9.3 Collection Object (``collection_objects[]``) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Required on create: - ``name`` (string, 1–64) Shared fields *(Allowed for all types)*: - ``guid`` (GUID; immutable) - ``reference`` (string) - ``class_type`` (CollectionObjectClass) - ``snippet_id`` (int; default 0) - ``snippet_reference`` (string) - auto-set to ``snip_`` if omitted and ``snippet_id != 0`` - ``snippet_argument`` (string) Config-only: - ``string_type`` (ConfigStringType) - ``group`` (0–50) - ``usage_type`` (CollectionObjectUsage) - ``asset_link`` (AssetLink) - ``asset_link_precedence`` (0..100 and must be increment of 10) - ``change_alerting`` (EnabledToggle) - ``table_alignment`` (TableAlignment) - ``hide_object`` (BooleanToggle) - ``disable_maintenance`` (BooleanToggle) - ``description`` (string) - ``component_identifiers`` (array of ComponentIdentifier) *(must be unique within the list; also globally unique across objects when component_mapping = EnabledToggle.ENABLED)* - ``formula`` (string; max 512) Performance-only: - ``group`` (0–50) - ``usage_type`` (CollectionObjectUsage) - ``enable_deviation_alerting`` (BooleanToggle) - ``min_weeks_data`` (int ≥0) - ``max_weeks_data`` (int ≥0) - ``disable_maintenance`` (BooleanToggle) Discovery-only: - ``tabular`` (EnabledToggle) - ``alignment_condition`` (DiscoveryAlignmentCondition) - ``validity_check_pattern`` (string max 128) *(only when alignment_condition is IF_OID_PRESENT)* - ``validity_check_operator`` (DiscoveryOperator) *(only when alignment_condition is IF_OID_PRESENT)* Enum-only: - ``string_type`` (ConfigStringType) - ``group`` (0–50) - ``usage_type`` (CollectionObjectUsage) - ``change_alerting`` (EnabledToggle) - ``table_alignment`` (TableAlignment) - ``hide_object`` (BooleanToggle) - ``disable_maintenance`` (BooleanToggle) - ``description`` (string) - ``enum_values`` (string) - ``formula`` (string; max 512) 9.4 Presentation Object (``presentation_objects[]``) — performance apps only ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Required on create: - ``name`` (string, 1–42) Optional: - ``guid`` (GUID; immutable) - ``reference`` (string) - ``guide_text`` (string max 2048) - ``formula`` (string max 512; default ``"()"``) - ``show_as_percent`` (BooleanToggle; default FALSE) - ``summarization_state`` (BooleanToggle; default FALSE) - ``abbreviation_suffix`` (string max 16) - ``data_unit`` (string max 25) 9.5 Threshold Object (``threshold_objects[]``) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Required on create: - ``name`` (string, 1–64) Optional fields (with defaults/constraints): - ``guid`` (GUID; immutable) - ``reference`` (string) - ``override_threshold_value`` (BooleanToggle; default TRUE) - ``numeric_range_high`` (float ≥0; default 100.0) - ``numeric_range_low`` (float ≥0; default 0.0) - ``type`` (ThresholdType; default PERCENTAGE) - ``unit`` (string nullable; max 25) - ``value`` (float ≥0; default 90.0) 9.6 Alert Object (``alert_objects[]``) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Required on create: - ``name`` (string, 1–128) - ``formula`` (string, 1–512) - ``log_message`` (string, 1–128) Optional: - ``guid`` (GUID; immutable) - ``reference`` (string) - ``state`` (EnabledToggle; default DISABLED) - ``maintain_state`` (EnabledToggle; default DISABLED) - ``triggered_alert_id`` (int; default 0) - ``triggered_alert_reference`` (string) - auto-set to ``a_`` if omitted and ``triggered_alert_id != 0`` 9.7 Event Policy (``event_policies[]`` or ``POST /lce/api/event_policies``) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Required on create: - ``name`` (string, 1–128) - ``message`` (string, 1–255) Optional: - ``guid`` (GUID; immutable) - ``reference`` (string) - ``pp_guid`` (GUID) - ``source`` (EventSource; default ``DYNAMIC``) - ``state`` (EnabledToggle; default ENABLED) - ``severity`` (EventSeverity; default MAJOR) - ``use_severity_modifier`` (BooleanToggle; default FALSE) - ``description`` (string) - ``occurrence_count`` (int 0–1000; default 0) - ``occurrence_time`` (EventTime; default DISABLED) - ``expiry_delay`` (EventTime; default DISABLED) - ``detection_weight`` (int 0–20; default 0) - ``component_type`` (EventComponentType) - ``external_event_id`` (nullable integer) - ``external_category`` (string max 255) - ``topology_suppression`` (EventTopologySuppression) - ``match_logic`` (EventMatchLogic) - ``use_multi_match`` (BooleanToggle) - ``use_message_match`` (BooleanToggle) - ``first_match_string`` (string max 512) - ``second_match_string`` (string max 512) - ``identifier_pattern`` (string max 512) - ``override_identifier_type`` (EventYType) - ``identifier_format`` (string max 128) - ``auto_clear_events`` (array of event policy GUIDs) Syslog-only fields: - ``syslog_facility`` (EventSyslogFacility) - ``syslog_severity`` (EventSyslogSeverity) - ``syslog_application_name`` (nullable string max 48) - ``syslog_process_id`` (nullable string max 128) - ``syslog_message_id`` (nullable string max 32) Trap-only fields: - ``source_host_oid`` (nullable string max 255) - ``trap_oid`` (nullable string max 255) Dynamic/Internal/Agent linkage fields: - ``link_id`` (int; default 0) - ``link_reference`` (string; only for linking to newly-created entities in request scope) Dynamic-only fields in nested DA context: - ``app_id`` and ``app_guid`` are meaningful for model/update contexts but are omitted when an Event Policy is returned nested under a Dynamic Application response. Event Policy source-specific rules """""""""""""""""""""""""""""""""" - If ``source = SYSLOG``: - syslog-only fields are legal - ``first_match_string`` is required - If ``source = TRAP``: - ``trap_oid`` is required - If ``source = DYNAMIC``: - link to an alert using either ``link_id`` or ``link_reference`` - If ``source = INTERNAL``: - ``link_id`` is required - If ``source = API`` or ``source = EMAIL``: - ``first_match_string`` is required Threshold-pair rule """"""""""""""""""" ``occurrence_count`` and ``occurrence_time`` must be configured together: - if one is set, the other must also be set - if one is disabled/unset, the other must also be disabled/unset - when updating an existing Event Policy with only one of the two fields, the other is taken from its stored value ---- 10) Cross-object validations ---------------------------- 10.1 GUID uniqueness across the entire payload ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ All ``guid`` values must be unique across all entities (dynamic app, snippets, collection objects, event policies, etc.) 10.2 Reference uniqueness across the entire payload ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ All ``reference`` values must be unique across all entities (dynamic app, snippets, collection objects, event policies, etc.) 10.3 Component identifier uniqueness (when component_mapping enabled) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If ``dynamic_app.component_mapping`` is EnabledToggle.ENABLED: - Each ``CollectionObject.component_identifiers`` must be unique within that object - No identifier may be used by more than one collection object of the DA, including collection objects not included in the payload. Duplicates that are already stored reject every update of the DA until the request removes them. ---- 11) Examples ------------ 11.1 Create performance app with a new collection object and explicit presentation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: json { "name": "CPU Monitoring", "type": "SNIPPET_PERFORMANCE", "is_sf_app_type": "FALSE", "collection_objects": [ { "reference": "cpu1", "name": "CPU Usage", "class_type": "PERFORMANCE_GAUGE" } ], "presentation_objects": [ { "reference": "cpu_pres", "name": "CPU Chart", "formula": "(cpu1) * 100.0", "show_as_percent": "TRUE", "data_unit": "%" } ] } 11.2 Config enum object ^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: json { "name": "Interface Admin Status", "collection_objects": [ { "name": "ifAdminStatus", "class_type": "CONFIG_ENUM", "enum_values": "1=up,2=down,3=testing", "table_alignment": "LEFT" } ] } 11.3 Discovery object with OID-present ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: json { "name": "Discovery Example", "collection_objects": [ { "name": "Discovery Object", "class_type": "DISCOVERY", "alignment_condition": "IF_OID_PRESENT", "tabular": "DISABLED", "validity_check_pattern": "ignored", "validity_check_operator": "MATCHES_REGEX" } ] } 11.4 Adding New Threshold object to Existing Dynamic Application (retrieve=TRUE) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ POST Body """"""""" .. code-block:: json { "guid": "FD4DEEBD49925BEB6F04BE4DBFC8661A", "threshold_objects": [ { "reference": "t_cpu", "name": "CPU High", "type": "PERCENTAGE", "value": 85, "unit": "%", "numeric_range_low": 0, "numeric_range_high": 100 } ] } Response """""""" .. code-block:: json { "entities": [ { "abandon_collection_limit": 0, "alert_objects": [], "collection_objects": [], "component_mapping": "DISABLED", "cu_affinity": "ASSIGNED_COLLECTOR", "description": "", "disable_rollup_of_data": "FALSE", "event_policies": [], "execution_environment": "sl1_default_ee", "guid": "FD4DEEBD49925BEB6F04BE4DBFC8661A", "id": 1134, "is_sf_app_type": "FALSE", "max_devices": 50, "name": "Postman - Minimal", "null_column_option": "DASH_VALUES", "null_row_option": "DASH_VALUES", "poll_interval": "EVERY_15_MINUTES", "pp_guid": null, "reference": "FD4DEEBD49925BEB6F04BE4DBFC8661A", "release_notes": "", "snippets": [], "state": "ENABLED", "threshold_objects": [ { "guid": "AB92071ECAC73541262265EF5A3E77E7", "id": 414, "name": "CPU High", "numeric_range_high": 100.0, "numeric_range_low": 0.0, "override_threshold_value": "TRUE", "reference": "t_414", "type": "PERCENTAGE", "unit": "%", "value": 85.0 } ], "type": "SNIPPET_CONFIGURATION", "version": 1.0 } ], "results": [ { "alert_objects": [], "collection_objects": [], "dynamic_app": { "guid": "FD4DEEBD49925BEB6F04BE4DBFC8661A", "id": 1134, "name": "Postman - Minimal", "new": false, "reference": "FD4DEEBD49925BEB6F04BE4DBFC8661A" }, "event_policies": [], "presentation_objects": [], "snippets": [], "threshold_objects": [ { "guid": "AB92071ECAC73541262265EF5A3E77E7", "id": 414, "name": "CPU High", "new": true, "reference": "t_cpu" } ] } ], "success": true } 11.5 Standard GET Response ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: json { "abandon_collection_limit": 0, "alert_objects": [ { "formula": "(o_3351) > 1", "guid": "EE77BEC839E4059E95558C192F2B6D0D", "id": 818, "log_message": "Too many emails", "maintain_state": "DISABLED", "name": "Email", "reference": "a_818", "state": "DISABLED", "triggered_alert_id": 0 }, { "formula": "o_3350 > t_280", "guid": "BA86C7EC7B8462E2876D8D1DED2628AB", "id": 819, "log_message": "Too many tickets", "maintain_state": "DISABLED", "name": "Aligned Ticket", "reference": "a_819", "state": "DISABLED", "triggered_alert_id": 0 } ], "collection_objects": [ { "class_type": "PERFORMANCE_GAUGE", "description": "Random number based on aligned_ticket_queues size. The snippet argument uses substitution. For Example: \"$silo_comp_uid\" will be replaced by \"/api/account/2\"", "disable_maintenance": "FALSE", "enable_deviation_alerting": "FALSE", "formula": "", "group": 0, "guid": "70295D279EE9004DADA522E92604D8F5", "id": 3350, "max_weeks_data": 0, "min_weeks_data": 0, "name": "Based on Aligned Ticket Queues", "reference": "o_3350", "snippet_argument": "low_code:\r\n version: 2\r\n steps:\r\n - http:\r\n uri: \"$silo_comp_uid\"\r\n - json\r\n - random_generator: \"aligned_ticket_queues\"", "snippet_id": 332, "snippet_reference": "snip_332", "usage_type": "STANDARD" }, { "class_type": "PERFORMANCE_GAUGE", "description": "Random number based on email string length.The snippet argument uses substitution. For Example: \"$silo_comp_uid\" will be replaced by \"/api/account/2\"", "disable_maintenance": "FALSE", "enable_deviation_alerting": "FALSE", "formula": "", "group": 0, "guid": "71F6C83B432DA0C32FF7A4CA8D10CC3F", "id": 3351, "max_weeks_data": 0, "min_weeks_data": 0, "name": "Based on Email", "reference": "o_3351", "snippet_argument": "low_code:\r\n version: 2\r\n steps:\r\n - http:\r\n uri: \"$silo_comp_uid\"\r\n - json\r\n - random_generator: \"email\"", "snippet_id": 332, "snippet_reference": "snip_332", "usage_type": "STANDARD" } ], "component_mapping": "DISABLED", "cu_affinity": "ASSIGNED_COLLECTOR", "description": "This Dynamic Application simulates performance data for each account.\r\n\r\nNotes:\r\nIn this Dynamic Application, a custom Step is defined, which is registered to generate a random number based on the previous result and action argument for the Collection Objects. Any custom Step registered via snippet code must be used in a Collection Object.", "disable_rollup_of_data": "FALSE", "event_policies": [], "execution_environment": "1BC13B3B88AAFB5399B94FEEE33EB48A", "guid": "96AA113228DCF8E1396C45DFE2EAB9C0", "id": 317, "is_sf_app_type": "FALSE", "max_devices": 50, "name": "Account Performance", "null_column_option": "DASH_VALUES", "null_row_option": "DASH_VALUES", "poll_interval": "EVERY_5_MINUTES", "pp_guid": "6450441E71B0EB1933D18A6C6252CF28", "presentation_objects": [ { "abbreviation_suffix": "", "data_unit": "Rows", "formula": "(o_3350)", "guid": "4808E1AC211DAB3029740B077295B0A8", "guide_text": "This is a guide text", "id": 1000, "name": "Based on Aligned Ticket Queues", "reference": "pres_1000", "show_as_percent": "FALSE", "summarization_state": "TRUE" }, { "abbreviation_suffix": "", "data_unit": "Rows", "formula": "(o_3351)", "guid": "240C671DF192FBADDC0B94EECA4CF2EE", "guide_text": "This is a guide text", "id": 1001, "name": "Based on Email", "reference": "pres_1001", "show_as_percent": "FALSE", "summarization_state": "TRUE" }, { "abbreviation_suffix": "", "data_unit": "Emails", "formula": "(o_3351) + 1", "guid": "7BA723660C5E9DF1C86968350B3EAD2F", "guide_text": "", "id": 2367, "name": "Test", "reference": "pres_2367", "show_as_percent": "FALSE", "summarization_state": "FALSE" } ], "reference": "96AA113228DCF8E1396C45DFE2EAB9C0", "release_notes": "Version 2.0
Updated the Execution Environment to Low-code Tools v100

Version 1.1
Updated to REST: Toolkit 101 Execution Environment and removed id fields from snippet arguments.

Version 1.0
Dynamic Application that uses available Steps from the low_code library and includes one custom Step.
  • low_code
  • http
  • json
  • random_generator (custom Step)

Copyright (c) 2003-2024 ScienceLogic, Inc.

This software is the copyrighted work of ScienceLogic, Inc.
Use of the Software is governed by the terms of the software license
agreement, which accompanies or is included with the Software
(\"License Agreement\"). An end user is not permitted to install any Software
that is accompanied by or includes a License Agreement, unless he or she
first agrees to the License Agreement terms.
The Software is made available solely for use by end users according to the
License Agreement. Any reproduction or redistribution of the Software not in
accordance with the License Agreement is expressly prohibited by law, and may
result in severe civil and criminal penalties. Violators will be prosecuted
to the maximum extent possible.

WITHOUT LIMITING THE FOREGOING, COPYING OR REPRODUCTION OF THE SOFTWARE TO
ANY OTHER SERVER OR LOCATION FOR FURTHER REPRODUCTION OR REDISTRIBUTION IS
EXPRESSLY PROHIBITED.

THE SOFTWARE IS WARRANTED, IF AT ALL, ONLY ACCORDING TO THE TERMS OF THE
LICENSE AGREEMENT. EXCEPT AS WARRANTED IN THE LICENSE AGREEMENT,
SCIENCELOGIC, INC. HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS WITH REGARD
TO THE SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES AND CONDITIONS OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT.
", "snippets": [ { "guid": "02C935554551CA07CC790888DB819AAF", "id": 332, "name": "Custom Step Performance", "reference": "snip_332", "required": "REQUIRED", "snippet": "from silo.apps.errors import error_manager\r\nwith error_manager(self):\r\n\r\n from silo.low_code import *\r\n from silo.apps.collection import create_collections, save_collections\r\n\r\n # =====================================\r\n # =========== User Editable ===========\r\n # =====================================\r\n import random\r\n \r\n @register_processor\r\n def random_generator(result, action_arg):\r\n \"\"\"Generates random number between 0 and action_arg value size.\r\n\r\n :param object result: Result from the parser\r\n :param int action_arg: Action argument for the phase.\r\n\r\n :return: Random number between 0 and action_arg value size\r\n :rtype: Integer\r\n \"\"\"\r\n attribute_leng = len(result[action_arg])\r\n generated_number = random.randint(0, attribute_leng)\r\n return generated_number\r\n\r\n \r\n # List any custom substitutions that need to occur within the snippet arguments\r\n custom_substitution = {}\r\n # =====================================\r\n # ========= End User Editable =========\r\n # =====================================\r\n\r\n\r\n collections = create_collections(self)\r\n snippet_framework(collections, custom_substitution, snippet_id, app=self)\r\n save_collections(collections, self)", "state": "ENABLED" } ], "state": "ENABLED", "threshold_objects": [ { "guid": "5C08106971B4DB6E96A7B5290DD665C5", "id": 280, "name": "Test Threshold", "numeric_range_high": 100.0, "numeric_range_low": 0.0, "override_threshold_value": "TRUE", "reference": "t_280", "type": "INTEGER", "unit": "KB/s", "value": 90.0 } ], "type": "SNIPPET_PERFORMANCE", "version": 2.0 } 11.6 Creating a Minimal Dynamic Application (retrieve=TRUE) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ POST Body """"""""" .. code-block:: json { "name": "Minimal" } Response """""""" .. code-block:: json { "entities": [ { "abandon_collection_limit": 0, "alert_objects": [], "collection_objects": [], "component_mapping": "DISABLED", "cu_affinity": "ASSIGNED_COLLECTOR", "description": "", "disable_rollup_of_data": "FALSE", "event_policies": [], "execution_environment": "sl1_default_ee", "guid": "FD4DEEBD49925BEB6F04BE4DBFC8661A", "id": 1134, "is_sf_app_type": "FALSE", "max_devices": 50, "name": "Minimal", "null_column_option": "DASH_VALUES", "null_row_option": "DASH_VALUES", "poll_interval": "EVERY_15_MINUTES", "pp_guid": null, "reference": "FD4DEEBD49925BEB6F04BE4DBFC8661A", "release_notes": "", "snippets": [], "state": "ENABLED", "threshold_objects": [], "type": "SNIPPET_CONFIGURATION", "version": 1.0 } ], "results": [ { "alert_objects": [], "collection_objects": [], "dynamic_app": { "guid": "FD4DEEBD49925BEB6F04BE4DBFC8661A", "id": 1134, "name": "Minimal", "new": true }, "event_policies": [], "presentation_objects": [], "snippets": [], "threshold_objects": [] } ], "success": true } 11.7 Multiple Dynamic Applications with References (retrieve=TRUE) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ POST Body """"""""" .. code-block:: json [ { "abandon_collection_limit": 0, "alert_objects": [], "collection_objects": [ { "asset_link": "NONE", "asset_link_precedence": 50, "change_alerting": "DISABLED", "class_type": "CONFIG_CHARACTER", "component_identifiers": ["DEVICE_NAME"], "description": "Account description.", "disable_maintenance": "FALSE", "formula": "", "group": 1, "hide_object": "FALSE", "name": "Account", "snippet_argument": "low_code:\r\n version: 2\r\n steps:\r\n - http:\r\n uri: \"/account\"\r\n - json\r\n - jmespath:\r\n index: true\r\n value: \"result_set[*].{_index: URI, _value: description}\"", "string_type": "STANDARD", "table_alignment": "LEFT", "usage_type": "STANDARD" }, { "component_identifiers": ["UNIQUE_IDENTIFIER", "UUID"], "description": "Account identifier.", "disable_maintenance": "FALSE", "formula": "", "group": 1, "hide_object": "FALSE", "name": "Id", "snippet_argument": "low_code:\r\n version: 2\r\n steps:\r\n - http:\r\n uri: \"/account\"\r\n - json\r\n - jmespath:\r\n index: true\r\n value: \"result_set[*].{_index: URI, _value: URI}\"", "string_type": "STANDARD", "table_alignment": "LEFT", "usage_type": "STANDARD" }, { "alignment_condition": "IF_OID_PRESENT", "class_type": "DISCOVERY", "name": "Discovery Object", "snippet_argument": "", "tabular": "DISABLED", "validity_check_operator": "IS_EQUAL_TO_RESULT", "validity_check_pattern": "true" } ], "component_mapping": "ENABLED", "component_mapping_dynamic_applications": [ "96AA113228DCF8E1396C45DFE2EAB9C0", "136FECC9018400DA709E4A70777DA517" ], "cu_affinity": "ASSIGNED_COLLECTOR", "description": "This Dynamic Application retrieves data from 'api/account' and creates a component device for each account.", "event_policies": [], "execution_environment": "1BC13B3B88AAFB5399B94FEEE33EB48A", "name": "Test Discovery", "type": "SNIPPET_CONFIGURATION" }, { "abandon_collection_limit": 0, "alert_objects": [ { "formula": "(o_3351) > 1", "log_message": "Too many emails", "maintain_state": "DISABLED", "name": "Email", "reference": "a_818", "state": "DISABLED", "triggered_alert_id": 0 }, { "formula": "o_3350 > t_280", "log_message": "Too many tickets", "maintain_state": "DISABLED", "name": "Aligned Ticket", "reference": "a_819", "state": "DISABLED" } ], "collection_objects": [ { "class_type": "PERFORMANCE_GAUGE", "description": "Random number based on aligned_ticket_queues size. The snippet argument uses substitution. For Example: \"$silo_comp_uid\" will be replaced by \"/api/account/2\"", "disable_maintenance": "FALSE", "enable_deviation_alerting": "FALSE", "formula": "", "group": 0, "max_weeks_data": 0, "min_weeks_data": 0, "name": "Based on Aligned Ticket Queues", "reference": "o_3350", "snippet_argument": "low_code:\r\n version: 2\r\n steps:\r\n - http:\r\n uri: \"$silo_comp_uid\"\r\n - json\r\n - random_generator: \"aligned_ticket_queues\"", "snippet_reference": "snip_332", "usage_type": "STANDARD" }, { "class_type": "PERFORMANCE_GAUGE", "description": "Random number based on email string length.The snippet argument uses substitution. For Example: \"$silo_comp_uid\" will be replaced by \"/api/account/2\"", "name": "Based on Email", "reference": "o_3351", "snippet_argument": "low_code:\r\n version: 2\r\n steps:\r\n - http:\r\n uri: \"$silo_comp_uid\"\r\n - json\r\n - random_generator: \"email\"", "snippet_reference": "snip_332" } ], "cu_affinity": "ASSIGNED_COLLECTOR", "description": "This Dynamic Application simulates performance data for each account.\r\n\r\nNotes:\r\nIn this Dynamic Application, a custom Step is defined, which is registered to generate a random number based on the previous result and action argument for the Collection Objects. Any custom Step registered via snippet code must be used in a Collection Object.", "event_policies": [], "name": "Test Performance", "poll_interval": "EVERY_5_MINUTES", "presentation_objects": [ { "abbreviation_suffix": "", "data_unit": "Rows", "formula": "(o_3350)", "guide_text": "This is a guide text", "name": "Based on Aligned Ticket Queues", "show_as_percent": "FALSE", "summarization_state": "TRUE" }, { "data_unit": "Rows", "formula": "(o_3351)", "guide_text": "This is a guide text", "name": "Based on Email", "show_as_percent": "FALSE", "summarization_state": "TRUE" }, { "data_unit": "Emails", "formula": "(o_3351) + 1", "name": "Test" } ], "reference": "96AA113228DCF8E1396C45DFE2EAB9C0", "snippets": [ { "name": "Custom Step Performance", "snippet": "from silo.apps.errors import error_manager\r\nwith error_manager(self):\r\n\r\n from silo.low_code import *\r\n from silo.apps.collection import create_collections, save_collections\r\n\r\n # =====================================\r\n # =========== User Editable ===========\r\n # =====================================\r\n import random\r\n \r\n @register_processor\r\n def random_generator(result, action_arg):\r\n \"\"\"Generates random number between 0 and action_arg value size.\r\n\r\n :param object result: Result from the parser\r\n :param int action_arg: Action argument for the phase.\r\n\r\n :return: Random number between 0 and action_arg value size\r\n :rtype: Integer\r\n \"\"\"\r\n attribute_leng = len(result[action_arg])\r\n generated_number = random.randint(0, attribute_leng)\r\n return generated_number\r\n\r\n \r\n # List any custom substitutions that need to occur within the snippet arguments\r\n custom_substitution = {}\r\n # =====================================\r\n # ========= End User Editable =========\r\n # =====================================\r\n\r\n\r\n collections = create_collections(self)\r\n snippet_framework(collections, custom_substitution, snippet_id, app=self)\r\n save_collections(collections, self)", "reference": "snip_332" } ], "threshold_objects": [ { "name": "Test Threshold", "numeric_range_high": 100.0, "numeric_range_low": 0.0, "override_threshold_value": "TRUE", "reference": "t_280", "type": "INTEGER", "unit": "KB/s", "value": 90.0 } ], "type": "SNIPPET_PERFORMANCE" }, { "alert_objects": [ { "name": "Unfriendly user", "formula": "(o_3355) != 'friend'", "log_message": "Bad friend!" }, { "name": "Test Alert", "formula": "(thresh_1) > 1", "log_message": "Log Message", "reference": "alert_1", "maintain_state": "ENABLED" }, { "name": "Test Alert 2", "formula": "(o_3355) + thresh_1 + (o_3357) + (o_3355)", "log_message": "Log Message", "triggered_alert_reference": "alert_1" } ], "collection_objects": [ { "description": "First name of the account. The snippet argument uses substitution. For Example: \"$silo_comp_uid\" will be replaced by \"/api/account/2\".", "group": 1, "name": "Contact First Name", "reference": "o_3355", "snippet_argument": "low_code:\r\n version: 2\r\n steps:\r\n - http:\r\n uri: \"$silo_comp_uid\"\r\n - json\r\n - simple_key: \"contact_fname\"\r\n - test_step" }, { "description": "Phone of the account. The snippet argument uses substitution. For Example: \"$silo_comp_uid\" will be replaced by \"/api/account/2\".", "group": 2, "name": "Phone", "reference": "o_3357", "snippet_argument": "low_code:\r\n version: 2\r\n steps:\r\n - http:\r\n uri: \"$silo_comp_uid\"\r\n - json\r\n - simple_key: \"phone\"" } ], "cu_affinity": "ROOT_DEVICE", "event_policies": [], "execution_environment": "1BC13B3B88AAFB5399B94FEEE33EB48A", "name": "Test Configuration", "reference": "136FECC9018400DA709E4A70777DA517", "threshold_objects": [ { "name": "Test Threshold Object", "reference": "thresh_1" } ] } ] Response """""""" .. code-block:: json { "entities": [ ... ], "results": [ ... ], "success": true } 11.8 Create Event Policies ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: json [ { "name": "Interface Down", "message": "Interface is down", "source": "SYSLOG", "first_match_string": "Interface down", "severity": "MAJOR" }, { "name": "Trap Example", "message": "Trap received", "source": "TRAP", "trap_oid": ".1.3.6.1.4.1.8072.2.3.0.1" } ] 11.9 Event Policy linked to new alert in a Dynamic Application payload ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: json { "guid": "136FECC9018400DA709E4A70777DA517", "name": "Performance App", "type": "SNIPPET_PERFORMANCE", "alert_objects": [ { "reference": "alert_high_cpu", "name": "CPU High Alert", "formula": "(o_5463) > 90", "log_message": "CPU high" } ], "event_policies": [ { "name": "CPU High Event", "message": "CPU event raised", "source": "DYNAMIC", "link_reference": "alert_high_cpu" } ] } ---- 12) Special behaviors --------------------- 12.1 Default snippet auto-creation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If updating or creating collection objects in a Dynamic Application that has **no snippets**, the service creates the Snippet Framework **Default Snippet** and assigns it to any collection object without a valid snippet reference. 12.2 Snippet alignment for collection objects ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - If ``snippet_id`` is default/unset -> assigned to a fallback snippet (first active snippet) - If ``snippet_id`` references a snippet not owned by the application -> validation error 12.3 Presentation auto-generation (performance apps only) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If ``presentation_objects`` is **empty** (or omitted) and the app is performance: - Create presentation objects for newly created collection objects with ``class_type <= PERFORMANCE_GAUGE`` - Auto formula is: ``(o_)`` If **any** presentation objects are provided in the request: - **No auto-generation** occurs 12.4 Derived collection object fields ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Discovery collection objects enforce: - ``name = "Discovery Object"`` - ``group = 0`` - ``alignment_condition = IF_OID_NOT_PRESENT`` sets ``validity_check_operator = NO_VALIDITY_CHECK`` and ``validity_check_pattern = ""``; the validity check fields cannot be sent together with ``alignment_condition = IF_OID_NOT_PRESENT`` - sending a validity check field without ``alignment_condition`` implies ``alignment_condition = IF_OID_PRESENT`` - ``validity_check_operator = NO_VALIDITY_CHECK`` is how ``IF_OID_NOT_PRESENT`` is stored, so sending it switches the object to ``alignment_condition = IF_OID_NOT_PRESENT`` (and ``validity_check_pattern = ""``); sending it together with ``alignment_condition = IF_OID_PRESENT`` is rejected (HTTP 422) - ``alignment_condition = IF_OID_PRESENT`` requires a validity check operator, so a stored ``validity_check_operator = NO_VALIDITY_CHECK`` (when switching from ``IF_OID_NOT_PRESENT`` without sending an operator) is set to ``IS_GREATER_THAN_RESULT`` 12.5 Group identity/relationship namespaces ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When ``usage_type`` is: - ``IDENTITY_NAMESPACE`` or ``RELATIONSHIP_NAMESPACE`` Then: - ``group`` must be set - a group index object must exist (first one in that group with indexing enabled) - duplicates are rejected These rules hold for every namespace collection object of the resulting Dynamic Application, including the stored ones that are not in the request (for example, removing the index of a group that stored namespaces use is rejected with ``Dynamic Application '' () [GUID=...]: Collection Object '' (o_) uses group , which has no index...``). Collection objects whose ``usage_type`` does not apply to them (e.g. discovery objects) are not checked. If invalid, the request is rejected (HTTP 422) and nothing is written. 12.6 Component mapping guardrails ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If the parent DA has ``component_mapping`` = EnabledToggle.DISABLED: - setting ``component_identifiers`` on collection objects is a validation error - setting a non-empty ``component_mapping_dynamic_applications`` is a validation error When EnabledToggle.ENABLED: - identifiers are diffed and synchronized (remove missing, add new) for collection objects that include ``component_identifiers``; an empty list removes all of the object's identifiers - collection objects that omit ``component_identifiers`` keep their existing identifiers - no identifier may be used by more than one collection object of the DA (see 10.3) 12.7 Event Policy nested-response behavior ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When Event Policies are returned nested under a Dynamic Application response: - ``app_id`` is omitted - ``app_guid`` is omitted These fields remain meaningful in broader Event Policy model/update contexts. 12.8 Behaviors Not Found in Schemas ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Cross-entity uniqueness across the entire payload - all guid unique across all entity types - all reference unique across all entity types 2. DB existence / ownership checks - guid exists when updating - snippet_id belongs to the same DA - triggered_alert_id points to an alert in same DA - link_id points to a valid target for the selected event source 3. Derived / rewritten fields - reference auto-defaulting (reference = guid) when guid present - canonical reference reassignments (``o_``, ``snip_``, etc.) - formula rewrites from ``(cpu1)`` -> ``(o_)`` 4. App-type feature toggles - is_sf_app_type gating rules (if TRUE then type must be SNIPPET_PERFORMANCE/SNIPPET_CONFIGURATION, etc.) 5. Group identity/relationship namespace rules - when usage_type in IDENTITY_NAMESPACE / RELATIONSHIP_NAMESPACE: - group must be set - a group index object must exist - duplicates rejected - checked for every namespace collection object of the resulting Dynamic Application (see 12.5); the request is rejected when not set correctly 6. Performance auto-generation rules - presentation auto-generation when omitted/empty - if any presentation objects are provided, none are auto-generated 7. Default snippet auto-creation logic - only when DA has no snippets and COs are created/updated and snippet refs missing/invalid 8. Event Policy source-specific business rules - exact source-dependent field legality - link target validation - first-match requirements for particular sources - serializer omission of context-specific fields ---- 13) Validation & error responses -------------------------------- Common status codes ^^^^^^^^^^^^^^^^^^^ - **400** Bad Request: invalid JSON, invalid identifiers, illegal field combinations, invalid filters - **401** Unauthorized: missing/invalid auth - **403** Forbidden: access hooks insufficient - **404** Not Found: referenced app/entity does not exist - **415** Unsupported Media Type: the request body is not sent as JSON - **422** Unprocessable Entity: schema/model validation failures, including missing required fields on create (e.g. ``name: Field required``) and text that cannot be stored (characters outside latin1) - **500** Internal Server Error: DB failures, unexpected errors Validation phases ^^^^^^^^^^^^^^^^^ - **Reads (GET) never fail because of stored data.** A stored value that fails validation (for example an empty ``name``, or an enum value that is not a member of the enum) is returned as is, and the entity it belongs to gets a ``validation_errors`` list describing each problem:: "validation_errors": [ {"field": "severity", "message": "Value error, 99 is not a valid EventSeverity"} ] - ``validation_errors`` is only present on entities with problems. It is always included, whatever ``fields`` and ``exclude`` specify (naming it in them has no effect). - ``field`` is the field with the invalid value. For list fields it includes the position of the invalid item (e.g. ``component_identifiers -> 2``); the whole list is then returned as stored. - ``validation_errors`` is read-only: it is ignored in requests, so a retrieved entity can be sent back to ``POST`` after fixing its values. - Rules between entities (unique GUIDs and references, formula references, linked entities, namespaces) are not validated by reads; updates report them. - The only stored data that cannot be read is a Dynamic Application whose stored application type (``type`` or ``is_sf_app_type``) is invalid or not a supported Snippet Framework type: ``GET /lce/api/dynamic_applications/`` returns HTTP 422, and the listings (``GET /lce/api/dynamic_applications`` and ``GET /lce/api/powerpacks/``) leave it out and report it in their ``errors`` list (``"Could not retrieve app with id: -> "``), so it never prevents other Dynamic Applications from being listed. - **Fields that do not apply to an entity are ignored.** A field does not apply when a request is not allowed to provide it, for example a configuration-only field of a Collection Object in a performance application, a field of an Event Policy that does not apply to its source, the validity check fields of a discovery object whose alignment condition is ``IF_OID_NOT_PRESENT``, ``component_identifiers`` when component mapping is disabled, or the Presentation Objects of a configuration application. Their stored values have no effect: they are not returned, not reported in ``validation_errors`` and not validated, and an update of the entity resets an invalid stored value to its default. Providing such a field is rejected (HTTP 422). - **Updates (POST) validate the complete result.** Before anything is written, every rule is validated against the complete resulting state: the stored values updated with the values of the request. For ``POST /lce/api/dynamic_applications`` this includes every stored child entity of the Dynamic Application, whether or not it is in the request. The request fails as a whole (nothing is written, HTTP 422) on the first violation, so an accepted update always leaves the Dynamic Application (or the Event Policies of ``POST /lce/api/event_policies``) fully valid. - **A stored problem rejects every update until it is fixed.** The error identifies the entity, the field and the stored value, and says how to fix it, for example:: The stored EventPolicy 'Aligned Ticket' [GUID=9441...] has invalid values: severity = 99: Value error, 99 is not a valid EventSeverity. Fix severity in the request to update it For a stored child entity that is not in the request, the entity is described as ``The stored '' [GUID=...] of Dynamic Application '' () [GUID=...]``. Fix the problem by providing the corrected values in the same request. Identifying fields (such as a ``guid``) cannot be changed through this API; the error then says the value must be fixed in Skylar One. Rules of the Dynamic Application itself name it in the error, e.g. ``Dynamic Application '' () [GUID=...]: The specified PowerPack GUID does not exist``. - **Checking stored entities without changing them:** use ``commit=false``, e.g. ``POST /lce/api/dynamic_applications?commit=false`` with ``{"guid": ""}`` reports the first problem of a Dynamic Application and all of its child entities, and ``POST /lce/api/event_policies?commit=false`` does the same for Event Policies. - Rules about the request itself apply to the fields you provide: providing a field that does not apply to the entity is rejected (see above). - The rules of each entity type are listed on its model's ``execute_strict_validation`` method. A few rules can only be checked while writing, as they depend on identifiers generated by the request (formula references, reference resolution, component alignment and events to clear); they also fail the whole request.