
	Version 2.3.1.18	SEARCH CONTENTS \| PDF BOOKS \| HOME UP PREV NEXT

— SAP R/3 Gateway Documentation —

Software Development Kit

The Software Development Kit describes XSLT extensions to develop your own stylesheets for pipeline processing. There are 2 different functions in XSLT:

XPath function
element extension call.

The calling convention differs between the types. The XPath function requires parameters and the element extension requires attributes. In the function definition there is an example of how to call and use it. The XSLT function can distinguish between categories for

sending and receiving UOWs,
providing error and status information,
handling UOW transactions,
logging,
exchanging documents via HTTP and
getting system or HTTP-Get parameters.

The extension functions are described in detail:

Expanding xsl:stylesheet Header
Trace UOW function
Receiving UOW
Sending UOW
Getting Status Information
UOW Transaction Handling
Logging
Sending Mail
Exchange Document
Getting System Parameter

Expanding xsl:stylesheet Header

To use the XSLT extension functions, the stylesheet header must be expanded.

<xsl:stylesheet
	    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	    version="1.0"
	    xmlns:java="http://xml.apache.org/xslt/java"
	    xmlns:io="XSLIOHelper"
	    xmlns:properties="TransformerRequestProperties"
	   extension-element-prefixes="io properties">

As convention the following sections use the definitions xmlns:io and xmlns:properties in function declarations.

Trace UOW function

To trace the communication to EntireX Broker, set the JVM property XSLIOHelper.entirex.trace. Use the value for this property defined on the page ACI for Java.

The trace output is written to the System Log.

Receiving UOW

Receives as server a UOW from the persistent message queue and returns an XML document. Use this function as XPath function.

Function Declaration:

io:receiveUOW       ( String brokerID, String service [, String userID [, String token [, String password ] ] ] )
io:receiveWithOldUOW( String brokerID, String service [, String userID [, String token [, String password ] ] ] )

The contents of the received UOW is required as XML document and passed through 1:1 to the receiver. The WithOld in the function name means that the server looks for and existing old conversation. If an error occurs, the returned XML document contains the error message. The error message starts with the exception XML tag.

Element Extension Example:

<xsl:variable name="item" select="io:receiveWithOldUOW( $broker, $service, $userid, 'pmqToFile' )"/>

Stores the UOW as XML document in the item variable.

Parameter:

No.	Value	Description
1.	XPath expression should return a string.	Connection Broker ID as DNS name or IP address with port.
2.	XPath expression should return a string.	Service name in the format CLASS/SERVER/SERVICE
3.	XPath expression should return a string.	Connection user ID
4.	XPath expression should return a string.	Token for unique identification of this communication client.
5.	XPath expression should return a string.	Password for EntireX Broker Security.

Function Declaration:

io:receiveUOWText       ( String brokerID, String service [, String userID [, String token [, String password ] ] ] )
io:receiveWithOldUOWText( String brokerID, String service [, String userID [, String token [, String password ] ] ] )

The UOW is received as one document and tagged with the token XML tag.

Function Declaration:

io:receiveUOWLines       ( String brokerID, String service [, String userID [, String token [, String password ] ] ] )
io:receiveWithOldUOWLines( String brokerID, String service [, String userID [, String token [, String password ] ] ] )
io:receiveOldUOWLines( String brokerID, String service [, String userID [, String token [, String password ] ] ] )

The UOW can have many messages. Each message line is tagged with the token XML tag. Depending on function name, io:receiveUOWLines() queries only for new conversation, io:receiveWithOldUOWLines() queries for old and new, io:receiveOldUOWLines() queries only for old conversation. Old conversation is already reveived and opened with the same user ID and token parameter.

Sending UOW

Creates a UOW in the persistent message queue. This function should be used as an element extension call. The contents of an element extension are sent to the queue. The created UOW ID can be received with the io:getUnitOfWorkID() function. The io:isOK() call returns true on success or false on error.

Example:

<io:sendUOW
   broker="$broker" 
   service="concat( 'QUEUE/OUTBOUND-IDOC-XML/', $environment )" 
   user="$userid"
   token="'IDocToPMQ'" 
   password="$password" 
   mode="'client'" 
   withOld="'false'" 
   context="io:getUnitOfWorkID()">
	       <xsl:copy-of select="$result"/>
</io:sendUOW>

The example sends the contents of the $result variable to the persistent message queue.

Attributes:

