Plugin - Xyna-Factory/xyna GitHub Wiki

Plugins can be used to add features to the Xyna Modeller. It’s possible to either use the ones provided with Xyna or create own plugins.

A Plugin can add a new section to the Factory Manager or introduce custom functionality to the Process Modeller.

Plugins are distributed as part of an Application. To install a Plugin, it’s sufficient to import the corresponding Application and restart the GUI in the browser.

The following screenshot shows the Plugin for OAS Imports in the Factory Manager:

It's available because the Application OAS_Base has been imported:

Creating a Plugin involves two main steps:

1. Registering the Plugin in Xyna
2. Implementing the GUI

New plugins must be registered via the PluginManagement class in the ZetaFramework application. A recommended approach is:

1. Creating a new Workspace that depends on ZetaFramework (see Workspace Management for details)
2. In that Workspace, adding a new Service Group (or, alternatively, a Filter)
3. Registering/unregistering the Plugin in the Service Group
4. Making sure the deployment order is correct

It’s best practice to register the Plugin in onDeployment() and unregister it in onUndeployment(), ensuring the Plugin is available during the lifetime of the Service Group (or Filter).

The following example shows how to add a Plugin that creates a new section for the Factory Manager.

[…]
import xmcp.forms.plugin.Plugin;
[…]

public class DataTypeRoleServicesServiceOperationImpl implements ExtendedDeploymentTask {
  […]

  public void onDeployment() throws XynaException {
    […]
    xmcp.forms.plugin.Plugin plugin = createPlugin();
    xmcp.forms.plugin.PluginManagement.registerPlugin(plugin);
    […]
  }

  public void onUndeployment() throws XynaException {
    […]
    xmcp.forms.plugin.Plugin plugin = createPlugin();
    xmcp.forms.plugin.PluginManagement.unregisterPlugin(plugin);
    […]
  }

  private Plugin createPlugin() {
    String entryName = "Role Usage Violations";

    RuntimeContext rtc = getOwnRtc();
    Plugin.Builder plugin = new Plugin.Builder();
    plugin.navigationEntryLabel(entryName);
    plugin.navigationEntryName(entryName);
    plugin.definitionWorkflowFQN("xmcp.dtroles.fman.GetViolationsDefinition");
    plugin.pluginRTC(rtc);
    plugin.path("manager");

    return plugin.instance();
  }

  private RuntimeContext getOwnRtc() {
    ClassLoaderBase clb = (ClassLoaderBase) getClass().getClassLoader();
    Long revision = clb.getRevision();

    return RuntimeContextService.getRuntimeContextFromRevision(new IntegerNumber(revision));
  }

  […]
}

The members of Plugin have the following meaning:

• navigationEntryLabel Label of the entry in the GUI
• navigationEntryName Name of the entry
• definitionWorkflowFQN The FQN of the Workflow that is used via Workflow-defined UI to define the GUI for the Plugin
• pluginRTC The Runtime Context from which definitionWorkflowFQN is to be executed
• path Defines the path in Xyna where the Plugin is to be shown. For details, see the following section.

This will make a Plugin available in Xyna restarting the GUI.

The member path, specified in the Plugin.Builder object, defines where a Plugin is to be shown. It can be one of the following:

• manager The Plugin is shown as a new section in the Factory Manager

• Plugins for sections of the Process Modeller:

  • modeller/datatype A new tab is shown when editing a Data Type in the Process Modeller

    • modeller/datatype/documentation Shown in the the documentation area of a Data Type
    • modeller/datatype/methods Member methods section
      • modeller/datatype/methods/documentation Documentation area of the methods
      • modeller/datatype/methods/implementation Implementaiton area of the methods
    • modeller/datatype/members Member variables section
      • modeller/datatype/members/documentation Documentation area of the member variables
    • modeller/datatypes/rightnav to do

  • modeller/exception New tab in Exception Types

    • modeller/exception/documentation Documentation area of a Execption Type
    • modeller/exception/members Member variables section
      • modeller/exception/members/documentation Documentation area of the member variables

  • modeller/servicegroup New tab in Service Groups

    • modeller/servicegroup/documentation Documentation area of a Service Group
    • modeller/servicegroup/methods Methods section
      • modeller/servicegroup/methods/documentation Documentation area of the methods
      • modeller/servicegroup/methods/implementation Implementaiton area of the methods

  • modeller/workflow/mapping Plugins for Mappings in Workflows

  • datatypes/navbar Plugins for the Factory-Navigation

The paths correspond to the following locations:

The paths for Exception Types and Service Groups are analogous to the ones for Data Types and start with modeller/exception and modeller/servicegroup respectively. However, there are no Services in Exception Types and no member variables in Service Groups.

To make sure the Plugin Management has already been deployed at the time the Service Group (or Filter) with the Plugin is being deployed, an AdditionalDependency meta tag has to be added to the XML of the Service Group / Filter:

<DataType xmlns="http://www.gip.com/xyna/xdev/xfractmod" Version="1.8" TypeName="DataTypeRoleServices" TypePath="xmcp" Label="Data Type Role Services" IsAbstract="false">
  […]
  <Service Label="ConstraintMgmt" TypeName="ConstraintMgmt">
    <Meta>
      <AdditionalDependencies>
        <Datatype>xmcp.forms.plugin.PluginManagement</Datatype>
      </AdditionalDependencies>
    </Meta>
    […]
  </Service>
</DataType>

The GUI components of a Plugin are to be implemented via Workflow-defined UI. The Workflow being called is defined during the registration of the Plugin (for details, see above):

private Plugin createPlugin() {
  […]
  Plugin.Builder plugin = new Plugin.Builder();
  plugin.definitionWorkflowFQN("xmcp.dtroles.pmod.GetRoleDefinition");
  plugin.path("modeller/datatype");
  […]

  return plugin.instance();
}

The corresponding Workflow could look something like this:

This would give a new section for Data Types in which one can set whether it is used for the backend or the frontend: