PI (Programming Interface) Activity

The Program Interface Activity element is located in the Activity drawer of the process editor palette.

Element Details

This element allows Axon.ivy to integrate custom-made software, legacy systems, proprietary applications or any other external system through a Java interface. The Program Interface element will instantiate a Java class that implements the interface IUserProcessExtension and will call the method perform each time a process arrives at the Program Interface. The common way to implement a Program Interface bean is to extend the abstract base class AbstractUserProcessExtension. The interface also includes an inner editor class to parametrize the bean. The documentation of the interface and the abstract class can be found in the Java Doc of the Axon.ivy Public API.

Note

Since Axon.ivy version 3.x this element has become somewhat obsolete since it has become very easy to create and call your own Java classes from IvyScript. However, the PI element still provides a standardized interface to a third party Java class and can provide a custom made editor for parametrization.

Inscription

Name Tab

The Name Tab is included in the mask of all process elements and contains the name and a description of the element.

PI Tab

On this tab you define the Java class that implements the interface IUserProcessExtension and is called when the PI step gets executed. Furthermore, you can specify exception handlers for errors such as unreachable systems, insufficient privileges and more.

Java Class to Execute: The fully qualified name of the PI Java class implementing IUserProcessExtension. You can use default copy & paste commands, open a Java Type Browser to search for the class or you use the predefined Wait class which just waits for a given period of time. Use the New Bean Class Wizard () to create a new Java source file with an example implementation of the bean class.
Program error: Occurs whenever an exception is thrown during the execution of the class. The error can be handled by a catching Error Start.
Timeout: Sets a timeout for the return call to the Java PI class.
Timeout error: Occurs when the timeout is reached. The error can be handled by a catching Error Start.

Editor Tab

This tab displays the editor that can be integrated in the external Java bean of the process element. The editor is implemented as an inner public static class of the Java bean class and must have the name Editor. Additionally the editor class must implement the IProcessExtensionConfigurationEditorEx interface. The common way to implement the editor class is to extend the abstract base class AbstractProcessExtensionConfigurationEditor and to override the methods createEditorPanelContent, loadUiDataFromConfiguration and saveUiDataToConfiguration. The method createEditorPanelContent can be used to build the UI components of the editor. You can add any AWT/Swing component to the given editorPanel parameter. With the given editorEnvironment parameter, which is of the type IProcessExtensionConfigurationEditorEnvironment, you can create text fields that support ivyScript and have smart buttons that provide access to the process data, environment functions and Java classes.

Here is an example on how an editor could look like:

../../../_images/program-interface-activy-sample.png

As you can see, the editor provides access to any process relevant data that can be used by your own process elements. For instance, you can easily transfer process data to your legacy system.

The following part shows the implementation of the above editor. As mentioned earlier Axon.ivy provides the IIvyScriptEditor that represents a text field with ivyScript support and smart buttons. Inside createEditorPanelContent use the method createIvyScriptEditor from the editorEnvironment parameter to create an instance of such an editor. Use the loadUiDataFromConfiguration method to read the bean configuration and show within the UI components. Inside this method you can use the methods getBeanConfiguration or getBeanConfigurationProperty to read the bean configuration. Use the method saveUiDataToConfiguration to save the data in the UI components to the bean configuration. Inside this method you can use methods setBeanConfiguration or setBeanConfigurationProperty to save the bean configuration.

public static class Editor extends AbstractProcessExtensionConfigurationEditor
{
  private IIvyScriptEditor editorUser;
  private IIvyScriptEditor editorEventTyp;
  private IIvyScriptEditor editorLinkId;
  private IIvyScriptEditor editorFieldValue;

  @Override
  protected void createEditorPanelContent(Container editorPanel,
          IProcessExtensionConfigurationEditorEnvironment editorEnvironment)
  {
    editorPanel.setLayout(new GridLayout(4, 2));
    editorUser = editorEnvironment.createIvyScriptEditor(null, null, "String");
    editorEventTyp = editorEnvironment.createIvyScriptEditor(null, null, "String");
    editorLinkId = editorEnvironment.createIvyScriptEditor(null, null, "String");
    editorFieldValue = editorEnvironment.createIvyScriptEditor(null, null);

    editorPanel.add(new JLabel("User"));
    editorPanel.add(editorUser.getComponent());
    editorPanel.add(new JLabel("Event Typ"));
    editorPanel.add(editorEventTyp.getComponent());
    editorPanel.add(new JLabel("Link-Id"));
    editorPanel.add(editorLinkId.getComponent());
    editorPanel.add(new JLabel("Feldwert"));
    editorPanel.add(editorFieldValue.getComponent());
  }

  @Override
  protected void loadUiDataFromConfiguration()
  {
    editorUser.setText(getBeanConfigurationProperty("User"));
    editorEventTyp.setText(getBeanConfigurationProperty("EventTyp"));
    editorLinkId.setText(getBeanConfigurationProperty("LinkId"));
    editorFieldValue.setText(getBeanConfigurationProperty("Feldwert"));
  }

