[[Category: Proxy Agent]]

= Overview =
This is the interface between the [[Proxy Agent]] and Plugin executable. The function of a plugin executable is to deliver device commands to the device management system and produce a results file with the outcome of the command execution.


= High-level design =
The ProxyAgent will launch a plugin executable with a set of parameters describing the device(s) to target and the action to take on the device(s). Once launched, the ProxyAgent will continue processing actions and will not interact again with the plugin instance (ie. “Fire and Forget”).

Multiple instances of a particular plugin can be launched concurrently. However, the ProxyAgent will not launch more than one plugin instance targeted against a particular device; each device will have at most one plugin operating on it at any given time.

The plugin will drop a command results file into a specific directory to communicate to the ProxyAgent the status of a particular action. Once the command results file is placed in the results directory, ownership of the file transfers to the ProxyAgent. No modifications of the results file may be made.

The command results file is distinct from the device report file. Device report files will communicate the properties of a device.

After the plugin executable has delivered the commands to the device management system, it can terminate or can block on execution progress. With respect to the interface described in this document, no requirements are placed on the plugin executable’s lifetime. The only requirements are that the plugin delivers the commands and then produces the appropriate results file.

If the plugin executable terminates prior to generating a results file or otherwise fails to generate a results file, we will rely on BigFix action expiration to report the failure. The ProxyAgent will not do any active probing of the plugins and will be unable to determine if a command is going to fail.

Example ActionScript:
  wipe
  enable wifi

In the first example, there is a command “wipe” with no options.
In the second example, there’s the Apple MDM command “enable” and command options “wifi”. Both the command and command options will be passed to the plugin.

= Plugin Setup and Configuration =
Plugins are configured by adding a subfolder to the "Plugins" folder of the Proxy Agent install location.  Everything the Proxy Agent needs to interact with the plugin is contained within the plugin folder.  Ideally, the plugin is entirely self-contained within the plugin folder, so that installing a plugin only requires copying the plugin folder and restarting the Proxy Agent (plugins are only registered on startup).

To create a plugin named "Foo Plugin", you would create a folder titled "Foo Plugin" in the "Plugins" folder, and then create a "settings.json" file within the "Foo Plugin" folder.  "settings.json" is the only required file, but you may wish to provide other supporting files for the plugin (such as the actual executable for the plugin along with any additional plugin-specific configuration files).

To declare that your plugin supports additional "runtime inspectors", place "*.inspectors" files in the "Inspectors" subfolder of your plugin folder.  For more information on *.inspectors files see [[Proxy Agent Plugin Inspectors]].

When the Proxy Agent runs, it will create several files and folders within the plugin folder -- it uses the new subfolders to communicate with the plugin, and it uses the files to store information about the current state of devices managed via the plugin.

== settings.json ==
Here's an example "settings.json"

  {
    "ID": "Foo Plugin",
    "ConfigurationOptions": "some information to pass to the plugin each time we execute it",
    "DeviceReportRefreshIntervalMinutes": 360,
    "DeviceReportExpirationIntervalHours": 80000,
    "CommandFormat": "JSON",
    "ExecutablePath": "\"C:\\Program Files (x86)\\BigFix Enterprise\\Management Extender\\Plugins\\Foo Plugin\\plugin\\FooPlugin.exe\"",
    "TargetHintRelevance": "dns name"
    "SendSettingsToPlugin": true
  }

* <tt>ID</tt>
** This is a string that the Proxy Agent will use to identify the plugin.  Each plugin needs to have a unique ID.

* <tt>ConfigurationOptions</tt>
** If non-empty, this setting will be passed to the plugin via the “--configOptions” plugin parameter.  There's no required format, since the plugin is the only one that will ever look at it.
** Default: empty
** Example: username=bigfix;password=bigfix

* <tt>DeviceReportRefreshIntervalMinutes</tt>
** This configures the "heartbeat" interval for this plugin.  Every time this number of minutes elapses, the Proxy Agent will launch the plugin with a request to refresh data on all of its devices.
** If it's very expensive for your plugin to collect that much data, you will want to make this period relatively long.  "Periodic" relevance evaluation (checking to see if a policy action needs to be re-applied, reporting a changed retrieved property, etc.) is driven by this refresh interval, so the shorter you make this interval, the more quickly changes on your devices will be reported into the Console.
** Typically, plugins will use the "refresh all" signal as a trigger to look for new devices entering the system and provide initial reports for those devices.  However, the plugin can use whatever mechanism it sees fit to watch for new devices entering the system, and it is allowed to submit new device reports even if the Proxy Agent hasn't specifically requested the report.
** Default: 15 minutes

* <tt>DeviceReportExpirationIntervalHours</tt>
** This configures the expiration period for this plugin.  If a device doesn't report any information after this many hours, it will be considered "expired" and the Proxy Agent will stop tracking information for the device.
** Default: 168 hours

