The Procedure (Script Inventory) API allows you to access and manage procedures (scripts). Through the API you can get, add and delete procedures from the procedure inventory, create and remove folders.

The principles of management rules are described in the Rule-Based Automation document of the Conceptual Guide. The syntax for rule creation is described in the Scripting and Rule-Based Management document of the same guide. Creating and managing tasks through console is described in the Task Executions document of User's Guide.

Accessing the Procedure API

The Script Inventory API is represented by the com.prosyst.mprm.admin.procedures package. Its main interface is ProcedureInventory, representing the procedure inventory module. The ProcedureInventory interface is accessed in two ways:

• By backend bundles – The Procedure Inventory is available as a service on the backend, registered under the com.prosyst.mprm.admin.procedures.ProcedureInventory interface. You can call the service using the conventional techniques defined by the OSGi Framework Specification.

• By external applications/systems – Non-RM applications/systems can access the Procedure Inventory in the standard way for accessing RM services through the Remote Access Client (RAC) module. Working with it is described in the Remote Access to RM guide from the System package documentation.

Using the Procedure API

Through the ProcedureInventory interface you can access and manage the entire procedure inventory and its content.

Folders

You can create folders and organize procedures in them. Each folder is represented by a com.prosyst.mprm.admin.procedures.Folder object. You can use its methods to create new subfolders and define new procedures thus building a convenient hierarchical structure. As the root of the procedure inventory is also treated as a folder, the ProcedureInventory interface extends Folder. Hence, use the methods inherited from the Folder interface to add/remove folders or procedures directly attached to the procedure inventory root.

To get a procedure folder by its path, call the getFolderByPath method of ProcedureInventory. The path to pass as an input parameter should start with the folder that is a direct successor of the procedure inventory root and should end with the target folder. Folders are separated by "/". For example my procedures/procedure group 1 is the path to the "procedure group 1" folder.

To manage folders, you can use the following basic methods of the appropriate Folder:

• getFolders and getFolder(String)

• createFolder

• deleteFolder

The getPath method provides the path in the procedure inventory to the parent folder of the referred Folder object. You can form the full path to this folder through combined invocation of getPath and getName, which returns the name of the folder. For example:

String fullpath = folder.getPath() + "/" + folder.getName()

Procedures

To manage procedures, you can use the following Folder methods:

• getProcedureNames

• getProcedureText

• addProcedure – This method is used for adding a new procedure. It exists in three variants:

  • addProcedure(String name, InputStream in) – Creates a procedure with the given name and contents given as InputStream

  • addProcedure(String name, String text) – Creates a procedure with the given name and contents as Strings

  • addProcedure(String name, String text, boolean hasShortcut, Argument[] arguments, InputStream icon) – This variant of the method allows you to create a procedure adjusting not only its name and contents, but also setting arguments and a custom icon for displaying the procedure in the procedure inventory by GUI applications. See the source code example at the end of this document for illustration on using this method variant.

• deleteProcedure

The methods of com.prosyst.mprm.admin.procedures.Procedure allow you to manage the settings of a particular procedure. You can obtain information about the path, name, contents, icon, etc. of the procedure. You can also set a new name, icon, shortcut or arguments to the Procedure object.

Parametrized Procedures

A procedure has parameters only if such are defined in its procedure text. The RM Procedure API allows you to create GUI applications that detect procedures with arguments and allow the user to define argument properties from the GUI.

First, you need to check if a procedure's text contains parameters. This is done via the parseProcedureText() method of the Folder interface. If this method returns an integer greater than zero, the procedure contains parameter(s).

Then you can create the arguments using the createProcedureArgument(String description, String type, String[] values) method of the Folder object. The description parameter of this method is a free-text description that can be given to help the administrator select the appropriate value of this argument when executing the procedure. The type parameter shows the argument type. It should be one of the following constants of the com.prosyst.mprm.admin.procedures.Argument interface:

• CONTROL_UNIT_ARG – This argument can be used to create a control unit filter that targets the execution of a procedure only to certain control unit. For example, if the user appoints for execution a procedure with such an argument, he/she can be prompted to choose a control unit of his/her interest from a browser that shows all the available control units of a device in a tree structure.

• CONTROL_UNIT_FILTER_ARG – This argument can be used to create a filter that will constrain the execution of a procedure to certain control unit type.

• DEVICE_ARG – An argument for creation of device filters that will target a procedure's execution only to the control units of certain device.

• ENUMERATION_ARG – An argument of this type accepts only a set of specified values. For example, you can create a control unit command that invokes the "$create.install"action of the my.bundle control unit and restrict the input arguments the action can accept only to URI's of certain bundles. For this purpose, you can create an argument of ENUMERATION_ARG, and set a value to the last parameter of the createProcedureArgument to the desired bundle URI Strings.

The values parameter of the createProcedureArgument method contains the values acceptable by this argument, if it is of ENUMERATION_ARG (see above). If the argument is not of this type, this parameter should be null.

When you appoint for execution the commands contained in a parametrized procedure, you actually appoint for execution not the commands themselves but a CALL command passing values to the parameters contained in the original commands.

Importing/Exporting Procedures

The Folder offers two methods for export of procedures into archive files:

• exportInventory – This method allows you to export a set of folders into a JAR file. It does not allow you to select only a subset of the procedures available in that folder location

• exportProcedures – This method allows you to export any set of procedures (no matter their location) into a ZIP file.

Importing procedures from files is done via the importInventory(InputStream in) method.

Using the Procedure API

The example below creates a folder, called "My Procedures", and adds a procedure, called "my procedure", that contains one parameter. The parameter will indicate a control unit filter, which will be user-definable on executing the procedure. The procedure will also have a custom display icon instead of the default icon for displaying in the GUI application.