Structure of an App

A valid Operations Monitor extension app consists of a Python 3.9 module and of an app specification file, that declares the parameters of the app and the schema of the app's result table. The Python module file and the app specification file must be packed into a ZIP archive, containing no other files and no directories. Such a ZIP archive can be uploaded to Operations Monitor as described in Apps.

Further requirements for the app module and the app specification file apply. The app module must contain a run function with the following signature:

run (facade, params)

Parameters:

• facade

  An instance of libpalladion.scripting.Facade which provides access to the Apps API.

• params

  A dict instance which represents the parameters supplied to the app.

This function is called by Operations Monitor when the app is executed from the web interface or via remote procedure calls.

The app specification file must be an XML file which complies with the Operations Monitor app-specification DTD cited below:

<!DOCTYPE script [
<!ELEMENT script (param-spec?,result-schema?)>
<!ATTLIST script xmlns CDATA #FIXED "http://iptego.de/palladion/script-spec">
<!ATTLIST script name CDATA #REQUIRED>
<!ATTLIST script description CDATA #IMPLIED>
<!ATTLIST script result-type (custom|calls) #REQUIRED>
  
<!ELEMENT param-spec (param+)>
  
<!ELEMENT param EMPTY>
<!ATTLIST param name CDATA #REQUIRED>
<!ATTLIST param label CDATA #REQUIRED>
<!ATTLIST param type (string|datetime|numeric) #REQUIRED>
<!ATTLIST param required CDATA #IMPLIED>
<!ATTLIST param default CDATA #IMPLIED>
  
<!ELEMENT result-schema (column+,primary-key?,unique-key*)>
  
<!ELEMENT column EMPTY>
<!ATTLIST column name CDATA #REQUIRED>
<!ATTLIST column type CDATA #REQUIRED>
<!ATTLIST column null (true|false) #IMPLIED>
<!ATTLIST column auto-increment (true|false) #IMPLIED>
<!ATTLIST column default CDATA #IMPLIED>
  
<!ELEMENT primary-key EMPTY>
<!ATTLIST primary-key columns NMTOKENS #REQUIRED>
  
<!ELEMENT unique-key EMPTY>
<!ATTLIST unique-key name CDATA #REQUIRED>
<!ATTLIST unique-key columns NMTOKENS #REQUIRED>
]>
  

The top-level script element is used to configure some important properties of an app. Its name attribute specifies a name for the app which is displayed in the Available Apps table. The description attribute can contain a longer description for the app. Most importantly, the result-type attribute specifies what kind of result table the app will have. It can be either custom, in which case you must specify the result table in the result-schema element, or calls, in which case the result table is fixed as a calls table.

The param-spec element is a container for parameter specifications declared by the param element. Parameter specifications are used by the web interface to generate the right kind of parameter entry dialog when an app is started. The name attribute of the param element specifies the name of the parameter, that is passed to the app. The label attribute specifies a label that is displayed in the parameter entry dialog. The type attribute specifies how the parameter entry is rendered in the parameter entry dialog. The required attribute decides whether the parameter must be entered or can be left blank. The default attribute specifies a default value, that is filled into the parameter entry.

The result-schema element is used to specify a schema for the result table of the app. This is required when the result-type attribute of the main script element is set to custom. The contents of the result-schema element are translated into an SQL CREATE TABLE statement. You can specify columns in the result table, as well as a primary key and multiple unique keys. The column element specifies a column. The name attribute gives the name of the column. The type attribute specifies the type of the column. It can contain any of the data type specifications valid in MySQL. For more information, see the Create Table Syntax in the MySQL 5.0 Reference Manual:

http://dev.mysql.com/doc/refman/5.0/en/create-table.html

The null attribute decides whether the column is nullable or not. The auto-increment attribute specifies whether the column can be filled via auto increment on insert. The default attribute gives a default value for the column. The primary-key element declares a primary key for the result table. Its columns attribute is a list of columns that make up the primary key. The unique-key element declares a unique key in the result table. Its name attribute gives the name for the unique key. Its columns attribute is a list of columns that make up the unique key.