  @Override
  protected boolean saveUiDataToConfiguration()
  {
    setBeanConfigurationProperty("User", editorUser.getText());
    setBeanConfigurationProperty("EventTyp", editorEventTyp.getText());
    setBeanConfigurationProperty("LinkId", editorLinkId.getText());
    setBeanConfigurationProperty("Feldwert", editorFieldValue.getText());
    return true;
  }
}

At runtime you have to evaluate the IvyScript the user have entered into the ivy script editors. If you implement for example the AbstractUserProcessExtension class there is a perform method which is executed at runtime. At this point you want to access the configured data in the editor. The following code snippet show how you can evaluate the value of an IIvyScriptEditor. If you use the IIvyScriptEditor you only get the value by calling the executeIvyScript method of the AbstractUserProcessExtension.

public CompositeObject perform(IRequestId requestId, CompositeObject in,
     IIvyScriptContext context) throws Exception
{
  IIvyScriptContext ownContext;
  CompositeObject out;
  out = in.clone();
  ownContext = createOwnContext(context);

  String eventtyp = "";
  String linkId = "";
  String fieldValue = "";
  String user= "";

  user = (String)executeIvyScript(ownContext, getConfigurationProperty("User"));
  eventtyp = (String)executeIvyScript(ownContext, getConfigurationProperty("Event Typ"));
  linkId = (String)executeIvyScript(ownContext, getConfigurationProperty("Link-Id"));
  fieldValue = (String)executeIvyScript(ownContext, getConfigurationProperty("Feldwert"));

  // add your call here

  return out;
}

Complete Code sample

public class MyOwnPiBean extends AbstractUserProcessExtension
{
  /**
   * @see ch.ivyteam.ivy.process.extension.IUserProcessExtension#perform(ch.ivyteam.ivy.process.engine.IRequestId,
   *      ch.ivyteam.ivy.scripting.objects.CompositeObject,
   *      ch.ivyteam.ivy.scripting.language.IIvyScriptContext)
   */
  public CompositeObject perform(IRequestId requestId, CompositeObject in,
          IIvyScriptContext context) throws Exception
  {

    IIvyScriptContext ownContext;
    CompositeObject out;
    out = in.clone();
    ownContext = createOwnContext(context);

    String eventtyp = "";
    String linkId = "";
    String fieldValue = "";
    String user = "";

    StringTokenizer st = new StringTokenizer(getConfiguration(), "|");
    if (st.hasMoreElements())
      user = (String) executeIvyScript(context, st.nextElement().toString());
    if (st.hasMoreElements())
      eventtyp = (String) executeIvyScript(context, st.nextElement().toString());
    if (st.hasMoreElements())
      linkId = (String) executeIvyScript(context, st.nextElement().toString());
    if (st.hasMoreElements())
      fieldValue = (String) executeIvyScript(context, st.nextElement().toString());

    // do something with the values
    return out;
  }

  public static class Editor extends JPanel implements IProcessExtensionConfigurationEditorEx
  {
    private IProcessExtensionConfigurationEditorEnvironment env;
    private IIvyScriptEditor editorUser;
    private IIvyScriptEditor editorEventTyp;
    private IIvyScriptEditor editorLinkId;
    private IIvyScriptEditor editorFieldValue;

    public Editor()
    {
      super(new GridLayout(4, 2));
    }

    /**
     * Sets the configuration
     * @param config the configuration as an String
     */
    public void setConfiguration(String config)
    {
      StringTokenizer st = new StringTokenizer(config, "|");
      if (st.hasMoreElements())
        editorUser.setText(st.nextElement().toString());
      if (st.hasMoreElements())
        editorEventTyp.setText(st.nextElement().toString());
      if (st.hasMoreElements())
        editorLinkId.setText(st.nextElement().toString());
      if (st.hasMoreElements())
        editorFieldValue.setText(st.nextElement().toString());
    }

    /**
     * Gets the component attribute of the Editor object
     * @return this
     */
    public Component getComponent()
    {
      return this;
    }

    /**
     * Gets the configuration
     * @return The configuration as an String
     */
    public String getConfiguration()
    {
      return editorUser.getText() + "|" + editorEventTyp.getText() + "|" +
              editorLinkId.getText() + "|" + editorFieldValue.getText() + "|";
    }

    /**
     * @return boolean
     */
    public boolean acceptInput()
    {
      return true;
    }

    public void setEnvironment(IProcessExtensionConfigurationEditorEnvironment env)
    {
      this.env = env;
      editorUser = env.createIvyScriptEditor(null, null, "String");
      editorEventTyp = env.createIvyScriptEditor(null, null, "String");
      editorLinkId = env.createIvyScriptEditor(null, null, "String");
      editorFieldValue = env.createIvyScriptEditor(null, null);

      add(new JLabel("User"));
      add(editorUser.getComponent());
      add(new JLabel("Event Typ"));
      add(editorEventTyp.getComponent());
      add(new JLabel("Link-Id"));
      add(editorLinkId.getComponent());
      add(new JLabel("Feldwert"));
      add(editorFieldValue.getComponent());
    }
  }
}