SAP xMII Business Logic Services Integration Guide

SAP xMII Business Logic Services Integration Guide

SAP xApp Manufacturing Integration and Intelligence (SAP xMII) Business Logic Services is easily integrated with SAP xMII in a number of ways.  An SAP xMII Business Logic Services transaction may be called from SAP xMII to perform a background task, or you may retrieve data using an SAP xMII Business Logic Services transaction and return it to SAP xMII for display in a SAP xMII visual control.  Since XML is the core language of SAP xMII and of SAP xMII Business Logic Services, accessing and manipulating data via SAP xMII requests is fast and easy to implement.  Conversely, data obtained from other data sources, such as FTP, HTTP pages, databases, and flat files may be converted to XML format and used through SAP xMII as any other data source through the SAP xMII Business Logic Services connector.

To call a transaction for execution from SAP xMII is similar to calling any SAP xMII query.  In fact, you can create an SAP xMII Business Logic Services Query Template to send data to a transaction and/or return data to an SAP xMII object.  A number of examples are provided below to demonstrate SAP xMII Business Logic Services to SAP xMII integration methods.

SAP xMII XML Format

It is important to note that SAP xMII Business Logic Services returns XML in SAP xMII format.  This means that if you execute a transaction using the URL syntax above, you can access the results in any SAP xMII application (applets, reports, and such) using an XML Query Template with Source parameter.  To better understand SAP xMII XML format, an excerpt from the SAP xMII Help Documentation has been included below.

A complete discussion of this file structure requires a detailed discussion of XML which is beyond the scope of this document. What is important to note is that each data query results in an XML file organized in a tree hierarchy known as the "Document Object Model" or DOM.. This means that from a single starting point there are branches or "nodes" in the tree and each node can have its own child nodes and/or attributes.

It is important to note that XML is, by design, case-sensitive.  Thus, the outputted XML content must use the exact element/node names to function correctly.

The data XML file has three tree levels.  A well formed XML file can have only one top level node.  The SAP xMII top level node is "Rowsets".  Rowsets contains attribute values for the date the document was created, the software version, and the Start Date (SD) and End Date (ED) settings used by the query.  Rowsets has one or more immediate child nodes named "Rowset."  Each Rowset has two immediate children, "Columns" and "Rows".  The Columns and Rows nodes are similar to describing the data in a spreadsheet, or grid.

The Columns node contains one or more Column nodes that describe the data which will appear in each row. The "Columns" element contains "Column" elements describing what is called "metadata", or "data about data", for the information to follow.  There are a series of attributes for each column of data, describing the column name, source column (data source column name), description, data type, and permissible minimum and maximum ranges.

The Rows node contains the actual data returned by the query object.  Each individual set of data, or "row" corresponding to the columns described in the Column node is returned as a separate data element within a Row node, and this Row node contains elements corresponding to each column/data value.

Passing Parameters to a Transaction

You may also pass parameters to a transaction, just like you would to any SAP xMII query.  In order to pass parameters to a transaction, you need to define one or more Transaction Properties within the transaction definition.  A Transaction Property is a "public variable" within the transaction.  By passing in different values, you can change the execution of the transaction.  This is an important concept in creating reusable transactions, and minimizing repetitive transactions for better maintainability.  

When you define an Xacute query, you just need to map the default SAP xMII Query Parameters, Param.1 through Param.32, into the appropriate Transaction Properties.

Constructing an Xacute Query Template to Call SAP xMII Business Logic Services

To tie a transaction into SAP xMII, we need only create an Xacute Query template using the Template Editor.  To do this, open the Template Editor and select New, then Xacute Query.  The data source defaults to the SAP xMII Business Logic Services Connector, and the mode defaults to Query.  Use the Query mode to get the results of a transaction into an SAP xMII visual component.

On the Transaction tab, select the appropriate transaction.  The output will default to * (All).  If you want a specific output parameter, you may select it, such as a properly formatted SAP xMII XML document.  If needed, you can apply a formatting stylesheet to any XML document via the transform tab.

