CQE Repository Script Management Guide

Learn how to manage, execute, and monitor script registration in the CQE (Custom Query Engine) Repository.

🤖 Go to CQE Repository List →

📋 Overview

The CQE Repo List provides a centralized repository for your maintenance and diagnostic scripts. You can store scripts once and deploy them across any number of logical servers (LSVR) with custom execution parameters.

🔍 Script Details & Execution

When you click on a script in the list, the detail modal opens with the following capabilities:

1. Script Content

View the full source code of the script. This is read-only in the list view; use the edit feature if modifications are needed.

2. Execution Settings (NEW)

Before registering a script to a server, you can configure how it should run:

• Active: Toggle whether the script is enabled for the selected servers.
• Repeat: If enabled, the script will run periodically.
• Interval (min): Set the frequency for repeated execution (in minutes).
• Start Date: Specify when the first execution should occur.

3. Server Registration (LSVR Queue Put)

You can select one or more servers from your current project to receive this script.

• LSVR Selector: Use the checkboxes to choose target servers.
• Add to Queue: Click this button to register the script with the defined settings for all selected servers.

📊 Script Usage Status

At the bottom of the modal, the Usage Status Table displays all servers currently registered for this specific script.

• Hostname: The name of the server using the script.
• Usage: The logical server's defined purpose.
• Settings: View the active/repeat/interval status for each registration.
• Last Run: Tracks the last time the script was successfully executed on that machine.

API Reference

For the detailed API specification of this feature, refer to the dedicated guide.

📘 System Management API Reference

Troubleshooting

Symptom	Cause	Solution
Script does not run after adding to the queue	Active is turned off in the execution settings	Enable Active in the detail modal, then add to the queue again.
Target servers are missing from the LSVR selector	The selected project has no servers, or the servers belong to another project	Confirm that the correct project is selected at the top.
Repeated execution does not work	Repeat is on but Interval (min) is empty	Set the interval to 1 or higher, then register again.
Last Run in the usage status is not updated	The target server's agent has not yet received the queue	Check the agent connection and that the start date is in the past.

🔌 CQE API (for automation)

The UI actions above map to these CQE API verbs (byAK/bySk dispatcher). Each request sends text (verb + parameter names), jsondata (values) and token.

• CQERepoPut msName msDetail msBody msPer msPrice msType — register a script into the repository.

  • text carries parameter names only: CQERepoPut msName msDetail msBody msPer msPrice msType
  • jsondata carries the actual values: {"msName":"...","msDetail":"...","msBody":"#!/bin/sh\n...","msPer":0,"msPrice":0,"msType":"sh"}
  • msType is limited to 5 characters (varchar(5)). Long names such as powershell, expect or cmdwin cannot be stored — use the short codes in the table below.

  msType	Target OS	How the agent actually runs it
  ps1	Windows	powershell.exe (headless)
  cmd	Windows	cmd.exe
  bat	Windows	normalized to cmd, then cmd.exe
  wsf	Windows	wscript.exe //B //Nologo
  ps1ui / cmdui	Windows	runs with a visible window in the desktop session
  sh	Linux	sh <tempfile>
  py	Linux	python3 <tempfile>
  ps1	Linux	pwsh <tempfile>

  Do not mix operating systems. The Windows agent runs only the Windows types above; any other value is logged as unsupported_script_type and is not executed. The Linux agent does the opposite — it runs every unknown type through sh, so assigning a bat/wsf script to a Linux server silently runs it under sh and breaks. Register the script with the type matching the OS of the servers you will assign it to.

  • Registering a Linux shell script: put sh in msType and the full shell script in msBody. The Linux agent writes the body to a temp file and runs it with sh, so a #!/bin/bash shebang is ignored. Avoid bash-only syntax ([[ ]], arrays, …) and write POSIX shell, or hand over to bash on the first line with exec bash "$0" "$@".

    #!/bin/sh
    # Runs under sh, so use POSIX syntax only. sk/lssn/apiaddrv2 arrive as environment variables.
    curl -s -H "Authorization: Bearer $sk" "$apiaddrv2/health" | jq -r .status

  • Where to keep the script body: both approaches work.

    • Put the whole body in msBody — nothing has to be pre-installed on the host, and a change on the giip side rolls out to every server. Recommended.
    • Keep the script on the host and only call it — for hosts that already require prerequisites such as jq/curl, or for very long bodies. You then have to track the per-host deployment state yourself.
    • msBody is ntext, so there is no practical length limit (largest observed: 20,883 characters).

• CQEQueuePut mssn lssngroup csn interval active script_type custom_values repeat startdate auid — assign a script to servers.

  • lssngroup: comma-separated LSSN list (one assignment per server).
  • interval: minutes. repeat: 0/1 = one-time, 2 = recursive (re-runs every interval).
  • custom_values: per-server injection → replaces {{CustomVariables}} in the script body.

• CQEQueueGet lssn hostname os op — the agent polls this to receive the next script body.

Script-body placeholders: {{CustomVariables}} (per-assignment custom_values, injected server-side), {{sk}} (agent token), {{lssn}} (agent LSSN).

The Linux agent also exports sk, lssn and apiaddrv2 as environment variables. Instead of the {{sk}}/{{lssn}} placeholders you may reference $sk, $lssn and $apiaddrv2 directly.

Execution limits

	Windows agent	Linux agent
Time limit	600 s by default; change it with cqetimeoutsec in giipAgent.cfg. The script is killed when it is exceeded	none
How it runs	temp file, headless process	temp file, executed with sh
Body length	unlimited (ntext)	same

Run interval: interval is in minutes. The effective cadence is governed by the agent polling cycle — interval=0 does not mean "no schedule", it means re-dispatch on every polling rotation. Several active queues are served in rotation, so with N queues the perceived interval stretches to roughly N× (measured in giipdb docs/30_Specs/SPEC_AND_CHECKLIST.md). Setting the interval to 1 minute will not make it run more often than the polling cycle.

Where results are stored: the script's stdout/stderr go to a local log file on the server running the agent. Only a summary is sent to giip — a KVSPut (kType=lssn, kKey=<lssn>, kFactor=giipagent) creates an event_type="script_execution" record holding script_type, exit_code, execution_time_seconds, mslsn and mssn. The output itself is not stored in giip. To see the output in giip, have the script publish it with KVSPut (retention then follows that KVS configuration).

Failure notification: there is no built-in notification. Detect failures by querying script_execution records with a non-zero exit_code, or send the alert from inside the script.

Full specification: giipdb docs/30_Specs/CQE_SPECIFICATION.md.

---

Version: 1.3 Last Updated: 2026-10-19 Source File: giipv3/public/help/cqerepolist.en.md