The Program Interface Step element is located in the Activity drawer of the process editor palette.
This element is one of Xpert.ivy facilities 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 must implement the
interface
IUserProcessExtension
and will call the method
perform
each time a process comes to 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. You will find the documentation of the
interface and the abstract class in the Java Doc of the Xpert.ivy Public API.
Since Xpert.ivy 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.
This tab is included in the mask of all process elements and contains the name and a description of the element. See Name Tab for a more detailed description.
On this tab you set the Java class which implements the interface
IUserProcessExtension
which is called when the PI step is
executed. Furthermore, you can define exception handlers to react on errors such as
not reachable systems, insufficient privileges and many more.
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.
You can add a graphical configuration editor for the Java call (i.e. setting the parameter values) on the PI inscription mask. See section Tab Editor for more details.
The Exception step which is executed whenever errors during the call to the PI Java class or during the execution of the class are returned.
Sets a timeout for the return call to the Java PI class. When the timeout ends without an answer from the PI class, then the Exception step below is executed
The Exception step which is executed whenever the timeout ends without an answer from the PI call.
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 has smart buttons which provide access to the process
data, environment functions and Java classes.
Here is an example of such an editor:
As you can see, the editor provides you access to any process relevant data, which 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 editor shown above. As mentioned above
Xpert.ivy provides the
IIvyScriptEditor
which 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 set them to 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 the 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; }
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; /** * Constructor for the Editor object */ 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()); } } }