systemlink-cli 1.6.5__tar.gz → 1.8.0__tar.gz

{systemlink_cli-1.6.5 → systemlink_cli-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: systemlink-cli
-Version: 1.6.5
+Version: 1.8.0
 Summary: SystemLink Integrator CLI - cross-platform CLI for SystemLink workflows and templates.
 License-File: LICENSE
 Author: Fred Visser
@@ -12,6 +12,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: click (>=7.1.2)
 Requires-Dist: keyring (>=25.6.0,<26.0.0)
+Requires-Dist: packaging (>=21.0)
 Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
 Requires-Dist: questionary (>=2.1.1,<3.0.0)
 Requires-Dist: requests (>=2.32.4,<3.0.0)

{systemlink_cli-1.6.5 → systemlink_cli-1.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "systemlink-cli"
-version = "1.6.5"
+version = "1.8.0"
 description = "SystemLink Integrator CLI - cross-platform CLI for SystemLink workflows and templates."
 authors = ["Fred Visser <fred.visser@emerson.com>"]
 packages = [{ include = "slcli" }]
@@ -35,6 +35,7 @@ truststore = ">=0.9,<0.11"
 watchdog = "^6.0.0"
 pyyaml = "^6.0.3"
 questionary = "^2.1.1"
+packaging = ">=21.0"
 rich = ">=13.7,<15"
 rich-click = ">=1.8,<2"
 

{systemlink_cli-1.6.5 → systemlink_cli-1.8.0}/slcli/_version.py

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

{systemlink_cli-1.6.5 → systemlink_cli-1.8.0}/slcli/skill_click.py

@@ -11,7 +11,7 @@ import questionary
 from .utils import ExitCodes
 
 SKILL_NAME = "slcli"
-SKILL_CHOICES = ["slcli", "systemlink-webapp"]
+SKILL_CHOICES = ["slcli", "systemlink-webapp", "systemlink-notebook"]
 
 # Mapping of client name -> (personal skills dir, project subdir relative to repo root)
 # personal dir uses Path.home() so it's always resolved at call time via _personal_dir().
@@ -178,7 +178,7 @@ def register_skill_commands(cli: Any) -> None:
         "-k",
         type=click.Choice(SKILL_CHOICES + ["all"], case_sensitive=False),
         default=None,
-        help="Skill to install (slcli, systemlink-webapp, or all).",
+        help="Skill to install (slcli, systemlink-webapp, systemlink-notebook, or all).",
     )
     @click.option(
         "--client",
@@ -207,7 +207,7 @@ def register_skill_commands(cli: Any) -> None:
         """Install agent skills for AI coding assistants.
 
         Copies bundled skills into the skills directory of one or more AI clients.
-        Available skills: slcli, systemlink-webapp.
+        Available skills: slcli, systemlink-webapp, systemlink-notebook.
         Supported clients and their skill locations:
 
                     \b

{systemlink_cli-1.6.5 → systemlink_cli-1.8.0}/slcli/skills/slcli/SKILL.md

@@ -227,6 +227,15 @@ slcli system report --type [SOFTWARE|HARDWARE] -o FILE  # Generate CSV report
 slcli system update <SYSTEM_ID> [OPTIONS]            # Update system metadata
 slcli system remove <SYSTEM_ID>                      # Remove a system
 
+# Compare two systems (by ID or alias)
+slcli system compare <SYSTEM_A> <SYSTEM_B> [-f json]
+# Compares installed software (packages, versions) and connected assets
+# (model, vendor, slot number). Accepts system IDs or alias names.
+# Output sections:
+#   Software: packages unique to each system, version differences
+#   Assets:   assets unique to each system, count mismatches, slot differences
+# Assets are matched by (modelName, vendorName) identity.
+
 # System jobs
 slcli system job list [OPTIONS]
 slcli system job get <JOB_ID>
@@ -249,6 +258,7 @@ slcli tag delete <TAG_PATH>                         # Delete a tag
 ### routine — Event-action and notebook routine management
 
 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.
 
@@ -580,7 +590,7 @@ slcli customfield edit [--directory DIR]                 # Interactively edit +
 ### template — Test plan template management
 
 > **Note:** Work item templates are managed separately via `slcli workitem template`.
-> The `slcli template` command manages test plan *configuration* templates used
+> The `slcli template` command manages test plan _configuration_ templates used
 > when provisioning new test plan instances.
 
 ```bash
@@ -641,6 +651,7 @@ slcli workitem workflow preview [--file PATH] [--id WORKFLOW_ID] [--html] [--no-
 ```
 
 **Create work item options:**
+
 ```bash
 slcli workitem create \
   --name "Battery Cycle Test" \
@@ -692,15 +703,17 @@ generated `.nipkg`, and emits a thin `manifest.json` with `schemaVersion`, `nipk
 Install bundled skills for supported AI clients.
 
 ```bash
-slcli skill install --skill [slcli|systemlink-webapp|all] --client [agents|claude|all] --scope [personal|project|both]
+slcli skill install --skill [slcli|systemlink-webapp|systemlink-notebook|all] --client [agents|claude|all] --scope [personal|project|both]
 ```
 
 Client paths:
+
 - `agents` — personal: `~/.agents/skills/`, project: `.agents/skills/` (most agents)
 - `claude` — personal: `~/.claude/skills/`, project: `.claude/skills/`
 - `all` — install to both the `agents` and `claude` locations for the selected scope
 
 Notes:
+
 - `agents` is the default client in interactive mode.
 - `webapp init` installs project-scoped skills into `.agents/skills/` by default.
 

systemlink_cli-1.8.0/slcli/skills/systemlink-notebook/SKILL.md

@@ -0,0 +1,310 @@
+---
+name: systemlink-notebook
+description: >-
+  Create, structure, and deploy Jupyter Notebooks for NI SystemLink.
+  Use when the user asks to create a notebook, report, or analysis that runs on
+  SystemLink — including Systems Grid reports, test data analysis notebooks,
+  asset reports, scheduled notebooks, or any notebook that uses scrapbook (sb.glue)
+  to return results. Covers parameter cells, systemlink metadata, output formats,
+  papermill integration, and deployment via slcli.
+argument-hint: 'Describe the notebook purpose and what data it should report on'
+---
+
+# SystemLink Notebook Creation
+
+## When to Use
+
+- Creating a new Jupyter Notebook that will run on SystemLink
+- Adding parameters or outputs to a notebook for the SystemLink Notebook Execution Service
+- Building a Systems Grid column report
+- Creating a test data analysis notebook
+- Deploying a notebook to SystemLink via `slcli`
+
+## Notebook Structure
+
+Every SystemLink notebook follows this cell pattern:
+
+1. **Imports (markdown)** — describe dependencies
+2. **Imports (code)** — import modules
+3. **Parameters (markdown)** — describe each parameter
+4. **Parameters (code)** — declare parameter variables with defaults *(requires special metadata)*
+5. **Logic (markdown + code)** — one or more pairs of markdown/code cells
+6. **Output (markdown)** — describe the output format
+7. **Output (code)** — format results and call `sb.glue('result', result)`
+8. **Instructions (markdown)** — how to use the notebook in SystemLink UI
+
+## Parameters Cell Metadata
+
+The parameters cell is the most critical part. It **must** have this metadata structure
+in the cell's `.metadata` field for SystemLink to recognize the parameters and outputs.
+
+```json
+{
+  "papermill": {
+    "parameters": {
+      "param_name": "default_value"
+    }
+  },
+  "systemlink": {
+    "namespaces": [],
+    "outputs": [
+      {
+        "display_name": "Human Readable Output Name",
+        "id": "output_snake_case_id",
+        "type": "data_frame"
+      }
+    ],
+    "parameters": [
+      {
+        "display_name": "Human Readable Param Name",
+        "id": "param_name",
+        "type": "string"
+      }
+    ],
+    "version": 2
+  },
+  "tags": ["parameters"]
+}
+```
+
+### Key rules for parameter metadata
+
+- `papermill.parameters` keys **must** match the variable names in the code cell
+- `systemlink.parameters[].id` **must** match the variable names in the code cell
+- `systemlink.outputs[].id` **must** match the key used in the result dict passed to `sb.glue`
+- `tags: ["parameters"]` is **required** — this is how papermill identifies the cell
+- `systemlink.version` must be `2` for most notebooks, or `1` for **Work Item Automations**
+- Supported parameter types: `string`, `integer`, `float`, `boolean`, `string[]`
+- Supported output types: `data_frame`, `scalar`, `string`, `string[]`
+
+### Work Item Automations pattern
+
+Notebooks with the **Work Item Automations** interface receive work item IDs as a
+**list** (`string[]`), not a comma-separated string. Key differences from other notebooks:
+
+- `systemlink.version` must be `1`
+- `work_item_ids` parameter type is `"string[]"` and its default value in
+  `papermill.parameters` is `[]` (empty list)
+- The Python variable must also default to a list: `work_item_ids = []`
+- Do NOT split by comma — the parameter is already a list of strings
+
+Example parameters cell metadata for Work Item Automations:
+```json
+{
+  "papermill": {
+    "parameters": {
+      "work_item_ids": []
+    }
+  },
+  "systemlink": {
+    "outputs": [...],
+    "parameters": [
+      {
+        "display_name": "Work item IDs",
+        "id": "work_item_ids",
+        "type": "string[]"
+      }
+    ],
+    "version": 1
+  },
+  "tags": ["parameters"]
+}
+```
+
+## Output Format (sb.glue)
+
+All notebooks must use `scrapbook` to return results. The output cell should:
+
+```python
+import scrapbook as sb
+
+# For data_frame outputs:
+result = [{
+    "display_name": "Human Readable Name",
+    "id": "output_id",           # Must match systemlink.outputs[].id
+    "type": "data_frame",
+    "data": {
+        "columns": ["column1", "column2"],
+        "values": df.reset_index().values.tolist()
+    }
+}]
+sb.glue('result', result)
+
+# For scalar outputs:
+result = [{
+    "display_name": "Count",
+    "id": "count_output",
+    "type": "scalar",
+    "data": 42
+}]
+sb.glue('result', result)
+```
+
+### Systems Grid reports
+
+When the notebook is used as a Systems Grid column, the `data_frame` output
+**must** include `minion id` as the first column. This maps rows to systems.
+
+```python
+df_dict = {
+    'columns': ['minion id', 'your column name'],
+    'values': df.reset_index().values.tolist()  # index = system IDs
+}
+```
+
+## Common Imports
+
+```python
+# Always needed
+import pandas as pd
+import scrapbook as sb
+
+# Systems queries
+from systemlink.clients.nisysmgmt.api.systems_api import SystemsApi
+from systemlink.clients.nisysmgmt.models.query_systems_request import QuerySystemsRequest
+
+# Test results
+from nisystemlink.clients.testmonitor import TestMonitorClient
+from nisystemlink.clients.core import HttpConfigurationManager
+
+# Assets
+from nisystemlink.clients.assetmanagement import AssetManagementClient
+
+# Direct HTTP (when no typed client exists)
+import requests
+from nisystemlink.clients.core import HttpConfigurationManager
+config = HttpConfigurationManager.get_configuration()
+base_url = config.server_uri.rstrip("/")
+headers = {"x-ni-api-key": config.api_keys[0]}
+```
+
+## Systems Query Pattern
+
+The `SystemsApi` uses a projection/filter pattern for querying:
+
+```python
+api = SystemsApi()
+
+# Projection selects which fields to return
+projection = 'new(id, alias, state, packages.data["ni-daqmx"].displayversion)'
+
+# Filter selects which systems to include
+filter = '!string.IsNullOrEmpty(id) && packages.data.keys.Contains("ni-daqmx")'
+
+query = QuerySystemsRequest(skip=0, projection=projection, filter=filter)
+query_result = api.get_systems_by_query(query=query)
+data = await query_result
+```
+
+### Common filter expressions
+
+| Filter | Description |
+|--------|-------------|
+| `!string.IsNullOrEmpty(id)` | All systems (default/fallback) |
+| `connected.data.state == "CONNECTED"` | Connected systems only |
+| `packages.data.keys.Contains("pkg")` | Systems with a specific package |
+| `grains.data.kernel == "Windows"` | Windows systems |
+
+## Notebook Interfaces
+
+When deploying, set the notebook interface to tell SystemLink how it will be used.
+See [interfaces reference](./references/interfaces.md) for the full list.
+
+Common interfaces:
+- **Systems Grid** — report that adds a column to the Systems management grid
+- **Test Data Analysis** — analysis of test monitor results
+- **Periodic Execution** — scheduled recurring notebook
+- **Work Item Automations** — triggered by work item state changes
+
+## Setting Cell Metadata
+
+The VS Code notebook editor tools do **not** persist custom cell metadata (like
+`papermill`, `systemlink`, `tags`). You must write cell metadata directly into
+the `.ipynb` JSON file using a Python script:
+
+```python
+import json
+
+with open('notebook.ipynb') as f:
+    nb = json.load(f)
+
+# Find the parameters cell and set its metadata
+for cell in nb['cells']:
+    src = ''.join(cell.get('source', []))
+    if 'parameters' in src and cell['cell_type'] == 'code':
+        cell['metadata'] = {
+            "papermill": {
+                "parameters": {
+                    "param_name": "default_value"
+                }
+            },
+            "systemlink": {
+                "namespaces": [],
+                "outputs": [...],
+                "parameters": [...],
+                "version": 2
+            },
+            "tags": ["parameters"],
+            "trusted": False,
+            "editable": True,
+            "slideshow": {"slide_type": ""}
+        }
+        break
+
+with open('notebook.ipynb', 'w') as f:
+    json.dump(nb, f, indent=1)
+    f.write('\n')
+```
+
+**Critical:** Without this metadata, SystemLink will not display parameters or
+outputs in the UI. Always verify metadata was written by inspecting the raw JSON.
+
+Also ensure the notebook-level `kernelspec` metadata is set. Papermill requires
+this to execute the notebook — without it you get
+`ValueError: No kernel name found in notebook`. The VS Code notebook editor may
+clear this when editing cells. Always verify and restore if needed:
+
+```python
+nb['metadata']['kernelspec'] = {
+    'display_name': 'Python 3',
+    'language': 'python',
+    'name': 'python3'
+}
+```
+
+## Deployment
+
+Deploy via `slcli`. **Always read the user's configured workspace** from `slcli info`
+and pass it with `--workspace` so the notebook lands in the correct workspace:
+
+```bash
+# 1. Read the configured workspace name from the active slcli profile
+#    (look for the "Workspace" row in `slcli info` output)
+
+# Create a new notebook with interface and workspace set at creation time (preferred)
+slcli notebook manage create --file notebook.ipynb --name "My Notebook" --interface "Systems Grid" --workspace "<WORKSPACE_NAME>"
+
+# Update content of an existing notebook
+slcli notebook manage update --id <NOTEBOOK_ID> --content notebook.ipynb
+
+# Update interface or metadata in place when needed
+slcli notebook manage update --id <NOTEBOOK_ID> --interface "Systems Grid"
+
+# Delete and re-create only as a fallback if the server rejects the update
+slcli notebook manage delete --id <NOTEBOOK_ID> --yes
+slcli notebook manage create --file notebook.ipynb --name "My Notebook" --interface "Systems Grid" --workspace "<WORKSPACE_NAME>"
+```
+
+**Important:** Prefer setting `--interface` at creation time, but use
+`slcli notebook manage update --interface ...` for in-place interface changes when
+you are updating an existing notebook. Delete and re-create only as a fallback if
+the server rejects the update.
+
+**Important:** Always determine the target workspace by running `slcli info` and
+reading the `Workspace` field from the active profile. Do not assume "Default" or
+prompt the user unless `slcli info` shows no workspace configured.
+
+## Example
+
+See [notebook-patterns.md](./references/notebook-patterns.md) for a complete
+annotated example based on the NI PackageVersionExample pattern.

systemlink_cli-1.8.0/slcli/skills/systemlink-notebook/references/interfaces.md

@@ -0,0 +1,82 @@
+# Notebook Interfaces
+
+When deploying a notebook to SystemLink, you can assign an **interface** that tells
+SystemLink how the notebook will be used. This affects how parameters are presented
+and how the notebook is triggered.
+
+Set the interface during creation or update:
+
+```bash
+slcli notebook manage update --id <ID> --interface "Systems Grid"
+```
+
+Prefer `create --interface ...` when you are creating a new notebook. Use
+`update --interface ...` for in-place interface changes on an existing notebook.
+Delete and re-create only if the server rejects the update.
+
+## Available Interfaces
+
+| Interface                    | Use Case                                                                                                                                                                                               |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Assets Grid**              | Report that adds a column to the Assets management grid                                                                                                                                                |
+| **Data Table Analysis**      | Analysis of data table contents                                                                                                                                                                        |
+| **Data Space Analysis**      | Analysis of data space contents                                                                                                                                                                        |
+| **File Analysis**            | Analysis of uploaded files                                                                                                                                                                             |
+| **Periodic Execution**       | Scheduled recurring notebook (e.g. daily/hourly reports)                                                                                                                                               |
+| **Resource Changed Routine** | Triggered when a resource changes (via v1 routines)                                                                                                                                                    |
+| **Specification Analysis**   | Analysis against specifications/limits                                                                                                                                                                 |
+| **Systems Grid**             | Report that adds a column to the Systems management grid                                                                                                                                               |
+| **Test Data Analysis**       | Analysis of test monitor results                                                                                                                                                                       |
+| **Test Data Extraction**     | Extract and transform test data                                                                                                                                                                        |
+| **Work Item Automations**    | Notebooks that can be manually executed on selected work items, or triggered by work item lifecycle events. **Use this for any notebook that acts on work items** (e.g. close, update status, assign). |
+| **Work Item Operations**     | Internal operations performed on work items by the system                                                                                                                                              |
+| **Work Item Scheduler**      | Scheduling logic for work items                                                                                                                                                                        |
+
+## Common Interface Patterns
+
+### Systems Grid
+
+Parameters typically include:
+
+- `group_by` (string) — always support "System"
+- `systems_filter` (string) — filter expression for which systems
+- Domain-specific params (e.g. `package` for package version)
+
+Output must be `data_frame` with `minion id` as the first column.
+
+### Test Data Analysis
+
+Parameters typically include:
+
+- `group_by` (string)
+- `program_name` (string)
+- `status_filter` (string)
+- `systems_filter` (string)
+
+### Periodic Execution
+
+No special parameter requirements. Typically uses fixed configuration
+or reads from tags/files. Can be scheduled via routines:
+
+```bash
+slcli routine create --api-version v1 \
+  --name "Daily Report" \
+  --type SCHEDULED \
+  --notebook-id <NOTEBOOK_ID> \
+  --schedule '{"startTime":"2026-01-01T00:00:00Z","repeat":"DAY"}'
+```
+
+### Work Item Automations
+
+Use this interface for notebooks that act on selected work items (close, update,
+assign, etc.). The notebook appears in the work items UI and can be manually
+triggered on one or more selected work items.
+
+Parameters are injected by the work item system:
+
+- `work_item_ids` (string[]) — list of selected work item IDs. Default: `[]`
+- `workspace` (string) — workspace context (optional)
+
+**Critical:** `work_item_ids` must be typed as `"string[]"` (not `"string"`),
+default to `[]` in both papermill and the code cell, and `systemlink.version`
+must be `1`. See the systemlink-notebook skill for the full metadata example.