PI (Programming Interface) Activity

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

Element Details

The Program Interface Activity integrates custom-made software, legacy systems, proprietary applications or any other external system through a Java interface into the process workflow.

Scope

If you just need to call some Java code within your workflow, it’s normally preferrable to do this via the Script Step.

If not only Java code must be called, but process logic, too, you are better off with calling a re-usable Callable SubProcesses that wraps your complex logic.

Furthermore, Callable SubProcess Start elements contain an expressive input/output parameter descriptor. This infrastructure often makes the need for a hand-crafted configuration Editor obsolete. In addition, these starts can be enriched with an illustrative logo and will appear prominently as connectors in the palette if tagged as such.

Still, there might be edge cases where you prefer the programmable element infrastructure. For instance as you like the style, and already built up knowledge on it while implementing a Program Start or a Wait Program Intermediate Event bean.

Inscription

Start Tab

On this tab you define the Java class to be executed.

Start tab

Java Class

Fully qualified name of the Java class that implements the IUserProcessExtension interface. Use the New Bean Class Wizard to create a new Java source file with an example implementation of the bean class.

Program

Defines the Error Start element which can handle execution errors.

Timeout

Defines a timeout for the return call to the Java PI class. A timout error can be handled by a catching Error Start.

Editor Tab

The custom editor UI provided by the implementation of IUserProcessExtension allows to configure its execution.

A custom editor example

Implementation

To initiate a custom bean implementation for your third party system, you start most conveniently by using the New Class button on the Start Tab. The wizard will create a minimal sample implementation that works already. You can then adjust it to your needs.

API reference

The Program Interface consumes a Java class that implements the IUserProcessExtension interface. This implementation is responsible for defining the element execution behavior in the method perform of IUserProcessExtension. The common way to implement a Program Interface Bean is to extend from AbstractUserProcessExtension.

Custom configuration

Very likely, your Program Interface Activity implementation will accept configuration parameters defining the local environment. For instance, a system specific file to send to a legacy system.

We help you with these configurations by providing an accessor for static element configurations via getConfigurationProperty().

Custom editor

To define your custom configuration on the process inscription mask, you must supply an inner Editor class implementation. We recommend to extend your implementation from UiEditorExtension.

This editor class is responsible for two things: Firstly, to create UI widgets, which display configuration values. And secondly, to map configuration data onto these widgets:

1. The initUiFields method supports you in creating widgets for the editor. Currently labels, scriptEditors and textEditors are supported.

2. The ConfigurableExtensionEditor provides methods to read and write configurations, in order to bind them to previously created ui widgets.

Example implementation

package com.axonivy.wf.custom;

import com.axonivy.erp.ErpFileService;

import ch.ivyteam.ivy.process.engine.IRequestId;
import ch.ivyteam.ivy.process.extension.impl.AbstractUserProcessExtension;
import ch.ivyteam.ivy.process.extension.ui.ExtensionUiBuilder;
import ch.ivyteam.ivy.process.extension.ui.IUiFieldEditor;
import ch.ivyteam.ivy.process.extension.ui.UiEditorExtension;
import ch.ivyteam.ivy.scripting.language.IIvyScriptContext;
import ch.ivyteam.ivy.scripting.objects.CompositeObject;
import ch.ivyteam.ivy.scripting.objects.File;

public class ErpLoader extends AbstractUserProcessExtension {

  @Override
  public CompositeObject perform(IRequestId requestId, CompositeObject in, IIvyScriptContext context) throws Exception {
    String pathScript = getConfigurationProperty(Config.PATH);
    File statistics = (File) executeIvyScript(context, pathScript);
    if (statistics.exists()) {
      ErpFileService.instance().reportStats(statistics);
    } else {
      getLog(context).warn("Failed to resolve statistics file from "+pathScript);
    }
    return in;
  }

  public static class Editor extends UiEditorExtension {

    private IUiFieldEditor filePath;

    @Override
    public void initUiFields(ExtensionUiBuilder ui) {
      ui.label("The CSV statistic to report to Acme.ERP:").create();
      filePath = ui.scriptField().requireType(File.class).create();
    }

    @Override
    protected void loadUiDataFromConfiguration() {
      filePath.setText(getBeanConfigurationProperty(Config.PATH));
    }

    @Override
    protected boolean saveUiDataToConfiguration() {
      clearBeanConfiguration();
      setBeanConfigurationProperty(Config.PATH, filePath.getText());
      return true;
    }
  }

  private static interface Config {
    String PATH = "path";
  }

}