Developing Custom Actions in SAP MII 14.

Document Version 1.2 - November 11, 2012

 Developing Custom Actions in SAP MII 14.0

© Copyright 2009 SAP AG. All rights reserved. NetWeaver, and other SAP products and services mentioned
herein as well as their respective logos are trademarks or
No part of this publication may be reproduced or registered trademarks of SAP AG in Germany and in several
transmitted in any form or for any purpose without the other countries all over the world. All other product
express permission of SAP AG. The information contained and service names mentioned are the trademarks of their
herein may be changed without prior notice. respective companies. Data contained in this document
Some software products marketed by SAP AG and its serves informational purposes only. National product
distributors contain proprietary software components of specifications may vary.
other software vendors. These materials are subject to change without notice.
These materials are provided by SAP AG and its affiliated
Microsoft, Windows, Outlook, and PowerPoint are companies (“SAP Group”) for informational purposes
registered trademarks of Microsoft Corporation. only, without representation or warranty of any kind, and
IBM, DB2, DB2 Universal Database, OS/2, Parallel SAP Group shall not be liable for errors or omissions with
Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400, respect to the materials. The only warranties for SAP Group
iSeries, pSeries, xSeries, zSeries, System i, System i5, System products and services are those that are set forth in the
p, System p5, System x, System z, System z9, z/OS, AFP, express warranty statements accompanying such products
Intelligent Miner, WebSphere, Netfinity, Tivoli, Informix, and services, if any. Nothing herein should be construed as
i5/OS, POWER, POWER5, POWER5+, OpenPower and constituting an additional warranty.
PowerPC are trademarks or registered trademarks of IBM
Corporation. This document was created using stylesheet 2006-06-15
Adobe, the Adobe logo, Acrobat, PostScript, and Reader (V4.3) and XSLT processor SAXON 6.5.2 from Michael Kay
are either trademarks or registered trademarks of Adobe (http://saxon.sf.net/), XSLT version 1.
Systems Incorporated in the United States and/or other
countries. Disclaimer
Oracle is a registered trademark of Oracle Corporation. Some components of this product are based on Java™. Any
UNIX, X/Open, OSF/1, and Motif are registered code change in these components may cause unpredictable
trademarks of the Open Group. and severe malfunctions and is therefore expressively
Citrix, ICA, Program Neighborhood, MetaFrame, prohibited, as is any decompilation of these components.
WinFrame, VideoFrame, and MultiWin are trademarks or Any Java™ Source Code delivered with this product is
registered trademarks of Citrix Systems, Inc. only to be used by SAP’s Support Services and may not be
HTML, XML, XHTML and W3C are trademarks modified or altered in any way.
or registered trademarks of W3C®, World Wide Web
Consortium, Massachusetts Institute of Technology.
Java is a registered trademark of Sun Microsystems, Inc. Documentation in the SAP Service Marketplace
JavaScript is a registered trademark of Sun Microsystems, You can find this documentation at the following Internet address:
Inc., used under license for technology invented and service.sap.com/instguides

implemented by Netscape.
MaxDB is a trademark of MySQL AB, Sweden.
SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP

2
 Developing Custom Actions in SAP MII 14.0

Table of Contents
1 Overview .......................................................................................................................................................................... 4
2 Background ..................................................................................................................................................................... 4
3 Annotations ...................................................................................................................................................................... 4
3.1 Action ..................................................................................................................................................................... 4
3.2 Outputs................................................................................................................................................................... 5
3.3 Input ....................................................................................................................................................................... 5
3.4 ConfigurationDialog ................................................................................................................................................ 6
3.5 DefinesAccompanimentData .................................................................................................................................. 6
4 Interfaces ......................................................................................................................................................................... 7
4.1 IActionInstance ....................................................................................................................................................... 7
4.2 IAccompanimentData ............................................................................................................................................. 7
4.3 IReferenceDocumentGenerator ............................................................................................................................. 7
4.3.1 Definition ............................................................................................................................................................ 8

4.4 IActionConfiguration ............................................................................................................................................... 8

4.5 IConfigurationDialog ............................................................................................................................................... 9
5 Class.............................................................................................................................................................................. 10
5.1 BaseConfigurationDialog ...................................................................................................................................... 10
6 Enumerations................................................................................................................................................................. 10
6.1 ActionRetention .................................................................................................................................................... 10
7 Deployment ................................................................................................................................................................... 11
7.1 Simple Action ....................................................................................................................................................... 12
7.2 Reference Document Generator .......................................................................................................................... 13
7.3 Accompaniment Data ........................................................................................................................................... 15
7.4 Configuration Dialog ............................................................................................................................................. 16

3
 Developing Custom Actions in SAP MII 14.0

1 Overview
Many users of SAP Manufacturing Integration and Intelligence (SAP MII) need special operations that are not provided by
SAP MII. These operations may include special calculation mechanisms or specific communication functions. The purpose
of this document is to summarize how a Java developer can create custom actions for such operations.

2 Background
Custom actions have been available to SAP MII users since its inception through custom interfaces and helper classes. Due
to the major architectural changes to the core SAP MII Business Logic Services (BLS) Engine, these older interfaces have
been deprecated and could cease to function in a future release. No end date has been determined at the release of this
document. Custom actions developed prior to SAP MII 12.1 will work in 12.1; however, they will run slower than 12.1
custom actions because a legacy action layer translates the calls to the 12.1 methodology.

There have been many changes to the 12.1 custom action APIs, which make actions easier to develop and maintain. These
features require the Java 1.5 JVM, especially the generic and annotation constructs.

3 Annotations

3.1 Action
The Action annotation identifies a method as an action.

Parameter Type Description

name† String Name of the action

icon String Location of the icon in the class path

retention ActionRetention Specifies if the action runs in a particular

execution state or not. Defaults to ALWAYS.

forceOutputLinks boolean If set to True, it forces the action to expose and

run output links. Default setting is False.

referenceDocumentGenerator Class implementing Declares the class needed to generate a

IReferenceDocumentGenerator
reference document. Used in design time only.
Defaults to a generator that produces no
reference documents.
†Required parameter

4
 Developing Custom Actions in SAP MII 14.0
3.2 Outputs
The Outputs annotation is used to describe the known output of an action at compile time. You can also create dynamic
outputs (see the IActionConfiguration interface). If there are defined outputs, this annotation is required..

Parameter Type Description

names† String[] Holds the array of output names

types† VariantDataTypes[] Holds the array of types corresponding to

the names
†Required parameter

NOTE: The types and names arrays must be the same size, and the order of the names corresponds to the order of the
types.

3.3 Input
The Input annotations are put on the parameters for the action method and describe the inputs to the action. All parameters,
except the IActionInstance, must have this annotation attached or the loading of the action fails.

The allowable types for action parameters include those described in the VariantDataTypes enumeration, the
VaraintData, and one IActionInstance parameter. If you use the VariantData as a parameter, you
should specify the annotations type parameter.

Parameter Type Description

name† String Holds the name of the parameter as the

user sees it. This name does not need to
be identical to the methods parameter
name.

defaultValue String Holds the parameter default value as a

string. If the parameter type is not a string,
the BLS engine automatically cases this
value. If this annotation parameter is not
specified, and if the value is not overridden,
the system uses the default value for the

5
 Developing Custom Actions in SAP MII 14.0
type.

type VariantDataTypes Holds the array of types corresponding to

the names
†Required parameter

3.4 ConfigurationDialog
You use the ConfigurationDialog annotation to create a configuration dialog so the user can set action parameters. If you
annotate the action method with this annotation and do not define a dialogClass, you will create a default configuration
dialog in which all inputs are configurable.

Parameter Type Description

dialogClass Class implementing References the class to use as

IConfigurationDialog
the dialog class

3.5 DefinesAccompanimentData
This annotation tells the engine that an IAccompanimentData object will be created by this action. The engine
makes it easier for downstream actions to reference the action. The action can create any name for the
IAccompanimentData interface; however, it is standard to call the object by the object instance name, which is
acquired through IActionInstance.getName().

Parameter Type Description

Guids String[] The list of GUIDs used to identify

the IAccomanimentData
class. For constraint information,
see
IAccompanimentData.

6
 Developing Custom Actions in SAP MII 14.0

4 Interfaces

4.1 IActionInstance
This is the main runtime state model for the action instance. It contains methods for retrieving and updating state
information. The action developer does not implement this interface, the engine implements it.

«interface»
IActionInstance

getTransactionInstance() : ITransactionInstance
getTransactionName() : String
getUser() : User
getLocalServiceConnection() : LocalServiceConnection
createRemoteServiceConnection(String, boolean) : RemoteServiceConnection
createRemoteServiceConnection(String) : RemoteServiceConnection
getAccompanimentData(String) : IAccompanimentData
setAccompanimentData(IAccompanimentData, boolean) : boolean
containsAccompanimentData(String) : boolean
setActionResults(String, $value$) : boolean
getActionVariable(String) : VariantData
containsActionVariable(String) : boolean
getActionVariableMap() : Map<String, VariantData>
getFullyQualifiedVariable(String) : VariantData

4.2 IAccompanimentData
If a complex stateful object must be shared by multiple actions, or multiple action calls, the action developer should
implement this interface.

«interface»
IAccompanimentData

dispose() : void
getUniqueId() : String
<Named>.getName() : String
<Named>.cloneNamed() : Named

4.3 IReferenceDocumentGenerator
This interface generates the reference document that helps the user develop links. The returned document is typically an
XML document that requires external lookup.

You can access this functionality by clicking the object with your secondary mouse button and choosing Generate Sample
or Clear Sample.

7
 Developing Custom Actions in SAP MII 14.0

com.sap.xmii.bls.sdk

«interface»
IReferenceDocumentGenerator

generate(IActionInstance) : boolean
clear(IActionInstance) : void
showGenerationDialog(Window, IActionConfiguration) : void

4.3.1 Definition
Method Description

generate Called when the user calls the Generate Sample operation. The return
from this method indicates if the operation was successful (true) or not
(false).

clear Called when the user calls the Clear Sample operation

showGenerationDialog Typically called after the configuration dialog is closed. This allows for
better interaction than requiring the user to close the dialog and select
Generate Sample.

4.4 IActionConfiguration
This interface is used as a configuration mechanism for the actions. It is only available at design time and assists the
IConfigurationDialog.

8
 Developing Custom Actions in SAP MII 14.0
«interface»
IActionConfiguration

getStaticInputs() : List<String>
getStaticInput(String) : VariantData
setStaticInput(String, VariantData) : void
getActionType() : String
getHelpFile() : String
getServiceConnection() :ServiceConnection
getDynamicInputNames() : List<String>
getDynamicOutputNames() : List<String>
getDynamicValue(String) :VariantData
setDynamicValue(String, VariantData, boolean) : void
removeDynamicValue(String name) : void
flushDynamicValues() : void
getAccompanimentDataNames(String) : List<String>
lookupConfiguration(String) : IActionConfiguration
getVariables() : ActionObjects

4.5 IConfigurationDialog
If you use the BaseConfigurationDialog as a base class, you do not need to implement this interface.

«interface»
IConfigurationDialog

initialize(IActionConfiguration, CommonLocalizer) : void

showDialog(Window) : ActionDialogResult
loadLinks(IActionConfiguration, CommonLocalizer)

4.6 IAdminInstance
You get the localized text for a key by providing inputs for the language, project and key to the method getLocalizedString()
of the IAdminInstance interface.

<<interface>>

IAdminInstance

getConnection(String name,RemoteConnectionType type): Map<String, String>

getCredential(String aliasName): NamedVariantData

getLocalizedString(String language, String project, String key): String

9
 Developing Custom Actions in SAP MII 14.0
5 Class

5.1 BaseConfigurationDialog
This class uses a basic configuration dialog to implement the IConfigurationDialog interface. You can use this
method as a base for any dialog you need to create.

6 Enumerations

6.1 ActionRetention
This enumeration determines if an action should be put into the execution tree.

Value Description

DEBUG_ONLY Run the action in debug environments only

ALWAYS Run the action in both debug and production environments

10
 Developing Custom Actions in SAP MII 14.0

7 Deployment
To deploy custom actions you need to zip all class files into a JAR and add a catalog.xml file to the root folder of the JAR.
Once the JAR is complete, you can add the JAR to SAP MII at System Management → Custom Actions.

The following is an example of a catalog.xml file:

<?xml version = "1.0" encoding="utf-8" ?>
<ComponentCatalog>
<Category Name="BlackBerry" Description="BlackBerry">
<Component Type="Action"
Name="AddTwoNumbers"
Description=""
Label="CustomActionSample"
ClassName="customactions.SimpleActions"
AssemblyName="CustomAction.jar"
HelpFileName="" />
</Category>
</ComponentCatalog>

Note: You can add multiple actions to the catalog.xml by adding more component nodes.

11
 Developing Custom Actions in SAP MII 14.0
Examples

7.1 Simple Action

package customactions;

import com.sap.lhcommon.common.*; // Needed for the VariantDataTypes and

//VariantData types.
import com.sap.xmii.bls.sdk.*; // This is the main SDK for custom actions.

/**
* This is a simple action construct used to show how to use some of the basic
* MII 12.1 Custom Action constructs.
*
*/
public class SimpleActions {

/**
* To ensure the parameters are always named the same, it is good practice to
* create a static final string with the parameters name. This also make it
* easy to use across actions.
*/
private static final String PARAM_OUTPUT = "Output";
/**
* Describes a simple action that adds two numbers together.
* @param instance This is the action instance. This is the main interface
* from the action code back into the transaction engine. Most
* users will only need to set their variables through this
* interface, though much more powerful operations are also
* available.
* @param in1 This is an input into the action. The type is detected by the
* transaction engine and automatically cast to the correct value.
* @param in2 This is a second input.
* @throws InvalidVariableException This exception is
*/
@Action(name = "AddTwoNumbers" ,
referenceDocumentGenerator = ReferenceDocumentGenSample.class) // This annotation
tells the engine that this
// is an action available to execute.
@Outputs(names = { PARAM_OUTPUT },
types = { VariantDataTypes.INTEGER }) // This annotation tells
// the engine that one
// integer output called
// 'Output' is going to be
// returned.
@ConfigurationDialog(dialogClass = SimpleConfigurationDialog.class, localizationType =
ConfigurationDialogLabelLocalizationType.BUILT_IN)
// This annotation tells the engine the class that implements IConfigurationDialog.
public static void addTwoNumbers(
IActionInstance instance, // Besides the basic types, the
// IActionInstance interface is the only
// other type allowed to be defined in
// parameter list of a custom action.
@Input(name = "Input1") int in1, // @Input annotations are used to
// indicate the user modifiable
// inputs to this action.
@Input(name = "Input2") int in2)
throws InvalidVariableException {// Exceptions can be thrown directly from
// the actions without causing critical
// execution failures. These exceptions
// will be caught and logged by the engine

12
 Developing Custom Actions in SAP MII 14.0
// and will cause the Success flag to be
// set to false.
// The following code describes how to set an actions output.
try {
instance.setActionResult(PARAM_OUTPUT, in1 + in2);
} catch (Exception e ) {
// Do what you like.
}
}
}

7.2 Reference Document Generator

package customactions;

import java.awt.*;
import javax.swing.*;
import org.w3c.dom.*;
import com.sap.lhcommon.common.*;
import com.sap.lhcommon.exceptions.*;
import com.sap.lhcommon.xml.*;
import com.sap.xmii.bls.sdk.*;
/**
* This is a sample for generating reference documents. It simply adds the
* following XML:
*
* <? xml version="1.0" encoding="UTF-8 ?>
* <Sample>This is some data to store.</Sample>
*
*/
public class ReferenceDocumentGenSample implements IReferenceDocumentGenerator {
/**
* Clear the configuration of this sample document.
*/
public void clear(IActionConfiguration configuration) {
try {
configuration.setStaticInput("Output",
new VariantData(new XMLDataType()));
} catch(DataConversionException e) {
configuration.setStaticInput("Output", new VariantData());
}
}
/**
* Generate the sample documents.
*/
public boolean generate(IActionConfiguration configuration) {
boolean succceeded = false;
try {
Document doc = XMLHandler.createDocument();
Element elem = doc.createElement("Sample");
doc.appendChild(elem);
elem.appendChild(doc.createTextNode(
"This is some data to store."));
configuration.setStaticInput("Output",
new VariantData(new XMLDataType(doc)));
succceeded = true;

13
 Developing Custom Actions in SAP MII 14.0
} catch(DataConversionException e) {
configuration.setStaticInput("Output", new VariantData());
}
return succceeded;
}
/**
* Show a dialog asking if the reference document should be generated.
*/
public void showGenerationDialog(Window parentWindow,
IActionConfiguration configuration) {
if (JOptionPane.showConfirmDialog(parentWindow,
"Do you want to generate a sample document?") ==
JOptionPane.YES_OPTION) {
generate(configuration);
}
}

/**
* Generate the reference documents upon initialization from the configuration.
*/
public boolean initialize(IActionConfiguration configuration)
{
return true;

14
 Developing Custom Actions in SAP MII 14.0
7.3 Accompaniment Data
package customactions;

import com.sap.lhcommon.common.*;
import com.sap.xmii.bls.sdk.*;

/**
* A simple accompaniment data sample.
*/
public class SimpleAccompanimentData implements IAccompanimentData {

/**
* Defines the serialization version.
*/
private static final long serialVersionUID = 1L;

/**
* Defines the StatisticsMemory id.
*/
public static final String UID = "054BC6DC-07AE-4cc0-A818-D5881A494268";

/**
* The object to store in this accompaniment data object.
*/
private Object storedObject;

/**
* The name of this object.
*/
private final String name;

/**
* Creates this object with a member to store.
* @param storedObject The object to store
*/
public SimpleAccompanimentData(Object storedObject, String name) {
this.storedObject = storedObject;
this.name = name;
}

/**
* dispose of the object.
*/
public void dispose() {
this.storedObject = null;
}

/**
* Get the unique id for this object type.
*/
public String getUniqueId() {
return UID;
}

/**
* clone this object.
*/
public Named cloneNamed() {
return new SimpleAccompanimentData(this.storedObject, this.name);
}

/**
* Get the objects name.
*/
public String getName() {
return this.name;
}
}

15
 Developing Custom Actions in SAP MII 14.0

7.4 Configuration Dialog

package customactions;

import java.awt.*;
import javax.swing.*;

import com.sap.lhcommon.common.*;
import com.sap.lhcommon.exceptions.*;
import com.sap.xmii.bls.sdk.*;

/**
* A simple dialog.
*/
public class SimpleConfigurationDialog extends BaseConfigurationDialog {

private static final long serialVersionUID = 1L;

private JTextField input1;

private JTextField input2;
/**
* Creates the Tracer Action dialog.
*/
public SimpleConfigurationDialog() {
super(475, 250);
input1 = new JTextField(10);
input2 = new JTextField(10);
}
/**
* @see com.sap.xmii.bls.sdk.BaseConfigurationDialog#load()
*/
@Override
protected void load() {
JPanel mainPanel = new JPanel(new GridBagLayout());
GridBagConstraints c = new GridBagConstraints();

c.gridy = 0;
c.weightx = 0.1;
c.fill = GridBagConstraints.NONE;
mainPanel.add(new JLabel("Input1"), c);
c.weightx = 0.9;
c.fill = GridBagConstraints.HORIZONTAL;
mainPanel.add(input1, c);

c.gridy = c.gridy + 1;
c.weightx = 0.1;
c.fill = GridBagConstraints.NONE;
mainPanel.add(new JLabel("Input2"), c);
c.weightx = 0.9;
c.fill = GridBagConstraints.HORIZONTAL;
mainPanel.add(input2, c);

getContentPane().setLayout(new GridBagLayout());
GridBagConstraints e = new GridBagConstraints();
e.gridy = 0;
e.weightx = 1.0;
e.weighty = 1.0;
e.fill = GridBagConstraints.BOTH;
getContentPane().add(mainPanel, e);

e.gridy = e.gridy + 1;
e.weightx = 1.0;
e.fill = GridBagConstraints.NONE;
e.anchor = GridBagConstraints.LINE_END;
createOKCancelPanel(this, e);

String option1 = "256";

16
 Developing Custom Actions in SAP MII 14.0
String option2 = "256" ;
try {
option1 = this.getConfiguration().getStaticInput("Input1").stringValue();
option2 = this.getConfiguration().getStaticInput("Input2").stringValue();
} catch(DataConversionException x) {}
input1.setText(option1);
input2.setText(option2);
}
/**
* @see com.sap.xmii.bls.sdk.BaseConfigurationDialog#saveData()
*/
@Override
protected void saveData() {
try {
this.getConfiguration().setStaticInput("Input1", new
VariantData(Integer.parseInt(input1.getText())));
this.getConfiguration().setStaticInput("Input2", new
VariantData(Integer.parseInt(input2.getText())));
} catch (Exception e) {};
}

17