Dell EMC DataIQ Developer Guide

Plugin configuration file (ca.control)

The primary plug-in configuration file is the ca.control file, which is located in the plug-in hoststorage folder.

The file is formatted as a standard YAML file. This file is only necessary for plugins that were originally designed for ClarityNow custom context menus (CCMs). New plugins written for DataIQ declare this information in code.

Sample code

"Plugin Name": "My Plugin"
"Version": "1.0.0"
"Actions":
  "Perform Action":
    endpoint: "/execute/"
    filter:
      groups:
        - DataIQ Administrators
      listed_within:
        - browse
        - search
      volume_types:
        - TYPE_VFS
        - TYPE_NFS
      applies:
        - files
        - folders
        - sequences
      max_selections: 10000
    command: "python2.7 plugin_script.py -u '%u' -g '%guitoken'"
"Cron Jobs":
  "Cron job - My Plugin":
    "Command": 'python2.7 /hoststorage/plugin_script.py --cron'
    "Execute On":
      DateTimes:
        - "*-*-* 01:00:00" # Run at precisely 1AM everyday
    "Global Configurations":
      userConfiguration: "SomeValue"
      anotherKey: 27
...

The following sections explore the options available in each section of ca.control:

Top-level

"Plugin Name": The name that the plug-in displays in the DataIQ UI.
"Version": May be used by the plug-in author to determine the version of the plug-in that is installed.
"Actions": A collection of actions that the plug-in exposes. See Actions section.
"Cron Jobs": Regularly starts shell commands within the plug-in. See Cron Jobs below.
"Global Configurations:" Not read by any DataIQ code. May be used by plug-in code to determine certain options. See Global Configurations below.

"Actions":

The dictionary of actions is a key-value collection, where the key is the name of the action being declared, and the value is another dictionary containing the specifics for the action.

endpoint: Must be "/execute/" for all legacy plugins.
filter: A dictionary of criteria that a user must meet to be eligible to view and/or start an action.
command: Shell command of program to execute when commanded. May assume the cwd is the plug-in hoststorage. This is a string that may optionally contain any number of replacement variables. See the section on replacement variables below.

filter:

groups: If present and not empty, is treated as a list of groups. A user must be a member of at least one group in the list.
listed_within: If present and not empty, is a list of locations that the action attempts to show on the web UI. Each action may declare one or more of the following locations:
- main: Always visible on the UI. Useful for actions which do not depend on a given selection. Same functionality as the ClarityNow “root” visibility.
- browse: Visible under the Actions tab of a given selection on the Data Management > Browse web page.
- details: Always visible on the UI. Primarily used by the Previewer to display a file preview to the user.
- search: Visible under the Actions tab of a given selection on the Data Management > Search web page.
volume_types: If present and not empty, is a list of volume types that the action may be run on. Some actions are only applicable to certain volume types. The following volume types are recognized: "TYPE_NFS", "TYPE_VFS", and "TYPE_S3".
applies: If present and not empty, is a list of file or folder classifications that the user selections must match. Some actions are only applicable to folders, or files, for example:
- files: Allows file selections.
- folders: Allows folder selections.
- single_volume: Restricts multi-selection to a single volume.
max_selections: Actions that do not support multiple selections must set this to 1. Actions that do support multiple selections should pick a reasonable limit for themselves.
path_regex: If present and not empty, must be a Java-flavor regex string that all selected paths must match in order to allow the Action to run.

command:

Each legacy action is started inside the plug-in hoststorage as a shell command. These commands may consume one or more variables, for example:

command: "python2.7 plugin_script.py --user='%u' --group='%group'"

See the list of replacment variables.

"Cron jobs:"

Regularly starts shell commands within a plugin. For the command to start, the plugin containing the command must be enabled.

The dictionary of cron jobs is a key-value collection, where the key is the name of the cron job being declared, and the value is another dictionary containing the specifics for the cron job.

"Command": Shell command that will be started on schedule. Cannot use replacement variables. May assume that the cwd is the plug-in hoststorage.
"Execute On": > DateTimes: A list of dates and times upon which the action will be periodically started. Uses the cron format.

"Global Configurations":

If your plug-in has settings that you would like DataIQ Administrators to be able to configure, you can use the Global Configurations section of the ca.control to control them. Typical use-cases:

Developing a widely-distributed plug-in that requires a different API key on each DataIQ install.
Developing behaviors that are configurable by administrators and are set for the entire plugin.

When you use this setting:

/hoststorage/ca.control is used for the global defaults.
/hoststorage/.configs/ca.control is a symbolic link to the currently-active configuration file. DataIQ Administrators read and modify this file through the DataIQ UI.
NOTE DataIQ Administrators should not edit this file from the command-line interface directly, because DataIQ may not notice the write, and sometimes this may cause a crash. DataIQ plugins keep a history of configuration changes to allow a configuration rollback in the event of a crash.

Welcome

Welcome to Dell