Mapping Query Parameters to Transaction Properties

Let's assume you have an transaction properties for start date, end date, and lot ID named LotStartDate, LotEndDate, and MaterialLotID, respectively.  If you wish to dynamically set these values via the query template, you would need to use a combination of mapped parameters and mapped date parameters.  This allows you to name the transaction properties however you wish.  The SAP xMII query parameters must be Param.1 through Param.32.  In order to link the user defined SAP xMII Business Logic Services transaction property names to SAP xMII query parameters, you must use mapped parameters.

In the above example, you would set MappedParamTarget.1 = MaterialLotID.  You could also specify a value in order to test the query.  You would specify LotStartDate as the StartDateMappedParam and LotEndDate as the EndDateMappedParam via the Set buttons next to the appropriate text boxes.  By mapping the start and end dates, you can use all the built-in applet date handling functions, including the applet "VCR" buttons.

The SAP xMII Business Logic Services Connector also has a parameter that you can use for "automated mapping" named AutoBind.  If this parameter is set to true, when the transaction is called by the Xacute Query, the connector will attempt to map any session variables into transaction properties with the same name.  

Using The Xacute Query Template To Build Your Application

Note that this now gives us the ability to use this from ANY SAP xMII software components, including the applets, reports, Web pages, KPIs/alerts, and quality engine. This is an extremely powerful capability and is the preferred way to deliver data from SAP xMII Business Logic Services to a Web page. Of course, there will be times when an SAP xMII Business Logic Services transaction is intended to perform some transactional function (log data, upload data to a business system, send an e-mail) in which case no "data" is typically returned. You can use the SAP xMII iCommand applet in your Web page or direct URL calls to SAP xMII from an HTML form to access the all of the power of SAP xMII Business Logic Services from your own Web pages! If you wish to return data from a transaction to an SAP xMII applet, see Returning Data to SAP xMII from a Transaction below, or refer to the SAP xMII Xacute Query Guide.

Returning Data to SAP xMII from a Transaction

The most important requirement to returning data to SAP xMII from SAP xMII Business Logic Services is that the resultant output be in "SAP xMII XML format". Recall that there are two ways to do this:

First, if you have transaction output parameters that are of the following data types - Boolean, Integer, Double, DateTime, or String - you can simply specify the desired output parameter using the "OutputParameter" property in the URL request to SAP xMII Business Logic Services. As mentioned earlier in this section, you can also specify a "wildcard" value with an asterisk (*) to return all non-XML output parameters. In both cases, SAP xMII Business Logic Services will create a properly structure SAP xMII XML output document for you.

Secondly, you may create an XML document with your SAP xMII Business Logic Services transaction, and specify the transaction output parameter corresponding to this XML document as the "OutputParameter" in the URL. Within your SAP xMII Business Logic Services transaction, there are a number of ways to create SAP xMII XML formatted output, including XSL transformations and the SAP xMII Output actions.

Once data is returned to SAP xMII via an Xacute Query template, this data is now available to be used in the KPI/Alerting module, quality analyses, applets such as charts, grids and tickers, SAP xMII report pages, custom HTML pages, and even to other applications (custom Java or VB applications for example) via URL requests to SAP xMII.

Calling an SAP xMII Business Logic Services Transaction via a URL

An execute request to an SAP xMII Business Logic Services transaction has the following base URL:

http://<servername>/Lighthammer/Runner?

You can pass any number of parameters into an SAP xMII Business Logic Services transaction.  Depending on how you have designed the transaction, and the number of transaction properties that you have defined, you may have different parameters for each transaction (examples will be shown below).  However, there are predefined command line parameters that may be passed into the SAP xMII Business Logic Services Web Service, independent of the transaction that you are calling, which are shown in the following table:

Parameter

Data Type

Possible Values

Description

Transaction

String

 

