Defining business objects to enable the bidirectional information flow

You can use the parameter documentation of a business object to define how a bidirectional flow can be set up between the SAP transaction in the SAP HTML user interface and the process instance in IBM® BPM.

About this task

Each parameter of the business object is bound to one or more HTML elements in the SAP transaction screen. The binding information is provided as one or more descriptors in the Documentation field of each parameter.

To learn more about how to define descriptors and selectors to enable the bidirectional information flow, review the following information and the example provided later in this topic.

Parent topic: Enabling the information flow between the SAP transactions and IBM BPM

Defining descriptors

About this task

The following descriptors can be manually specified in the documentation of each parameter.
Table 1. Descriptors that can be defined manually in the parameter documentation
Descriptor Description Valid Values Default Value Sample
selector A mandatory CSS selector that specifies the location of the HTML element. ANY EMPTY selector = span[id='helloworld']
input A boolean parameter that specifies whether the transaction parameter is of input or output type. true or false true input=false
readonly When readonly is set to true, the located HTML element cannot be manually modified. true or false false readonly=true
required When required is set to true, the captured value of this parameter cannot be empty, otherwise the activity cannot be completed. It is applicable only when the input is set to false. true or false false required=true
extractregex A regular expression that extracts the value from the selected HTML element. For more information, see Regular Expressions. ANY EMPTY extractregex =\s\d+?(?=has been saved)

Extracts an integer string before the string "has been saved" from the captured value.
format A regular expression that formats the output value. If the data does not conform to the format, the value is ignored. For more information, see Regular Expressions. ANY EMPTY format=1\d+

The value must be an integer string starting with 1.
exclude A JSON array that specifies what value or values must be ignored. If the captured value is within the array, it is ignored. ANY JSON array EMPTY JSON array exclude=[‘exclude1’, ‘exclude2’]

The values ‘exclude1’ and ‘exclude2’ are ignored.

Defining selectors

About this task

Use the CSS selector to locate the HTML element in which you want to prefill data or from which you want to capture data. Some development skills are required to define the selector. To locate the target HTML element, you can use an identifier attribute of the HTML element or of its parent. Using the located HTML information, you can then use selector patterns to define the selector descriptor.

HTML content in monitored elements

About this task

To locate the HTML content of a target element, complete the following steps in Mozilla Firefox:

Procedure

  1. Open Mozilla Firefox.
  2. Click Tools > Web Developers > Inspector. The Inspector perspective opens.
  3. Click the Select element with mouse icon Select element with mouse icon in the upper left corner of the Inspector perspective window.
  4. Select the element that you want to monitor, and then locate the HTML content of the selected element.

Selector patterns

About this task

Some of the patterns that can be used to define the final selector descriptor are provided in the following table. However, the selector definition can be very flexible.

The selector definition is used to locate the HTML element that you want to monitor. Each HTML element can have many valid selectors. To choose the correct selector, ensure that the CSS selector can be used to locate what you want. For more information, see the CSS Selector reference.

Table 2. Summary of selector patterns
Condition Pattern Sample Element Sample Selector
If the selected element has a unique ID attribute 
{tagName}[id=’{ID Value}’]
 
<input id=”inputid” type=”text”/>
 
selector=input[id=’inputid’]
If the parent of the selected element has a unique ID 
{parent’s tagName}[id=’{parent’s ID}’] > {tagName}:nth-child ({child index})
 
<div id="parent">
	<div class="child">
	<div class="child"></div>
</div>
 
selector=div[id=’parent’] > div: nth-child(2)
If the selected element has a unique attribute value that can be used as an identifier 
{tagName}[{attributeName}={attributeValue}]
 
<div class="a"></div>
<div class="a" unique="b"></div>
 
selector=div[unique=’b’]
If the attribute value varies in different systems, but contains a consistent part. For example, "myuni1" and "myuni2" are possible values of the attribute, but both contain 'myuni'. 
{tagName}[{attributeName}*={attributePattern}]
 
<div class=”a” unique=”myuni1”></div>
 
selector=div[unique*=’myuni’]
If this parameter corresponds to a table column 
{table selector} > tbody>tr>td:nth-of-type({column index})
 
<table id="tableId">
<tbody>
<tr><td></td><td></td></tr>
<tr><td></td><td></td></tr>
<tr><td></td><td></td></tr>
</tbody>
</table>
 
selector=table[id='tableId']>tbody>tr>td:nth-of-type(2)

Example

About this task

The following example illustrates how the parameter documentation for the CreateOrder and CreateOrder_Material business objects can be used to prefill data in Transaction VA01 and capture data from it.

Table 3. Parameter documentation for the CreateOrder and CreateOrder_Material business objects
Business Object: CreateOrder
Parameter Documentation
DistributionChannel 
input=true 
selector=input[id*='__AGIM0:U:::6:22']
Division 
input=true 
selector=input[id*='__AGIM0:U:::7:22']
NetValue 
selector=input[id*='input#__AGIM0:U:1::0:56'] 
input=false 
exclude=['0,00']
orderId 
selector=span[id=‘messagebar’]
input=false
required=true
extractRegex=\d+
exclude=['0,00']
Business Object: CreateOrder_Material
Parameter Documentation
quantity 
input=true
selector=[id='__AGIM0:U:2:3:2:1-mrss-cont-none-content']>tbody>tr>td:nth-of-type(1)
material 
input=true
selector=[id='__AGIM0:U:2:3:2:1-mrss-cont-left-content']>tbody>tr>td:nth-of-type(3)