The Shell Exec Adapter provides a generic integration method to edgeCore in cases where a more specific data adapter is not appropriate. This adapter allows edgeCore to execute a command and capture the response which is expected to be in either CSV, JSON, or XML format. Alternatively, users can configure an action off of a Shell Exec connection. The action runs a server side script and, optionally, updates one or more other feeds after the server side script runs.
Both static and dynamic variables can be provided to the script via command line parameters and setting environment variables.
Creating a Shell Exec Connection
To utilize the Shell Exec Adapter, the first step is to create a Shell Exec Connection. Go to the Pipeline, click + and select the Shell Exec connection. Then, configure the following connection wizard:
The following options may be configured on a Shell Exec Connection:
| Option | Description | Required | Example |
|---|---|---|---|
| Connection Name | Display Name of Connection | Yes | Launch Codes |
| Description | This is where the administrator can enter notes for the connection. | No | |
| Enabled | If enabled, Connection will count against license limit. | No | Yes |
| Scripts Folder Path | File system location of scripts relative to edgeCore installation folder | Yes | /missile_silo_scripts/ |
Create a Feed
Shell scripts can be written in a variety of languages and can be used so long as you can execute the script on the same operating system that edgeSuite runs upon, and the script can produce output via STDOUT. Given this, edgeCore provides wide latitude on the format of data that the script may produce. When attaching a Feed to a Shell Exec Connection, edgeCore provides a list of File/Stream formats that may be consumed.
Regardless of which output formats are selected, the following Shell-specific options will be presented in the Feed configuration stage:
| Option | Description | Required | Example |
|---|---|---|---|
| Feed Name | Display Name of the Feed | Yes | Active Launch Codes |
| File Name | This file represents the command to be executed. | Yes | get_launch_codes |
| Command Parameters | One or more command line parameters, these can include SHIM expressions. | No | -active -expired=false -number_results 1000 |
| STDERR Treatment | This option provides flexibility in dealing with script output written to STDERR. By default, anything written to STDERR is considered error messages and logged as such. However, if this option is set to Fail, then any STDERR output will be interpreted as if the script had failed executing, meaning that any STDOUT output will be ignored. Setting this option to Ignore will cause edgeSuite to ignore STDERR output from the script entirely. | Yes | |
| Environment Variables | Define or override the environment provided to the script one variable per line in the format KEY=value. These can include SHIM expressions. | No | IGNORE_LAUNCH_CODES_IN_USE=true |
| Use Server Environment | By default the executed command will inherit the complete environment from the edgeCore server along with any changes in the Environment Variables configuration. Setting this switch to No means only the environment defined in Environment Variables will be passed to the script. Using environment variables to pass sensitive information such as passwords is a better method than command line parameters. |
Script Execution Details
As stated, scripts can be written in a variety of languages. However it should be noted that Operating Systems use different approaches in determining what interpreter to run given a particular command. On UNIX, for instance, the convention is to put a “SheBang” line at the stop of a script (#!/path/to/interpreter). So on platforms that are essentially UNIX derivatives, the interpreter to be used is fairly clear.
On UNIX derivatives, if the path specified in the SheBang line is not absolute then the PATH environment variable should be set such that the interpreter can be found.
On Windows, selecting the correct interpreter is a little more complex. On this platform, file extensions are significant, and generally speaking the system registry maintains program associations for each file extension. Generally speaking, if an interpreter is installed (such as Perl, Python, etc.) the Operating System will know what interpreter to run if you “double-click” on a script. edgeCore reads this list of file associations from the System Registry and uses the same mapping. Thus, the issue of integrating edgeSuite with various scripts on Windows becomes merely a System Administration issue. If no registry program association with a file extension exists it is a simple matter to add the correct association to the System Registry.