Name	Value	Description
broker	XPath expression should return a string.	Connection Broker ID as DNS name or IP address with port.
service	XPath expression should return a string.	Service name in format CLASS/SERVER/SERVICE
userid	XPath expression should return a string.	Connection user ID
token	XPath expression should return a string.	Token for identify this communication client unique.
password	XPath expression should return a string.	Password for EntireX Broker Security.
withOld	XPath expression should return 'true' or 'false'	Ask for an existing conversation and if true, append this. Otherwise, create a new conversation.
mode	XPath expression should return 'client' or 'server'	Creates this UOW as client (=sender) or as server (=receiver) to an existing UOW.
context	XPath expression should return a string.	Prints this context information to the UOW status.
encoding	XPath expression should return a string.	Defines the encoding of sending data.

Getting Status Information

The following set of XPath functions replies information about the status of the last call.

Function Declaration:

io:getUnitOfWorkID()

Returns the last created or received UOW as string.

Function Declaration:

io:isOK()

Returns true, if last call was successful. Otherwise returns false on error.

Function Declaration:

io:getContextData()

Returns the user context data, if UOW is received.

Function Declaration:

io:getException()

If an error occurs ( not( io:isOK()) ), returns the error XML document. The main tag starts with exception.

UOW Transaction Handling

After sending or receiving a UOW, the client (=sender) or server (=receiver) must commit or back out (=rollback) the started transaction.

Element Extension:

<io:commitUOW/>

Commits the UOW. The Broker can deliver the created UOW to the partner or commit the correct processing pipeline step.

Element Extension:

<io:backoutUOW/>

Rolls back the UOW. The Broker does not deliver the created UOW to the partner, or delivery of the receiving UOW should be restarted later.

Logging

Sends log information to System Log.

Element Extension Example:

<io:log>
   <xsl:copy:of select="$result"/>
</io:log>

This example writes the contents of $result to the System Log.

Attributes:

Name	Value	Description
message	String	Writes this string.
select	XPath expression should return a string.	Writes this string.
encoding	XPath expression should return a string.	Defines the encoding of writing data.

Sending Mail

Sends a e-mail with the extension contents. Ask with io:isOK() for correct delivery.

Note:
The property mail.smtp.host must be set correctly. The JVM Property page helps with parameter settings.

Caution:
This function should be used only for control of your environment by sending mails to the administrator, for example. There is no support of document appendix setting.

Element Extension Example:

<io:sendMail
   subject="concat( //configuration[ @name = 'MainMenu' ]/title, ' sends hello world' )"
	to="//MAIL_TO_GW_ADMIN"
	from="//MAIL_FROM_GW_ADMIN">
     <xsl:copy:of select="$result"/>
</io:sendMail>

This example sends the contents of $result to the e-mail receiver.

Attributes:

Name	Value	Description
to	XPath expression should return a string.	E-mail receiver.
from	XPath expression should return a string.	Name of e-mail sender.
encoding	XPath expression should return a string.	Defines the encoding of writing data.
subject	XPath expression should return a string.	Title of e-mail.
content	XPath expression should return a string.	Sends this contents data.

Exchange Document

Sends and receives an XML document via HTTP-Post. It is possible to pass user ID and password to the web service with HTTP Basic Authentication.

Element Extension Example:

<xsl:variable name="resultFromWeb">
   <io:document href="'http://localhost:8080/axis/myWebService'">
        <xsl:copy:of select="$result"/>
   </io:document>
</xsl:variable>

This example sends the contents of $result to the HTTP server and stores the reply in $resultFromWeb.

Attributes:

Name	Value	Description
href	XPath expression should return a string.	HTTP address
userid	XPath expression should return a string.	HTTP Basic Authentication user ID.
password	XPath expression should return a string.	HTTP Basic Authentication user password.
select	XPath expression should return a string.	Send the string as text.
encoding	XPath expression should return a string.	Send the content with this encoding.
contentType	XPath expression should return a string.	Set this content type in the request header.
contentType	XPath expression should return a string.	Set the `SOAPAction` request header to this value, e.g. `Some-URI`.

Getting System Parameter

The following function retrieves parameters from the System Constants page or parameters that have been passed via HTTP-Get request.

Function Declaration:

properties:getParameter( String key )

Returns the value as string of HTTP-Get parameter from key name. This HTTP-Get parameter should be sent to the caller in the URL or be passed as HTTP-Post parameter.

Function Declaration:

properties:getSystemConstancy( String key )

Returns the value as string of System Constants parameter from key name.

SEARCH CONTENTS | PDF BOOKS | HOME UP PREV NEXT