This is the folder and transaction name for the transaction you wish to run.  For transactions in the root folder, only the transaction name is needed. The correct syntax is FOLDER/TRANSACTIONNAME (note the use of the forward slash).

InputParameter

String

 

If you wish to post a document to the SAP xMII Business Logic Services transaction, you must specify which transaction property you wish to write the document to.  You use this parameter to specify the name of the appropriate transaction property.  See the section on Posting a Document to a Transaction below for more information.

OutputParameter

String

 

You can pass a specific transaction property value back from a transaction.  Use this parameter to specify which property value you wish returned.   A wildcard value is available as a value for this parameter:  If you pass in a value of "*", all non-XML data type transaction property values will be returned.  For XML data type transaction variables, they may only be output one at a time by explicitly referencing them with this parameter.

XacuteLoginName

String

 

To call a transaction via a URL when SAP xMII Authentication is enabled, you must pass a user name and password.  This parameter specifies the user name.

Note: this information is NOT required if you are calling SAP xMII Business Logic Services via the localhost Web server (as you typically would when calling SAP xMII Business Logic Services from within SAP xMII).

XacuteLoginPassword

String

 

This parameter specifies the password associated with the user name supplied via the XacuteLoginName parameter.

Content-Type

String

  • text/xml

  • text/html

  • image/xxx

A response content-type of text/xml is the default.  If you wish to return HTML content or image content, you can do so by selecting the appropriate MIME type and specifying the appropriate OUtputParameter value. Note that for HTML output, the output parameter should be of a string or XML type (if XML, the XML document should consist of HTML tags and content). For image output, the output parameters should be a string type corresponding to the EncodedImage value returned from one of the SAP xMII Business Logic Services actions that loads/generates image output.

 

To execute a specific transaction from a browser, the URL should utilize the following format (in this case calling a transaction named YieldCalc in the Test folder, passing a value of 10.0 to the YieldFactor input parameter, and requesting that the transaction property named YieldAverage be returned as the output):

http://<servername>/Lighthammer/Runner?Transaction=Test/YieldCalc&YieldFactor=10.0&OutputParameter=YieldAverage

The default response, if this URL was called via a browser, would look like the following:

Passing Parameters to a Transaction via a URL

You may also pass parameters to a transaction over the URL, just like you would when calling an SAP xMII query via a URL.  As stated above, in order to pass parameters to a transaction, you need to define one or more Transaction Properties within the transaction definition.

Let us suppose we wish to obtain all of the news articles associated with a particular stock ticker symbol. We have created an SAP xMII Business Logic Services transaction that calls a Web service to gather this information, and are returning the news headlines, and URL links to the news articles in an SAP xMII document output. We created a transaction-level input parameter called "Ticker" that is used to pass the stock ticker symbol to the SAP xMII Business Logic Services transaction, and a transaction output parameter called "Results" that contains the desired data to be sent back to the requester. The URL to call this transaction would look like:

http://<servername>/Lighthammer/Runner?Transaction=StockNews&OutputParameter=Results&Ticker=MSFT

Posting a Document to an SAP xMII Business Logic Services Transaction

If you wish to post a document to the SAP xMII Business Logic Services transaction, you must specify which transaction property you wish to write the document to.  Let's look at an example.

Suppose that you have a third party application, such as an XML based enterprise application integration tool.  If you want to send data from that tool to a plant system (such as a production schedule) or show that information within the SAP xMII portal, you would need to post the XML document with the relevant information to an SAP xMII Business Logic Services transaction.

Let's assume that the transaction is named ProductionOrders .  Within that transaction would be a property named OrderDoc, with a data type of XML.  In order to execute the transaction and post the correct document, you would need to post the document to the following URL:

http://<servername>/Lighthammer/Runner?Transaction=ProductionOrders&InputParameter=OrderDoc

The SAP xMII Business Logic Services transaction would take the posted document and place it into the transaction property OrderDoc, which you could then access within the execution of the transaction.