systemlink-cli 1.13.8__tar.gz → 1.13.9__tar.gz

{systemlink_cli-1.13.8 → systemlink_cli-1.13.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: systemlink-cli
-Version: 1.13.8
+Version: 1.13.9
 Summary: SystemLink Integrator CLI - cross-platform CLI for SystemLink workflows and templates.
 License-File: LICENSE
 Author: Fred Visser

{systemlink_cli-1.13.8 → systemlink_cli-1.13.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "systemlink-cli"
-version = "1.13.8"
+version = "1.13.9"
 description = "SystemLink Integrator CLI - cross-platform CLI for SystemLink workflows and templates."
 authors = ["Fred Visser <fred.visser@emerson.com>"]
 packages = [{ include = "slcli" }]

{systemlink_cli-1.13.8 → systemlink_cli-1.13.9}/slcli/_version.py

@@ -1,4 +1,4 @@
 """Version information for slcli."""
 
 # This file is auto-generated. Do not edit manually.
-__version__ = "1.13.8"
+__version__ = "1.13.9"

{systemlink_cli-1.13.8 → systemlink_cli-1.13.9}/slcli/skills/slcli/SKILL.md

@@ -164,6 +164,52 @@ slcli example install <EXAMPLE_ID> [--workspace NAME]    # Provision example res
 slcli example delete <EXAMPLE_ID> [--workspace NAME]     # Remove provisioned resources
 ```
 
+### routine — Routine management
+
+`slcli routine` spans two different services with different trigger payload shapes.
+Document the API version and trigger schema explicitly when generating commands.
+
+#### v1 notebook routines
+
+Use `--api-version v1` for notebook-execution routines. These map to the
+Routine Manager API and use `--type`, `--notebook-id`, plus either `--trigger`
+or `--schedule`.
+
+Notes for v1 triggers:
+
+- `trigger.filter` is required by the v1 API schema for triggered routines.
+- The only trigger `source` documented by the swagger is `FILES`.
+- The documented `events` values are `CREATED` and `UPDATED`.
+- The simplest documented filter is `extension=".xml"`, but observed live examples also combine `workspace = ...` and `name.Contains(...)` checks.
+- Treat the filter string as service-owned syntax, not LINQ or OData. Do not rewrite it as `--filter` CLI syntax.
+- When working with an existing v1 routine, prefer `slcli routine get --api-version v1 <ID>` because the default API version is v2.
+
+#### v2 event-action routines
+
+Use the default `v2` API for event-action routines. These map to the newer
+Routine Service and use `--event` plus `--actions`.
+
+For v2 routines, there is no top-level `filter` field in the create/update
+request. Filtering is event-type-specific and lives inside
+`event.triggers[].configuration`.
+
+Notes for v2 triggers:
+
+- `event.type` selects the event provider/plugin.
+- `event.triggers[]` contains one or more named conditions.
+- Each trigger's `configuration` object is provider-specific; the v2 swagger does not enumerate a universal set of filter keys.
+- Some v2 providers do use a `configuration.filter` field, but it is part of the provider-specific trigger configuration, not a top-level routine field.
+- Other v2 providers use structured condition fields such as `path`, `type`, `comparator`, `thresholds`, and `deadband` instead of a `filter` string.
+- Do not assume the v1 file-trigger filter string syntax applies to v2 routines.
+- When documenting v2 routines, show the exact JSON shape and note that valid configuration keys depend on the event type.
+- Live survey on the demo environment found these v2 event types in use: `TAG`, `TESTRESULTCHANGED`, and `WORKITEMCHANGED`.
+- Live survey on the demo environment found these v2 action types in use: `ALARM` and `NOTEBOOK`.
+- Observed TAG routines also use comparator-driven configurations such as `IN_RANGE`, `NOT_EQUAL`, and `GREATER_THAN_OR_EQUAL`.
+- Observed `TESTRESULTCHANGED` and `WORKITEMCHANGED` filters use provider-specific expression syntax such as nested field comparisons, `after.properties["key"]`, `DateTime.parse(...)`, `.Any(...)`, and `!Contains(...)`.
+- Common NOTEBOOK action fields in v2 are `notebookId`, `parameters`, `resourceProfile`, `priority`, and `serviceAccount`.
+- ALARM-producing routines need the clear/reset action that uses trigger `nisystemlink_no_triggers_breached`.
+- Load [routine-examples.md](./references/routine-examples.md) for sanitized live examples of compound v1 FILES filters and advanced v2 configurations.
+
 ## Reference docs
 
 Consult these for detailed guidance. Load only what you need for the current task.
@@ -171,6 +217,7 @@ Consult these for detailed guidance. Load only what you need for the current tas
 | Topic                       | File                                                        | When to load                                                  |
 | --------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------- |
 | CLI command reference       | [commands.md](./references/commands.md)                     | Looking up command syntax, options, or examples               |
+| Routine examples            | [routine-examples.md](./references/routine-examples.md)     | Provider-specific v1/v2 payload shapes and sanitized live examples |
 | Datasheet-to-specs workflow | [datasheet-workflow.md](./references/datasheet-workflow.md) | Importing specs from PDF, CSV, or structured text             |
 | Filtering guide             | [filtering.md](./references/filtering.md)                   | Advanced LINQ expressions, parameterized queries              |
 | Analysis recipes            | [analysis-recipes.md](./references/analysis-recipes.md)     | Multi-step analysis: yield, calibration, operator performance |

{systemlink_cli-1.13.8 → systemlink_cli-1.13.9}/slcli/skills/slcli/references/commands.md

@@ -358,6 +358,11 @@ Two API versions are supported:
 - **v2** (default): General event-action routines — monitor tags, work-item changes, and more; trigger alarms, emails, or notebook executions.
 - **v1**: Notebook-execution routines with SCHEDULED or TRIGGERED types.
 
+Observed on the demo environment:
+
+- v2 event types: `TAG`, `TESTRESULTCHANGED`, `WORKITEMCHANGED`
+- v2 action types: `ALARM`, `NOTEBOOK`
+
 ```bash
 # List routines
 slcli routine list [OPTIONS]
@@ -375,6 +380,9 @@ slcli routine list [OPTIONS]
 # Get a single routine by ID
 slcli routine get <ROUTINE_ID> [--api-version v1|v2] [-f json]
 
+# Note: the default API version is v2. Use --api-version v1 when reading or
+# updating notebook routines created through the older Routine Manager service.
+
 # Create a v2 event-action routine
 # --event: JSON object with `type` and `triggers` array
 # --actions: JSON array of action objects
@@ -401,7 +409,10 @@ slcli routine create --api-version v1 \
   --name "On Upload" \
   --type TRIGGERED \
   --notebook-id <NOTEBOOK_ID> \
-  --trigger '{"source":"FILES","events":["CREATED"],"filter":"extension=\".csv\""}'
+  --trigger '{"source":"FILES","events":["CREATED"],"filter":"extension=\".xml\""}'
+
+# For compound FILES filters and provider-specific live examples, load
+# routine-examples.md in this folder.
 
 # Update a routine (only supplied fields are changed)
 slcli routine update <ROUTINE_ID> [--api-version v1|v2] \
@@ -420,6 +431,10 @@ slcli routine delete <ROUTINE_ID> [--api-version v1|v2] [-y]
 
 ### v2 event JSON structure
 
+For v2 routines, there is no top-level routine `filter` field. Filtering is
+provider-specific and belongs inside `event.triggers[].configuration` when the
+provider supports it.
+
 ```json
 {
   "type": "TAG",
@@ -437,9 +452,41 @@ slcli routine delete <ROUTINE_ID> [--api-version v1|v2] [-y]
 }
 ```
 
-Supported TAG comparators: `GREATER_THAN`, `LESS_THAN`, `EQUAL`, `NOT_EQUAL`.
+Observed TAG comparators include `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN`, `EQUAL`, `NOT_EQUAL`, and `IN_RANGE`.
 Tag data types: `DOUBLE`, `INT32`, `U_INT64`, `STRING`, `BOOLEAN`.
 
+Some v2 providers use a string filter inside trigger configuration instead of
+structured comparator/path fields. Example from a `WORKITEMCHANGED` routine:
+
+```json
+{
+  "type": "WORKITEMCHANGED",
+  "triggers": [
+    {
+      "name": "8f4db567-9686-4e4b-ac2c-31345cb01691",
+      "configuration": {
+        "filter": "(before.assignedTo != after.assignedTo) && (after.assignedTo = \"a69caa22-7e24-445f-8e9f-084ed98ff6e3\")"
+      }
+    }
+  ]
+}
+```
+
+Another observed string-filter provider is `TESTRESULTCHANGED`:
+
+```json
+{
+  "type": "TESTRESULTCHANGED",
+  "triggers": [
+    {
+      "configuration": {
+        "filter": "(before.status != after.status) && (after.programName = \"...\")"
+      }
+    }
+  ]
+}
+```
+
 ### v2 actions JSON structure
 
 ```json
@@ -465,44 +512,13 @@ Tag data types: `DOUBLE`, `INT32`, `U_INT64`, `STRING`, `BOOLEAN`.
 
 The second ALARM entry with trigger `nisystemlink_no_triggers_breached` is required by the API — it handles the alarm clear/reset state. Email notifications are delivered via `dynamicRecipientList` inside the ALARM action configuration. Severity levels: 1 (low) – 4 (critical).
 
-### Full example: tag threshold monitor with alarm + email
+Load [routine-examples.md](./routine-examples.md) for sanitized live examples covering:
 
-```bash
-slcli routine create \
-  --name "Fred Tag Monitor" \
-  --description "Alert when fred.test.* exceeds 10.2" \
-  --enabled \
-  --event '{
-    "type": "TAG",
-    "triggers": [{
-      "name": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-      "configuration": {
-        "comparator": "GREATER_THAN",
-        "path": "fred.test.*",
-        "thresholds": ["10.2"],
-        "type": "DOUBLE"
-      }
-    }]
-  }' \
-  --actions '[
-    {
-      "type": "ALARM",
-      "triggers": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
-      "configuration": {
-        "displayName": "Fred Test Tag Alarm",
-        "description": "Tag fred.test.* exceeded 10.2",
-        "severity": 4,
-        "condition": "Greater than: 10.2",
-        "dynamicRecipientList": ["fred.visser@emerson.com"]
-      }
-    },
-    {
-      "type": "ALARM",
-      "triggers": ["nisystemlink_no_triggers_breached"],
-      "configuration": null
-    }
-  ]'
-```
+- v1 FILES filters that combine workspace checks, `name.Contains(...)`, and extension matching
+- v2 TAG routines using `IN_RANGE`, `NOT_EQUAL`, and `GREATER_THAN_OR_EQUAL`
+- v2 `TESTRESULTCHANGED` filters with nested field checks, indexed property access, and `DateTime.parse(...)`
+- v2 `WORKITEMCHANGED` filters with `.Any(...)` and `!Contains(...)`
+- Representative NOTEBOOK and ALARM action payloads
 
 ## comment — Resource comments
 

systemlink_cli-1.13.9/slcli/skills/slcli/references/routine-examples.md

@@ -0,0 +1,186 @@
+# Routine Configuration Examples
+
+Load this file when you need sanitized live examples for provider-specific
+routine payloads beyond the minimal syntax in `commands.md`.
+
+## v1 notebook routines
+
+### Scheduled notebook execution
+
+```bash
+slcli routine create --api-version v1 \
+  --name "Daily Notebook" \
+  --type SCHEDULED \
+  --notebook-id <NOTEBOOK_ID> \
+  --schedule '{"startTime":"2026-01-01T00:00:00Z","repeat":"DAY"}'
+```
+
+### FILES trigger with compound filter
+
+Observed v1 routines use the service-owned `trigger.filter` string directly.
+This can be more expressive than the simple `extension=".xml"` example.
+
+```json
+{
+  "trigger": {
+    "source": "FILES",
+    "events": ["CREATED"],
+    "filter": "workspace = \"<WORKSPACE_ID>\" && (name.Contains(\"Specs\") && extension = \"xlsx\")"
+  },
+  "execution": {
+    "type": "NOTEBOOK",
+    "definition": {
+      "notebookId": "<NOTEBOOK_ID>"
+    }
+  }
+}
+```
+
+Notes:
+
+- Keep the v1 filter string in the service's own syntax.
+- Observed FILES filters can combine workspace checks, `name.Contains(...)`, and extension checks.
+
+## v2 event-action routines
+
+### TAG alarm with structured trigger fields
+
+Observed TAG routines can use comparator-driven configuration instead of a
+string `filter`.
+
+```json
+{
+  "event": {
+    "type": "TAG",
+    "triggers": [
+      {
+        "configuration": {
+          "comparator": "IN_RANGE",
+          "deadband": 2,
+          "path": "*.path.to.tag",
+          "thresholds": ["1", "12"],
+          "type": "INT"
+        }
+      },
+      {
+        "configuration": {
+          "comparator": "NOT_EQUAL",
+          "path": "*.path.to.tag",
+          "thresholds": ["3"],
+          "type": "INT"
+        }
+      }
+    ]
+  },
+  "actions": [
+    {
+      "type": "ALARM",
+      "configuration": {
+        "displayName": "Alarm Name",
+        "severity": 4,
+        "condition": "In range: [1, 12]",
+        "dynamicRecipientList": ["user@example.com"]
+      }
+    }
+  ]
+}
+```
+
+### TAG health monitor with threshold alarm
+
+```json
+{
+  "event": {
+    "type": "TAG",
+    "triggers": [
+      {
+        "configuration": {
+          "comparator": "GREATER_THAN_OR_EQUAL",
+          "deadband": 5,
+          "path": "*.Health.Memory.UsePercentage",
+          "thresholds": ["80"],
+          "type": "DOUBLE"
+        }
+      }
+    ]
+  },
+  "actions": [
+    {
+      "type": "ALARM",
+      "configuration": {
+        "displayName": "High memory usage on <system>",
+        "severity": 3,
+        "condition": "Greater than or equal: 80"
+      }
+    }
+  ]
+}
+```
+
+Notes:
+
+- Observed TAG comparators include `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`, `NOT_EQUAL`, and `IN_RANGE`.
+- Alarm-producing TAG routines still need the clear/reset action that uses trigger `nisystemlink_no_triggers_breached`.
+
+### TESTRESULTCHANGED filter with nested fields and time parsing
+
+```json
+{
+  "event": {
+    "type": "TESTRESULTCHANGED",
+    "triggers": [
+      {
+        "configuration": {
+          "filter": "(before.partNumber != after.partNumber) && ((after.status.statusType = \"Done\" && after.hostName = \"<HOST_NAME>\" && after.operator = \"<OPERATOR>\" && after.properties[\"key\"] = \"value\" || after.programName = \"Test Name\" && DateTime(after.updatedAt) > DateTime.parse(\"2026-05-14T19:23:15.275Z\")))"
+        }
+      }
+    ]
+  },
+  "actions": [
+    {
+      "type": "NOTEBOOK",
+      "configuration": {
+        "notebookId": "<NOTEBOOK_ID>",
+        "resourceProfile": "LOW",
+        "priority": "MEDIUM",
+        "serviceAccount": "<SERVICE_ACCOUNT_ID>"
+      }
+    }
+  ]
+}
+```
+
+Notes:
+
+- Observed filters can combine before/after comparisons, nested status fields, indexed property lookups, and `DateTime.parse(...)`.
+
+### WORKITEMCHANGED filter with collection predicates
+
+```json
+{
+  "event": {
+    "type": "WORKITEMCHANGED",
+    "triggers": [
+      {
+        "configuration": {
+          "filter": "(before.assignedTo != after.assignedTo) && (after.resources.assets.selections.Any(s => s.id == \"<ASSET_ID>\") && !after.description.Contains(\"description\") && after.templateId = \"123\")"
+        }
+      }
+    ]
+  },
+  "actions": [
+    {
+      "type": "NOTEBOOK",
+      "configuration": {
+        "resourceProfile": "HIGH",
+        "priority": "HIGH"
+      }
+    }
+  ]
+}
+```
+
+Notes:
+
+- Observed `WORKITEMCHANGED` filters can use `.Any(...)`, negated string checks, and exact template matching.
+- Common NOTEBOOK action fields across v2 examples are `notebookId`, `parameters`, `resourceProfile`, `priority`, and `serviceAccount`.