* <tt>CommandFormat</tt>
** Can be set to "CommandLine" or "JSON".  This setting controls how the Proxy Agent passes arguments to the plugin when it invokes a command.  If the "CommandLine" option is set, all arguments are passed as command line arguments.  If the "JSON" option is set, most arguments are put in a JSON file which is passed to the plugin at execution time.
** Default: JSON

* <tt>ExecutablePath</tt>
** Defines the command line invocation of the plugin.
** Example: C:\plugin.exe
** Example: C:\java\java.exe -jar plugin.jar
** Example: cmd.exe plugin.bat -option1 -option2

* <tt>TargetHintRelevance</tt>
** If this setting is defined, then the Proxy Agent will evaluate this relevance in the context of the "current device" before sending a command to the plugin, and it will then provide the result to the plugin.  For example if the TargetHintRelevance were "dns name", and the Proxy Agent were issuing a command against my computer, it would evaluate the TargetHint to be "surfrider.bigfix.com", and it would provide that hint to the plugin.  This is mainly a convenience function for plugin authors (so that they do not have to maintain their own data structures mapping device ids to other information).

* <tt>SendSettingsToPlugin</tt>
** If this setting is set to "true", then whenever the Proxy Agent encounters a settings action command ("setting" or "setting delete"), it will send the command to the plugin with the argument of "{name}={value}" for "setting" or simply "{name}" for "{setting delete}".  Use this if you need your plugin to be aware of changes to client settings for proxied devices.  The Proxy Agent will wait until the plugin responds to the "settings" command before continuing with the action, so using this mode will make the Proxy Agent take somewhat longer to run actions that contain client settings.
** Default: false

= Plugin interface, execution =
When the proxy agent decides to invoke a plugin, it will launch the process with the following command:

   {executable path} --configOptions "{configuration options}" --commandDir "{command directory}"

The executable path and configuration options are defined in the settings.json file for the plugin.  The "command directory" is provided by the Proxy Agent.  The Proxy Agent writes individual commands into the directory as "command files".  When the plugin is executed, it is responsible for processing every command file currently in the directory.  A command file can be in JSON format or it can be in the form of command line arguments (this is primarily for backwards compatibility with older plugins).

There are two main types of commands:

; Refresh : These commands ask the plugin to get information from a device, and the plugin responds by submitting an updated "device report" to the Proxy Agent.
; Action : These commands ask the plugin to make some change on a device, and the plugin responds by submitting a "command result" file to the Proxy Agent
=== JSON format ===
And here's an example of an iOS plugin "refresh" command:

   {"outputDirectory":"C:\\Program Files (x86)\\BigFix Enterprise\\Management Extender\\DeviceReports",
    "targetDevice":"5K122NP1A4T",
    "targetHint":"clindsay\u0027s iPhone",
    "commandName":"refresh"}

Here's an example of an iOS plugin "action" command:

   {"outputDirectory":"C:\\Program Files (x86)\\BigFix Enterprise\\Management Extender\\Plugins\\Apple MDM\\ActionResultsFiles",
    "inputDirectory":"C:\\Program Files (x86)\\BigFix Enterprise\\Management Extender\\Plugins\\Apple MDM\\ActionExecution\\7810139_569",
    "commandID":"1334104551-0",
    "targetDevice":"5K122NP1A4T",
    "targetHint":"clindsay\u0027s iPhone",
    "commandName":"lock screen",
    "commandArguments":""}

* <tt>outputDirectory</tt>
** This parameter specifies where the plugin should place its response files.

* <tt>inputDirectory</tt>
** This parameter essentially specifies a "working directory" for the plugin to use for this command.  This directory will be persistent over the course of an action execution, so that one command can provide data to be used by a subsequent command.  The most common use of this directory may be to use the "createfile" command to place a file into the working directory, and then provide that file as an argument in a subsequent command.

* <tt>commandID</tt>
** This is the unique identifier for this command request.  The plugin must use this commandID when it generates a response file.

* <tt>targetDevice</tt>
** This is the target of the command, identified by "device id", which can be any string.  The plugin is responsible for generating unique "device ids" when it submits reports and keeping track of how to reach a device based on its id.
** If the target device is not specified and this is a "refresh" command, the plugin should refresh '''all''' devices.

* <tt>targetHint</tt>
** This is a string the Proxy Agent passes to the plugin to help decide how to reach the target.  The string is the result of evaluating the "TargetHintRelevance" from settings.json in the context of the targeted device.  This can be helpful if the unique device ID is not the easiest way for the plugin to find out how to reach the device (for example, maybe relevance to get a primary IP address for the device will be helpful for the plugin).

