Defining and Implementing Functions

When defining your own device/agent/server context functions, it's necessary to specify properties of their definitions, i.e. name, description, input and output format, permission level, help text, and group. To declare new function, create an instance of FunctionDefinition object and set its properties. Here is an example:

// Creating function input format (scalar, integer)
FieldFormat iff = FieldFormat.create("demoOperationInputField", FieldFormat.INTEGER_FIELD);
TableFormat inputFormat = new TableFormat(1, 1, iff);

// Creating function output format (scalar, string)
FieldFormat off = FieldFormat.create("demoOperationOutputField", FieldFormat.STRING_FIELD);
TableFormat outputFormat = new TableFormat(1, 1, off);

// Creating function (operation) definition. Note that function group should not be changed.
FunctionDefinition fd = new FunctionDefinition("demoOperation", inputFormat, outputFormat, "Demo Operation", ContextUtils.GROUP_DEFAULT);

Once done, add the function definition to a context:

  • Definitions of device driver context's functions matching device operations should be returned by overridden DeviceDriver.readFunctionDefinitions() method. Server will add function definitions to the device context and create action definitions for them.
  • Server plugins should add functions from inside install() and start() methods.
  • Java-based Agents should add functions after Agent object creation via Agent.getContext().addFunctionDefinition().
  • Finally, scripts (both server and widget scripts) should not normally add any functions.

For server-side functions, it might be also necessary to specify permission level:

// Setting permission level
fd.setPermissions(ServerPermissionChecker.getManagerPermissions());

Device operation functions provided by a device driver, along with Agent functions, must belong to a group remote. If you want them to be grouped logically (and put into nested context menus), append group description to a group name using "|" as a separator, e.g. remote|Maintenance Operations.  It's also possible to use nested groups, e.g. remote|Maintenance Operations|Daily.

Function group is specified by calling FunctionDefinition.setGroup(). You can use the following syntax:

fd.setGroup(ContextUtils.createGroup(ContextUtils.GROUP_REMOTE, "Maintenance Operations", "Daily"));

Manually added functions must have a non-null implementation that is a derived from FunctionImplementation interface. The implementation should analyze function input, process it, and generate the output.

Format of data table returned by function implementation method must match output format contained in its definition. Failure to follow this rule may result in data loss since the system will try convert the data table to definition-provided format preserving as much data as it can.

Was this page helpful?