add headless install (#367)

* add headless install

* nit

* spellcheck

* updated doc for passing agent name as arg

* spellcheck

* upd

---------

Co-authored-by: zachaugenfeld <[email protected]>

.wordlist.txt

@@ -289,3 +289,9 @@ webhook
 AIA
 CDF
 MockGanymedeContext
+tagParams
+inferredData
+headlessly
+startTime
+agentname
+HamiltonAgent

docs/app/agents/DebuggingAgents.mdx

@@ -1,25 +1,25 @@
 ---
 id: DebuggingAgents
-title: Troubleshooting Agents
+title: Agent FAQ and Troubleshooting
 displayed_sidebar: webUiSidebar
 ---
 
 ## FAQ
 
 #### Q: How do I exclude specific files from a watch folder from being uploaded for an agent that uploads files and runs flows?
 
-A: To exclude specific files from being uploaded, you can use the `fp` function to specify which files should be included.  For example, to exclude files that contain the string "exclude" in the filename, you can use the following code:
+A: To exclude specific files from being uploaded, you can use the `fp` function to specify which files should be included. For example, to exclude files that contain the string "exclude" in the filename, you can use the following code:
 
 ```python
-    def fp_res(x: str):
-        x = parse.unquote(x)
+def fp_res(x: str):
+    x = parse.unquote(x)
 
-        # files excluding temp files
-        files_to_capture = [filename in glob.glob(os.path.join(watch_dir, pattern), recursive=True) if not 'exclude' in filename]
+    # files excluding temp files
+    files_to_capture = [filename in glob.glob(os.path.join(watch_dir, pattern), recursive=True) if not 'exclude' in filename]
 
-        return files_to_capture
+    return files_to_capture
 
-    return fp_res
+return fp_res
 ```
 
 #### Q: How do I capture a file that is periodically overwritten by an instrument?
@@ -30,16 +30,92 @@ A: File watcher Agents automatically capture modified files, which they then upl
 
 A: Yes, environment secrets can be accessed from the Agent by using the [get_secret](../../sdk/GanymedeClass#method-get_secret) method.
 
-#### Q: Can I access an environment variable from a cron Agent?  For example, can I access the `input_path` variable configured upon installation?
+#### Q: Can I access an environment variable from a cron Agent? For example, can I access the `input_path` variable configured upon installation?
 
-A: Yes, environment variables can be accessed from a cron Agent through the `kwargs` dictionary.  For example, to access the `input_path` variable, you can use the following code:
+A: Yes, environment variables can be accessed from a cron Agent through the `kwargs` dictionary. For example, to access the `input_path` variable, you can use the following code:
 
 ```python
 # .get method for dictionries is used to handle the case where the variable may not be present without erroring out
 # note: assumes DEFAULT_PATH is configured in the agent
 watch_directory = Path(kwargs.get("vars", {}).get("input_path", DEFAULT_PATH))
 ```
 
+#### Q: Can Windows Agents be installed headlessly?
+
+A: Yes - Agent installers (v4.10+) can be installed headlessly.
+
+##### Requirements
+
+The following files are needed:
+
+- Agent installer (EXE, not MSI) with a minimum core Agent version of 4.10
+- Configuration file (YAML); examples of this can be found in the directory specified by the installer when not installed headlessly. Start with an existing YAML configuration and modify as follows:
+  - Include:
+    - environment (required)
+    - name (required)
+    - variables
+    - tagParams (if applicable)
+  - Exclude:
+    - id
+    - inferredData (any)
+    - startTime
+    - Version
+
+A Windows batch script, such as the one shown below, saved to a .bat file:
+
+```shell
+@ECHO OFF
+
+:: Agent name (used for defining install path) defined by passed argument:
+set agentname=%1
+
+:: Set install path assuming agentname was passed:
+set installpath=C:\Program Files\Ganymede\%agentname%\
+
+:: If agentname was not passed, remove double filesep:
+IF "%~1" == "" (
+	set installpath=C:\Program Files\Ganymede\
+)
+ECHO Step 1: Creating install path: %installpath%
+mkdir "%installpath%"
+
+ECHO Step 2: Copying exe file
+:: Note: %~dp0 is the path of the script (needed when running as admin)
+:: Note: /v verifies the copied file, /y forces a replace if file with same name exists
+copy "%~dp0agent.exe" "%installpath%" /v /y
+
+ECHO Step 3: Copying config file
+copy "%~dp0connection.yaml" "%installpath%" /v /y
+
+ECHO Step 4: Running installer
+start "%installpath%" "%installpath%agent.exe"
+:: Uncomment next line for testing purposes if needed
+:: PAUSE
+```
+
+##### Execution steps
+
+1. Rename agent installer “agent.exe”
+1. Name configuration file “connection.yaml” (if it has a different name)
+1. If desired, zip up a folder containing the agent installer, connection.yaml, and Windows batch script to facilitate sharing.
+1. On the target Windows machine, run the batch script via command prompt or Power Shell (as Administrator).
+   1. To do this manually, unzip the installation package if necessary, and run command prompt or PowerShell (as Administrator).
+   1. In command prompt or PowerShell, run the batch script via command line, optionally supplying the agent name as an argument
+      1. (e.g. "C:\user\agent_install.bat HamiltonAgent")
+      1. If argument is not supplied (e.g. when batch script is run from Windows directly), the install path will default to "C:\Program Files\Ganymede"
+   1. To do this via a script, create a task in Task Scheduler pointing to the Windows batch script.
+      1. Name the task, and check **Run with highest privileges**.
+      1. In the **Actions** tab, add a new action pointing to your batch script.
+         1. In the "Add Arguments" field, optionally provide the agent name. If argument is not supplied, the install path will default to "C:\Program Files\Ganymede"
+      1. In the **Settings** tab, ensure that the task is configured to run without user intervention.
+      1. In the **Triggers** tab, set an appropriate condition to trigger the task.
+
+Once set, invoke the task using `schtasks`:
+
+```powershell
+schtasks /run /tn "TaskName"
+```
+
 #### Q: Are there any command-line scripts (e.g. - .vbs or .bat) that need to run for Windows Agents to work?
 
 A: No, there are no command-line scripts that need to execute for the Windows Agent.
@@ -54,7 +130,7 @@ A: No, the full set of Agent requirements can be found on the [Agent System Requ
 
 #### Issue: The build for a "Watch for files locally then run flow" Agent keeps failing, with no Windows executable or Linux binary created.
 
-Agents that watch for files locally then run Flow require file inputs to be passed to the Flow for execution.  
+Agents that watch for files locally then run Flow require file inputs to be passed to the Flow for execution.
 
 1. Ensure that the Flow being triggered by the Agent has at least one Node for ingesting files.
 2. Ensure that Agent creation occurs after Nodes for input files have been created; if necessary, create a new Agent after the Flow has input Nodes; to see that this is the case, you should see dropdown selectors for specifying glob patterns to associate with the input Nodes of the Flow corresponding to the new Agent.
@@ -63,31 +139,33 @@ Agents that watch for files locally then run Flow require file inputs to be pass
 
 #### Issue: I am unable to install an Agent Connection on Windows; the installer is failing at the final step.
 
-Ensure that you are running the installer as an administrator.  
+Ensure that you are running the installer as an administrator.
 
 Check for existing installations that might conflict with the current installation:
+
 - Open Task Manager and navigate to the Services tab.
 - Look for any service starting with "GanymedeAgent-" and stop it by right-clicking and selecting "Stop."
 - Open "Add or Remove Programs" and uninstall any existing Ganymede Agent installations.
 - Try installing the Agent again.
 
 #### Issue: I've installed an Agent Connection, but do not see the Connection in logs.
 
-This is likely a network issue, which can be confirmed by [testing connectivity](../configuration/AgentSystemRequirements#testing-connectivity).  
+This is likely a network issue, which can be confirmed by [testing connectivity](../configuration/AgentSystemRequirements#testing-connectivity).
 
-Another way to confirm this is to see 
+Another way to confirm this is to see
 
 ```bash
 ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate`
-``` 
+```
 
-in the Connection logs file found locally on the computer.  These logs can be found in the directory that the Agent Connection is installed in.
+in the Connection logs file found locally on the computer. These logs can be found in the directory that the Agent Connection is installed in.
 
 To resolve, ensure that outbound port 443 communication is available to the web addresses mentioned on the [Agent System Requirements page](../configuration/AgentSystemRequirements#testing-connectivity).
 
-#### Issue: The Agent Connection is not actively running.  How do I check?
+#### Issue: The Agent Connection is not actively running. How do I check?
 
 On Windows:
+
 - Open Task Manager and navigate to the Services tab.
 - Look for the Connection of interest (a service with a name starting with "GanymedeAgent-") and verify that its status is "Running."
 - If the service is not running, right-click on it and select "Start." Connections are configured to start upon reboot by default.
@@ -113,17 +191,17 @@ On Linux:
 On Windows:
 
 - Ensure that the PC where the Agent is installed is not asleep. PCs running cron Agents should be configured to never sleep:
-    - Open the Control Panel and navigate to "Hardware and Sound" -> "Power Options."
-    - Select "Change when the computer sleeps" and set "Put the computer to sleep" to "Never."
+  - Open the Control Panel and navigate to "Hardware and Sound" -> "Power Options."
+  - Select "Change when the computer sleeps" and set "Put the computer to sleep" to "Never."
 - Verify that the system time is properly synced:
-    - Right-click on the time in the bottom right corner of the screen and select "Adjust date/time."
-    - Ensure that "Set time automatically" is enabled, and click "Sync now."
+  - Right-click on the time in the bottom right corner of the screen and select "Adjust date/time."
+  - Ensure that "Set time automatically" is enabled, and click "Sync now."
 
 #### Issue: The flow is failing to trigger when files are being dropped
 
 On Windows:
 
-Look at the logs for the agent in Ganymede App.  If you see the JWT error below, click on the system clock in the lower right corner of the screen and select "Adjust date/time".  Ensure that the "Set time automatically" option is enabled, and click "Sync now".
+Look at the logs for the agent in Ganymede App. If you see the JWT error below, click on the system clock in the lower right corner of the screen and select "Adjust date/time". Ensure that the "Set time automatically" option is enabled, and click "Sync now".
 
 ```bash
 _thread.ExceptHookArgs(exc_type=<class 'google.auth.exceptions.RefreshError'>, exc_value=RefreshError('invalid_grant: Invalid JWT: Token must be a short-lived token (60 minutes) and in a reasonable timeframe. Check your iat and exp values in the JWT claim.', {'error': 'invalid_grant', 'error_description': 'Invalid JWT: Token must be a short-lived token (60 minutes) and in a reasonable timeframe. Check your iat and exp values in the JWT claim.'})
@@ -144,7 +222,7 @@ Be careful when copying and pasting commands. The quote character `"` can someti
 
 #### Issue: All files are present in the watched directory, but the flow does not trigger. The logs show files being collected in two different waiting groups.
 
-A: Unquote the string referenced within the fp function, which specifies which filename patterns the Agent should watch for.  An example is shown below:
+A: Unquote the string referenced within the fp function, which specifies which filename patterns the Agent should watch for. An example is shown below:
 
 ```python
 def fp(watch_dir: str, parent_dir: str, pattern: str) -> Callable[[str], bool]:
@@ -154,4 +232,3 @@ def fp(watch_dir: str, parent_dir: str, pattern: str) -> Callable[[str], bool]:
 
     return fp_res
 ```
-

pydoc/generateAllotropeDocs.py

@@ -1,5 +1,5 @@
 def get_allotrope_schema_dict(path: str) -> dict:
-    allotrope_globals = {}
+    allotrope_globals: dict = {}
     with open(path, "r") as f:
         exec(f.read(), allotrope_globals)