* <tt>commandName</tt>
** If the command name is "refresh", then the plugin should process this as a refresh command.  Any other string should be interpreted as an action command.  Plugins publish which commands they support by updating the file "ProxyPluginCommands.json" in BES Support.  The Proxy Agent will refuse to run a command if the command name is not listed as a supported command in "ProxyPluginCommands.json".  Bug #45452 tracks the problem that although you can create your own plugin, you can't get new action script commands to work without modifying this central file in BES Support.

* <tt>commandArguments</tt>
** This is a string containing everything after the command name from the source action script line.

=== CommandLine format ===
Command files in the "CommandLine" format contain the same information, but place information in a single line that mimics the format you might see on a command line.  This format is at least somewhat deprecated.

   --outputDir "{outputDirectory}" --inputDir "{inputDirectory}" --commandID "{commandID}" --target "{target}" --targetHint "{targetHint} {commandName} {commandArguments}

Note that the "commandName" and "commandArguments" are passed as unnamed arguments at the end of the string.

= Plugin interface, command results reporting =
When the plugin finishes executing any command other than a "refresh" command, it must write a "command results" file to the directory specified by the "outputDirectory" paramter.

After processing a command, the plugin should communicate the outcome of that command by creating a results file with the format described below. Only a single plugin will be creating command result files in the same directory, so the plugin need only coordinate with other instances of the same plugin. Since a command ID will be provided to the plugin, one suggested format for the file name is: <commandID>-<PID>-<seq>.json, where “PID” is the process ID of the plugin and “seq” is a sequence number unique to that plugin instance (process). For example, if we have command ID “1145” and process ID “87937”, then the plugin would create the result file “1145-87937-0.json”. If the same plugin instance needs to create additional report files, it need only increment the sequence number to create a new unique file name. The ProxyAgent will not impose any particular naming convention at this time.

The ProxyAgent will only read in files with the “.json” extension. In particular, plugin authors are free to create “.json_” or “.json.tmp” files to use as temporary files. After a file has been renamed to “.json”, the ProxyAgent may start reading its contents. Do not place incomplete or temporary files with the “.json” extension in the command results directory.

Ownership of a results file transfers to the ProxyAgent once a file has been placed in the results directory. Plugins must not modify, delete, rename, or lock a file after placing it in the results directory.

The JSON document will consist of three string values whose keys are: “CommandID”, “DeviceID”, and “Result”. Here is a sample document:
  [
     { “CommandID” : “131200445-0”,
       “DeviceID” : “Android_3zf9ac937bmd98”,
       “Result” : “Completed”
    },
     { “CommandID” : “131200445-0”,
       “DeviceID” : “Android_2f476ecb792daf2”,
       “Result” : “Failed”
    }
  ]

; CommandID : Must match the commandID which the Proxy Agent provided when it initiated this command
; DeviceID : Plugin-specific device ID.  Also must match the Device ID provided when the Proxy Agent initiated the command
; Result : "Completed" means this command executed successfully, "Failed" means this command executed but received some sort of failure from the device, "Error" means the plugin encountered some problem which prevented it from executing the command

= Plugin interface, device reports =
In response to "refresh" commands, plugins report data back to the Proxy Agent in the form of "Device Reports".  The format for device reports is specified in the [[Proxy Agent Plugin Inspectors]] document.  The plugin is '''required''' to implement the "device id", "computer name", and "data source" inspectors specified in the "main.inspectors" file (if these inspectors aren't implemented, the Proxy Agent will be unable to register devices reported by the plugin).  If possible, plugins '''should''' implement all inspectors defined in main.inspectors.

The Proxy Agent keeps around the last submitted device report for every active device, so when the plugin submits a new device report it will have to overwrite the previous report.  The plugin should avoid placing incomplete/in-progress reports into the output directory -- as with command results, it can write results to a temporary file, and then move that file into place once the file is complete.

The Proxy Agent notices new reports by watching for any files being touched in a plugin's device reports directory.  When the Proxy Agent processes a report, it will only consider the report "new" if the "effective device communication" time is more recent than the last recorded communication time.  The plugin can specify the communication time by implementing the "last server communication" inspector (this should return a string which can be parsed into an inspector time object).  If the "last server communication" inspector is not implemented, the Proxy Agent will use the file modification time as the "effective device communication time".

In MDM 2.1 (Proxy Agent 9.0.10107 and up), the Proxy Agent added support for a "last device report time" inspector in the device report (see bug #55864).  If this value is present, the Proxy Agent will use it for evaluating the "apparent registration server time" inspector, which is used to generate the "Last Report Time" property shown in the Console.  If the value is not present, the Proxy Agent will use the "effective device communication time" to generate the "Last Report Time".  The purpose of this new option is to allow plugins to generate new reports (i.e. reports that trigger re-evaluation of actions, fixlets, etc.) without updating the "Last Report Time" displayed in the Console.

The Proxy Agent only processes report files that end with the ".report" extension.