| <?xml version="1.0" encoding="ISO-8859-1"?> |
| <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd"> |
| <document> |
| <header> |
| <title>Web3</title> |
| <subtitle>Web3 Connectivity Toolkit</subtitle> |
| <authors> |
| <person name="Michael Gerzabek" email="michael.gerzabek@at.efp.cc"/> |
| </authors> |
| </header> |
| <body> |
| <s1 title="About"> |
| <p> |
| <link href="http://www.efp.cc/web3">EFP Consulting Austria</link> produced an open-source library called Web3 |
| that allows you to integrate SAP R/3 seamlessly into Cocoon 2. With these components you are able to call Remote |
| Function Calls via an easy to use XML-syntax. For most BAPIs and Remote enabled Function Calls you simply need |
| a text editor. |
| </p> |
| <p>This toolkit offers you ...</p> |
| <ul> |
| <li>... synchron communication to any SAP system above release 3.1H.</li> |
| <li>... easy to use ABAP function calls from outside R/3 with a se37-like markup-syntax.</li> |
| </ul> |
| <note> |
| The following guide helps you to setup cocoon with your SAP R/3. Reasonably this guide cannot answer |
| all questions dealing with your environment. For further questions be advised to contact your favorite SAP Consultant. |
| </note> |
| </s1> |
| <s1 title="Installing SAP R/3 (TM) JavaConnector"> |
| <p> |
| Be sure to proper install the appropriate SAP Java-Connector from <link href="http://service.sap.com/connectors"> |
| www.sap.com</link>. To install the connector refer to the included documentations. |
| </p> |
| </s1> |
| <s1 title="Configuring cocoon.xconf"> |
| <p> |
| With Web3 you have a flexible Toolkit where you can connect to multiple R/3 System within one single Cocoon- |
| Instance. Enter your backend configuration into cocoon.xconf like this: |
| </p> |
| <s2 title="Items"> |
| <table> |
| <caption>Configuration elements</caption> |
| <tr> |
| <th>Element</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>web3</td> |
| <td>Declare your logger here.</td> |
| </tr> |
| <tr> |
| <td>pool</td> |
| <td>The pool element is the logical unit of all your SAP settings.</td> |
| </tr> |
| <tr> |
| <td>client</td> |
| <td>The systems client you log onto.</td> |
| </tr> |
| <tr> |
| <td>user, password, language</td> |
| <td>...</td> |
| </tr> |
| <tr> |
| <td>route</td> |
| <td>The route to your SAP system. Please refer to your <link href="http://help.sap.com">SAP help</link> to prepare the connection string.</td> |
| </tr> |
| <tr> |
| <td>system</td> |
| <td>The system-number of your SAP system you log onto.</td> |
| </tr> |
| <tr> |
| <td>gateway, program-id</td> |
| <td>Are mandatory and not used within Web3's szenario.</td> |
| </tr> |
| </table> |
| <table> |
| <caption>Specifics on the <code>pool</code> element</caption> |
| <tr> |
| <td>@trace</td><td>a <code>boolean</code> switch whether to use JCO's facility to trace the communication layer or not.</td> |
| </tr> |
| <tr> |
| <td>@level</td><td>if @trace is <code>true</code> set the trace-level to your prefered value. Please refer to the JCO's documentation about tracing.</td> |
| </tr> |
| <tr> |
| <td>@size</td><td>denotes the pool-size of your sap connection pool. Be aware that this is a hard-limited pool.</td> |
| </tr> |
| </table> |
| </s2> |
| <p> |
| A configuration in your cocoon.xconf would look like this: |
| </p> |
| |
| <source><![CDATA[<web3 logger="core.web3"> |
| <backend name="indy"> |
| <pool level="0" size="10" trace="false"> |
| <client>100</client> |
| <user>user</user> |
| <password>secret-passphrase</password> |
| <language>DE</language> |
| <route>indy</route> |
| <system>00</system> |
| <gateway>sapgw00</gateway> |
| <program-id>USR-GR02</program-id> |
| </pool> |
| </backend> |
| <backend name="hugo"> |
| ... |
| </web3>]]></source> |
| |
| </s1> |
| |
| <s1 title="Implementing your own RFC's"> |
| <p>First of all you have to setup your markup with the right Namespace</p> |
| <source><![CDATA[<page xmlns:rfc="http://apache.org/cocoon/Web3-Rfc/1.0"> |
| ... |
| </page>]]></source> |
| <p>After doing so you can enter RFC-mappings with the following syntax. You will see this is a very easy task and you will enjoy |
| using Web3 to do the stuff for you within your SAP environment :)</p> |
| <s2 title="Web3 rfc-Syntax"> |
| <p> |
| Data definitions (metadata) are created and managed in the ABAP Dictionary. The ABAP Dictionary permits a central |
| description of all the data used in the system without redundancies. New or modified information is automatically provided |
| for all the system components. This ensures data integrity, data consistency and data security. |
| </p> |
| <p> |
| The syntax used within this markup builds upon these facts. So do not wonder if you find the corresponding logical |
| units in the Cocoon frontend. |
| </p> |
| <table> |
| <caption>Markup</caption> |
| <tr> |
| <th>Element</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td> |
| <link href="#rfc_include">rfc:include</link> |
| </td> |
| <td>Starts a mapping for the specified RFC.</td> |
| </tr> |
| <tr> |
| <td> |
| <link href="#rfc_import">rfc:import</link> |
| </td> |
| <td>Container element for structures and fields.</td> |
| </tr> |
| <tr> |
| <td> |
| <link href="#rfc_tables">rfc:tables</link> |
| </td> |
| <td>Container element for tables.</td> |
| </tr> |
| <tr> |
| <td> |
| <link href="#rfc_structure">rfc:structure</link> |
| </td> |
| <td>Container element for fields.</td> |
| </tr> |
| <tr> |
| <td> |
| <link href="#rfc_table">rfc:table</link> |
| </td> |
| <td>Container element for structures.</td> |
| </tr> |
| <tr> |
| <td> |
| <link href="#rfc_field">rfc:field</link> |
| </td> |
| <td>The data-fields.</td> |
| </tr> |
| </table> |
| </s2> |
| |
| <anchor id="rfc_include"/> |
| <s2 title="rfc:include"> |
| <p>First when you start to map a RFC keep in mind to get the parameters from your SAP system. Therefore you |
| may want to use se37 where all relevant parameters are listed. The <code>@name</code> has to be the name of |
| the RFC you want to map. </p> |
| <p>Since many RFC's return hierarchical data split into tables you will encounter some |
| problems in xslt when rendering these data to trees. So you may implement <code>org.apache.cocoon.components.web3.Web3Streamer</code> to get a proper XML to work with. You can set your own streamer in the |
| <code>@streamer</code>.</p> |
| <table> |
| <caption>Attributes</caption> |
| <tr> |
| <th>Attribute</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td> |
| @name |
| </td> |
| <td>The name of the SAP RFC</td> |
| </tr> |
| <tr> |
| <td> |
| @streamer |
| </td> |
| <td>The class-name of your function streamer. Most of the time you won't need to implement it anyway.</td> |
| </tr> |
| </table> |
| <p/> |
| </s2> |
| <anchor id="rfc_import"/> |
| <s2 title="rfc:import"> |
| <p> |
| When requesting a RFC you have to fill the import parameterlist. The import parameterlist lists all relevant parameters |
| that have to be provided to get proper results from your R/3.</p> |
| <p>se37 can provide you with the relevant information. |
| </p> |
| </s2> |
| <anchor id="rfc_tables"/> |
| <s2 title="rfc:tables"> |
| <p> |
| Some highly complex RFC's have also tables in their calling interface. You may need to read the SAP documentation of the |
| BAPI you gotta call and when to make use of one of them. |
| </p> |
| </s2> |
| <anchor id="rfc_structure"/> |
| <s2 title="rfc:structure"> |
| <p> |
| A structure comprises fields. A field can refer to an elementary type (via a data element or by directly specifying the data type and length in the structure definition), another structure or a table type. A structure can therefore be nested to any depth. |
| </p> |
| <note>At the time the facility to use nested structures has not been tested!</note> |
| </s2> |
| <anchor id="rfc_table"/> |
| <s2 title="rfc:table"> |
| <p> |
| A table consists of a collection of structures with same structure type. To keep it simple we can sloppily say a table is like |
| a SQL-database-table. |
| </p> |
| </s2> |
| <anchor id="rfc_field"/> |
| <s2 title="rfc:field"> |
| <p> |
| Fields, also called data elements are the smallest indivisible units of the complex types and are used to specify the types |
| in structures and columns of tables. A field describes either an elementary type or a reference type.</p> |
| <p> |
| In ABAP exist predefined types and custom defined types. But don't worry about the horrible task of converting into the right |
| type. This task is excellently done for you by the JavaConnector. |
| </p> |
| <note> |
| Keep in mind that the communication format for numbers and date is US. So supply <code>Date</code> information |
| in format YYYY-MM-DD with the slashes and <code>number</code> information like DDDDD.DD where the dot is the comma! |
| </note> |
| </s2> |
| <p>If you want to check your RFC mappings for syntactically correctness you may want to use the enclosed <code>dtd</code>'s.</p> |
| </s1> |
| <s1 title="A more complex example"> |
| <p> |
| The included example demonstrates a more complex function call. Keep in mind that the correct execution |
| depends on the local customizing settings of the connected SAP System. |
| </p> |
| <source><![CDATA[<page xmlns:rfc="http://apache.org/cocoon/Web3-Rfc/1.0"> |
| <rfc:include name="XXX" streamer="XXX"> |
| <rfc:import> |
| <rfc:structure name="XXX"> |
| <rfc:field name="XXX">YYY</rfc:field> |
| <rfc:field name="XXX">YYY</rfc:field> |
| <rfc:field name="XXX">YYY</rfc:field> |
| </rfc:structure> |
| <rfc:tables> |
| <rfc:table name="XXX"> |
| <rfc:structure name="1"> |
| <rfc:field name="XXX">YYY</rfc:field> |
| <rfc:field name="XXX">YYY</rfc:field> |
| <rfc:field name="XXX">YYY</rfc:field> |
| </rfc:structure> |
| </rfc:table> |
| </rfc:tables> |
| </rfc:import> |
| </rfc:include> |
| </page>]]></source> |
| </s1> |
| <s1 title="Setting up the sitemap"> |
| <p>There are two ways to setup your Web3Transformer in the sitemap.</p> |
| <s2 title="Global Configuration"> |
| <p>If you have to deal only with one R/3 Instance you may |
| configure your <code>org.apache.cocoon.transformation.Web3RfcTransformer</code> |
| global like stated in the following sitemap snippet.</p> |
| |
| <source><![CDATA[ |
| <map:transformer name="rfc" |
| src="org.apache.cocoon.transformation.Web3RfcTransformer" |
| logger="web3.transformation"> |
| <system>indy</system> |
| </map:transformer> |
| ]]></source> |
| </s2> |
| <s2 title="Parametrized Configuration"> |
| <p>If you have setup several R/3 pools you can parametrize the |
| <code>org.apache.cocoon.transformation.Web3RfcTransformer</code> as stated next</p> |
| <source><![CDATA[ |
| <map:transform type="rfc"> |
| <map:parameter name="backend" value="indy"/> |
| </map:transform> |
| ]]></source> |
| </s2> |
| </s1> |
| <s1 title="Further questions"> |
| <p> |
| Enjoy using Web3. For further questions feel free to contact the author |
| <link href="mailto:michael.gerzabek@at.efp.cc">Michael Gerzabek</link> |
| </p> |
| </s1> |
| <figure src="images/cocoon-built.gif" alt="Built with Apache Cocoon"/> |
| </body> |
| </document> |