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

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

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

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

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "systemlink-cli"
-version = "1.7.0"
+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" }]

{systemlink_cli-1.7.0 → 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.7.0"
+__version__ = "1.8.0"

{systemlink_cli-1.7.0 → 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.7.0 → systemlink_cli-1.8.0}/slcli/skills/slcli/SKILL.md

@@ -703,7 +703,7 @@ 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:

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.

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

@@ -0,0 +1,252 @@
+# Notebook Patterns
+
+Annotated examples of common SystemLink notebook patterns.
+
+---
+
+## Pattern 1: Systems Grid Column Report
+
+This is the most common pattern. The notebook queries system data and returns
+a `data_frame` output that the Systems Grid can display as a column.
+
+### Full annotated example (Package Version)
+
+**Cell 1 — Imports description (markdown)**
+```markdown
+### Imports
+Import Python modules for executing the notebook.
+ - Pandas is used for building and handling dataframes.
+ - Scrapbook is used for recording data for the Notebook Execution Service.
+ - SystemsApi is an NI provided package for communicating with the SystemLink Systems service.
+```
+
+**Cell 2 — Imports (code)**
+```python
+import pandas as pd
+import scrapbook as sb
+
+from systemlink.clients.nisysmgmt.api.systems_api import SystemsApi
+from systemlink.clients.nisysmgmt.models.query_systems_request import QuerySystemsRequest
+```
+
+**Cell 3 — Parameters description (markdown)**
+```markdown
+### Parameters
+ - `group_by`: The property by which data is grouped. For the data to appear
+   as a column in the Systems Grid, we must support 'System' here.
+ - `package`: The Package Name of the software to display the version of.
+ - `systems_filter`: A filter specifying which systems to query.
+   An empty filter matches all systems.
+```
+
+**Cell 4 — Parameters (code, with metadata)**
+
+The code cell declares variables with defaults:
+```python
+group_by = "System"
+package = "ni-daqmx"
+systems_filter = ""
+```
+
+The cell metadata must include:
+```json
+{
+  "papermill": {
+    "parameters": {
+      "group_by": "System",
+      "package": "ni-daqmx",
+      "systems_filter": ""
+    }
+  },
+  "systemlink": {
+    "namespaces": [],
+    "outputs": [
+      {
+        "display_name": "Package Version",
+        "id": "package_version",
+        "type": "data_frame"
+      }
+    ],
+    "parameters": [
+      {
+        "display_name": "Group by",
+        "id": "group_by",
+        "type": "string"
+      },
+      {
+        "display_name": "Package",
+        "id": "package",
+        "type": "string"
+      },
+      {
+        "display_name": "Systems Filter",
+        "id": "systems_filter",
+        "type": "string"
+      }
+    ],
+    "version": 2
+  },
+  "tags": ["parameters"]
+}
+```
+
+**Cell 5 — Query description (markdown)**
+```markdown
+### Query for Systems with the specified package and get the Package Version
+```
+
+**Cell 6 — Query (code)**
+```python
+api = SystemsApi()
+
+projection = f'new(id, packages.data["{package}"].displayversion, packages.data["{package}"].version)'
+filter = (systems_filter or "!string.IsNullOrEmpty(id)") + f' && packages.data.keys.Contains("{package}")'
+
+query_sys_request = QuerySystemsRequest(skip=0, projection=projection, filter=filter)
+query_result = api.get_systems_by_query(query=query_sys_request)
+data = await query_result
+```
+
+**Cell 7 — Dataframe description (markdown)**
+```markdown
+### Extract Package data from query results and create pandas dataframe
+```
+
+**Cell 8 — Dataframe (code)**
+```python
+pkg_version = { item['id'] : item['displayversion'] for item in data.data }
+df = pd.DataFrame.from_dict(pkg_version, orient='index', columns=['Package Version'])
+df
+```
+
+**Cell 9 — Output description (markdown)**
+```markdown
+### Convert dataframe to result format that the Systems Grid can interpret
+```
+
+**Cell 10 — Output with sb.glue (code)**
+```python
+df_dict = {
+    'columns': ['minion id', 'package version'],
+    'values': df.reset_index().values.tolist()
+}
+
+result = [{
+    "display_name": "Package Version",
+    "id": "package_version",
+    "type": "data_frame",
+    "data": df_dict
+}]
+
+sb.glue('result', result)
+```
+
+**Cell 11 — Usage instructions (markdown)**
+```markdown
+### View the output of this report in the Systems Grid
+1. Upload this notebook to the reports folder in SystemLink Jupyter
+2. From the Systems page, press the edit grid button
+3. Press '+ ADD' and select 'Notebook' as the data source
+4. Select this report, choose 'Package Version' as the output
+5. Enter the package name and update interval
+6. Enter a column name and press Done
+```
+
+---
+
+## Pattern 2: Test Data Analysis
+
+Query test results and return a summary. Uses `nisystemlink.clients.testmonitor`.
+
+**Parameters cell metadata:**
+```json
+{
+  "papermill": {
+    "parameters": {
+      "group_by": "System",
+      "program_name": "",
+      "status_filter": "",
+      "systems_filter": ""
+    }
+  },
+  "systemlink": {
+    "namespaces": [],
+    "outputs": [
+      {
+        "display_name": "Test Summary",
+        "id": "test_summary",
+        "type": "data_frame"
+      }
+    ],
+    "parameters": [
+      {"display_name": "Group by", "id": "group_by", "type": "string"},
+      {"display_name": "Program Name", "id": "program_name", "type": "string"},
+      {"display_name": "Status Filter", "id": "status_filter", "type": "string"},
+      {"display_name": "Systems Filter", "id": "systems_filter", "type": "string"}
+    ],
+    "version": 2
+  },
+  "tags": ["parameters"]
+}
+```
+
+**Query pattern:**
+```python
+from nisystemlink.clients.testmonitor import TestMonitorClient
+from nisystemlink.clients.core import HttpConfigurationManager
+
+config = HttpConfigurationManager.get_configuration()
+client = TestMonitorClient(config)
+
+# Use the client to query results with filters
+results = client.get_results(
+    filter=f'status.statusType == "{status_filter}"' if status_filter else None,
+    take=1000
+)
+```
+
+**Output pattern (same as Pattern 1):**
+```python
+result = [{
+    "display_name": "Test Summary",
+    "id": "test_summary",
+    "type": "data_frame",
+    "data": {
+        "columns": ["minion id", "pass rate"],
+        "values": df.reset_index().values.tolist()
+    }
+}]
+sb.glue('result', result)
+```
+
+---
+
+## Pattern 3: Scalar Output
+
+When the notebook returns a single value instead of a table.
+
+**Output metadata:**
+```json
+{
+  "systemlink": {
+    "outputs": [
+      {
+        "display_name": "Total Count",
+        "id": "total_count",
+        "type": "scalar"
+      }
+    ]
+  }
+}
+```
+
+**Output code:**
+```python
+result = [{
+    "display_name": "Total Count",
+    "id": "total_count",
+    "type": "scalar",
+    "data": len(df)
+}]
+sb.glue('result', result)
+```