Open Catalog Interface

Transcription

1 Open Catalog Interface Release July 1999

2 Overview SAP AG Copyright Copyright 1997 SAP AG. All rights reserved. No part of this documentation may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. SAP AG further does not warrant the accuracy or completeness of the information, text, graphics, links or other items contained within these materials. SAP AG shall not be liable for any special, indirect, incidental, or consequential damages, including without limitation, lost revenues or lost profits, which may result from the use of these materials. The information in this documentation is subject to change without notice and does not represent a commitment on the part of SAP AG in the future. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. Microsoft ###, WINDOWS, NT ###,EXCEL and SQL-Server ### are registered trademarks of Microsoft Corporation. IBM ###, OS/2, DB2/6000, ###AIX, OS/400, AS/400 ### are a registered trademark of IBM Corporation. OSF/Motif is a registered trademark of Open Software Foundation. ORACLE is a registered trademark of ORACLE Corporation, California, USA. INFORMIX -OnLine for SAP is a registered trademark of Informix Software Incorporated. UNIX ### and X/Open ### are registered trademarks of SCO Santa Cruz Operation. ADABAS is a registered trademark of Software AG SAP, R/2 ###, R/3 ###, RIVA ###, ABAP/4, SAPoffice, SAPmail, SAPaccess ###, SAP-EDI, SAP ArchiveLink, SAP EarlyWatch ###, SAP Business Workflow, R/3 Retail are registered trademarks of SAP AG All rights reserved. Material Number of this document:

3 SAP AG Overview Contents Chapter 1: Overview Chapter 2: Interface Structure Outbound Section Inbound Section Catalog Interface Example

4 Overview SAP AG Chapter 1: Overview This specification describes the standard CGI interface between catalogs and SAP B2B Procurement. This specification has already been implemented between several catalog applications and SAP B2B Procurement. Overview of catalogue integration Intranet DB Employee ITS Browser Agate/ WGate R/3 Catalog Internet Catalog Ext. Catalog SAP AG 1999 Dr. Claudius Fischer /10 1 4

5 SAP AG Interface Structure Chapter 2: Interface Structure The catalog interface consists of two separate and distinct sections: Outbound and Inbound. The Outbound section defines the information being sent from the SAP B2B Procurement application to the catalog application. This can include information such as the catalog URL and login data. The Inbound section consists of the information being sent from the catalog application to the SAP B2B Procurement application. This section contains data on the items selected in the catalog, such as the item descriptions, quantities ordered, and prices. Refer to the Interface Diagram at the end of this document for more details. Outbound Section The following graphic illustrates the outbound interface Catalog Purchasing application (via Browser) Catalog button OkCode SAP Web application Catalog URL with parameters e.g. SAP B2B Procurement Internet Information Server (IIS) Internet Transaction Server (ITS) Catalog application Catalog CGI script Catalog page 2 5

6 Interface Structure SAP AG The Outbound section consists of information that is sent to the catalog application by the SAP B2B Procurement application. This information originates in the SAP system, where it is created and maintained by SAP Transaction OXW3. Using this information, the SAP B2B Procurement application constructs a URL call to the catalog application. The CGI script of the catalog application then parses and decodes this information. In the SAP B2B Procurement system, you can set up this information in Customizing. For further information, see: IMG: Electronic Commerce Business-to-Business Procurement Catalogs Define Catalogs. Note the following when setting up this information: Many of the field names and values are dependent on the particular catalog application. You must structure the fields in the order shown in the table below. In particular, define the catalog-specific information directly after the catalog URL and the ~OkCode and ~Target fields directly after the Return URL field. Typically, field values are entered as literals. For example, the LOGIN field can have a literal value of GUEST. However, system variables such as SY-UNAME can also be used as valid values for a field, allowing for the actual value to be determined at runtime. In this case, you should assign a Type value of "3" to the relevant field (refer also to the documentation on Transaction OXW3). The Outbound data you maintain in transaction OXW3 is structured as described in the table below. In this table, "Fixed" indicates that the field name must be exactly as specified, whereas Variable indicates that the field name is catalog-specific. Description Mandatory Catalogspecific Catalog URL All catalogspecific fields Field Name Field name is fixed / variable Meaning Yes Yes <blank> Fixed The URL of the catalog. Should refer to the location of the catalog CGI script file. As applicable Return URL Yes No HOOK_ URL Yes Variable The set of catalog-specific fields. An example of catalogspecific fields is provided in the table below. Variable The URL used to return to the SAP B2B Procurement 2 6

7 SAP AG Interface Structure application from the catalog application. Set the value of this field to blank as it is automatically filled at run-time by the procurement application. The HOOK_URL can have a different name, but the type of this field must be set to 4 (return URL). The HOOK_URL is encoded so that special characters such as ':' or '/' are represented by '%' and ASCII characters by their hex digits. The catalog application is responsible for decoding this string into a valid URL. Note that the catalog application must not make any assumptions on the HOOK_URL, e.g. it cannot assume that a question mark is present to delineate the URL variables. OK Code Yes No ~OkCode Fixed Contains the transaction code indicating that the function Add Items to SAP shopping basket is to be performed. Must be set to ADDI for SAP B2B Procurement. Target Yes No ~TARGET Fixed Specifies the frame to which a catalog is to return to in a frame-based environment. If this field is not set, the catalog application MUST provide a default target of _top. Example of catalog-specific parameters: Description Field Name Fixed/Variable field name Meaning Request type REQTYPE Variable Requests a login when the catalog is first accessed. Login USERNAME Variable The user ID to login to the catalog. 2 7

8 Interface Structure SAP AG Password PASSWORD Variable The login password. Database identifier SERVICE Variable A database identifier. This may be required for some catalogs. 2 8

9 SAP AG Interface Structure Inbound Section The Inbound section consists of information that is sent to the SAP B2B Procurement application by the catalog application. The specification of this information is different for goods catalogs and services catalogs. The following graphic illustrates the inbound interface: Catalog Catalog application Transfer shopping basket (Field arrays) Field arrays SAP Web Application e.g. SAP B2B Procurement Field array values copied to screen fields, OkCode = "ADDI" Internet Information Server (IIS) Internet Transaction Server (ITS) Save Purchasing application (via Browser) 2 9

10 Interface Structure SAP AG Goods Catalogs For each item selected in the catalog and sent to the SAP B2B Procurement application, all mandatory fields should be sent, along with the relevant optional fields. To handle multiple items selected in the catalog, each field name must be an array using the bracket subscript convention as per the C programming language. Subscripts must start at 1 (not zero). For example, the description of an item would be returned as a name, e.g. DESCRIPTION [1]. The fields can be sent back to the purchasing application by either the GET or the POST method. Note the following: The maximum number of items transferred in one call must not exceed 25. There must be no leading spaces in the fields. All numeric fields that allow fractional amounts must explicitly include the decimal point. in the correct byte position. Apart from the decimal point, numeric fields must NOT include commas or any other non-numeric characters. Item Name Required / Description Material Master Unit of Measure DESCRIPTION MATNR UNIT Required if the SAP material master number is not specified. Required if the Description field is not specified. Required if Material Master field is not filled. Details The description of the item to be ordered. This must not exceed 40 characters. The SAP material master number. This must not exceed 18 characters. Unit of measure of the item. This must not exceed 3 characters, and must be the standard ISO code. Price PRICE Price of the item from the catalog. This must not exceed 15 characters. There can be a maximum of 11 digits to the left of the decimal point, and there must be 3 digits to the right. Quantity QUANTITY Required Quantity to add. This must not exceed 15 characters. There can be a maximum of 11 digits to the 2 10

11 SAP AG Interface Structure left of the decimal point, and there must be 3 digits to the right. Currency CURRENCY Required if a price is returned, otherwise optional Must not exceed 5 characters, and must be the ISO code for the currency. Lead Time LEADTIME Number of working days from today when the product will be available. If not specified, no assumptions will be made on the lead time. Must not exceed 5 characters. Vendor VENDOR The SAP vendor account number of the product, if the product is purchased through a broker. Must not exceed 10 characters. Vendor Material Number VENDORMAT The vendor material part number of the product. Must not exceed 22 characters. Manufacturer MANUFACTCODE The manufacturer of the product. Must not exceed 10 characters. Manufacturer Material Number MANUFACTMAT The manufacturer s material part number of the product. Must not exceed 22 characters. Price Unit PRICEUNIT The number of units that must be purchased at the given price. Must not exceed 9 characters. This quantity defaults to one. Material Group MATGROUP The SAP material group. This must not exceed 9 characters. Service Catalogs The following fields are returned to the SAP B2B Procurement application from a catalog application. For each item selected in the catalog and sent to the SAP B2B Procurement application, all mandatory fields should be sent, along with the relevant optional fields. To handle multiple items selected in the catalog, each field name should be an array using the bracket subscript convention as in the C programming language. Subscripts must start at 1 (not zero). For example, the description of an item would be returned as a name, 2 11

12 Interface Structure SAP AG e.g. DESCRIPTION [1]. The fields can be sent back to the purchasing application by either the GET or the POST method. Note the following: The maximum number of items transferred in one call must not exceed 25. There must be no leading spaces in the fields. All numeric fields that allow fractional amounts must explicitly include the decimal point. in the correct byte position. Apart from the decimal point, numeric fields must NOT include commas or any other non-numeric characters. Item Name Required / Details Description DESCRIPTION Required if no service master is specified. The description of the service to be ordered. This must not exceed 40 characters. Service Master SERVICE Required if no Description is specified. The SAP service master number. This must not exceed 18 characters. Unit of Measure UNIT Required if no service master number is specified. Unit of measure of the service line. This must not exceed 3 characters, and must be the standard ISO code. Price PRICE. Price of the service line from the catalog. This must not exceed 15 characters. There can be a maximum of 11 digits to the left of the decimal point, and there must be 3 digits to the right. If no price is returned, the SAP system can only create a purchase requisition, not a purchase order. Quantity QUANTITY Required. Quantity to add. This must not exceed 15 characters. There can be a maximum of 11 digits to the left of the decimal point, and there must be 3 digits to the right. 2 12

13 SAP AG Interface Structure If no quantity is returned the default value is 1. Currency CURRENCY Required if the price is returned. Must not exceed 5 characters, and must be the ISO code for currency. Lead Time LEADTIME. Number of working days from today when the service will be available. If no value is provided, no assumptions will be made on the lead time. Must not exceed 5 characters. Vendor VENDOR. The SAP vendor account number if the service is purchased through a broker. Must not exceed 10 characters. Vendor Service Number VENDORSRV. The vendor service number of the service. Must not exceed 18 characters. Price Unit PRICEUNIT. The number of units that must be purchased at the given price. Must not exceed 9 characters. This defaults to 1 if no other value is specified. 2 13

14 Interface Structure SAP AG Catalog Interface Example The following excerpts are examples of the HTML source code generated by a catalogue engine after a user has completed selecting items for a shopping basket. You can extract the source code and display the data in a Web Browser. Example 1 shows the HTML code generated for goods, example 2 that generated for services. Note that the input type of "text" can be set to "hidden" if it is not necessary to display the items. Also, the table coding is used for display purposes only and is not mandatory. </HEAD> <BODY bgcolor="#ded6c2"> <FORM action="content of HOOK_URL" method=get target=_top> <input type="hidden" name="~okcode" value="value of ~OKCODE (ADDI for B2B)"> <input type="hidden" name="~target" value="value of ~TARGET (must be _top)"> <TABLE border=1> Example 1: Up to 25 items (goods) <!--For more information about the interface fields see the catalogue interface description--> <!--Item number 1--> <TR> <TD><input type="text" name="description[1]" value="descriptive text"> </TD> <TD><input type="text" name="matnr[1]" value="material number of the item"> </TD> <TD><input type="text" name="unit[1]" value="unit of the item"> </TD> <TD><input type="text" name="price[1]" value="price of the item"> </TD> <TD><input type="text" name="quantity[1]" value="quantity of the item"> </TD> <TD><input type="text" name="currency[1]" value="currency"> </TD> <TD><input type="text" name="leadtime[1]" value="lead time"> </TD> <TD><input type="text" name="vendor[1]" value="vendor number"> </TD> <TD><input type="text" name="vendormat[1]" value="vendor material"> </TD> <TD><input type="text" name="manufactcode[1]" value="manufacturer of the product"> </TD> <TD><input type="text" name="manufactmat[1]" value="manufacturer's material number"></td> <TD><input type="text" name="priceunit[1]" value="price per unit"> </TD> <TD><input type="text" name="matgroup[1]" value="material group"> </TD> </TR> <!--Item number 2--> <TR> <TD><input type="text" name="description[2]" value="descriptive text"> </TD> <TD><input type="text" name="matnr[2]" value="material number of the item"> </TD> <TD><input type="text" name="unit[2]" value="unit of the item"> </TD> <TD><input type="text" name="price[2]" value="price of the item"> </TD> <TD><input type="text" name="quantity[2]" value="quantity of the item"> </TD> 2 14

15 SAP AG Interface Structure <TD><input type="text" name="currency[2]" value="currency"> </TD> <TD><input type="text" name="leadtime[2]" value="lead time"> </TD> <TD><input type="text" name="vendor[2]" value="vendor number"> </TD> <TD><input type="text" name="vendormat[2]" value="vendor material"> </TD> <TD><input type="text" name="manufactcode[2]" value="manufacturer of the product"> </TD> <TD><input type="text" name="manufactmat[2]" value="manufacturer's material number"> </TD> <TD><input type="text" name="priceunit[2]" value="price per unit"> </TD> <TD><input type="text" name="matgroup[2]" value="material group"> </TD> </TR> <!--Item number 3--> <TR> <TD><input type="text" name="description[3]" value="descriptive text"> </TD> <TD><input type="text" name="matnr[3]" value="material number of the item"> </TD> <TD><input type="text" name="unit[3]" value="unit of the item"> </TD> <TD><input type="text" name="price[3]" value="price of the item"> </TD> <TD><input type="text" name="quantity[3]" value="quantity of the item"> </TD> <TD><input type="text" name="currency[3]" value="currency"> </TD> <TD><input type="text" name="leadtime[3]" value="lead time"> </TD> <TD><input type="text" name="vendor[3]" value="vendor number"> </TD> <TD><input type="text" name="vendormat[3]" value="vendor material"> </TD> <TD><input type="text" name="manufactcode[3]" value="manufacturer of the product"> </TD> <TD><input type="text" name="manufactmat[3]" value="manufacturer's Material number"></td> <TD><input type="text" name="priceunit[3]" value="price per unit"> </TD> <TD><input type="text" name="matgroup[3]" value="material group"> </TD> </TR> <!--and so on...--> </TABLE> <BR> <! > <TABLE border=1> Example 2: Up to 25 items (services) <!--For more information about the interface fields see the catalogue interface description--> <!--Item number 1--> <TR> <TD><input type="text" name="description[1]" value="descriptive text"> </TD> <TD><input type="text" name="service[1]" value="service number"> </TD> <TD><input type="text" name="unit[1]" value="unit of the service"> </TD> <TD><input type="text" name="price[1]" value="price of the service"> </TD> <TD><input type="text" name="quantity[1]" value="quantity of the service"></td> <TD><input type="text" name="currency[1]" value="currency"> </TD> 2 15

16 Interface Structure SAP AG <TD><input type="text" name="leadtime[1]" value="lead time"> </TD> <TD><input type="text" name="vendor[1]" value="vendor"> </TD> <TD><input type="text" name="vendorsrv[1]" value="vendor service number"> </TD> <TD><input type="text" name="priceunit[1]" value="price per unit"> </TD> </TR> <!--Item number 2--> <TR> <TD><input type="text" name="description[2]" value="descriptive text"> </TD> <TD><input type="text" name="service[2]" value="service number"> </TD> <TD><input type="text" name="unit[2]" value="unit of the service"> </TD> <TD><input type="text" name="price[2]" value="price of the service"> </TD> <TD><input type="text" name="quantity[2]" value="quantity of the service"> </TD> <TD><input type="text" name="currency[2]" value="currency"> </TD> <TD><input type="text" name="leadtime[2]" value="lead time"> </TD> <TD><input type="text" name="vendor[2]" value="vendor"> </TD> <TD><input type="text" name="vendorsrv[2]" value="vendor service number"> </TD> <TD><input type="text" name="priceunit[2]" value="price per unit"> </TD> </TR> <!--Item number 3--> <TR> <TD><input type="text" name="description[3]" value="descriptive text"> </TD> <TD><input type="text" name="service[3]" value="service number"> </TD> <TD><input type="text" name="unit[3]" value="unit of the service"> </TD> <TD><input type="text" name="price[3]" value="price of the service"> </TD> <TD><input type="text" name="quantity[3]" value="quantity of the service"> </TD> <TD><input type="text" name="currency[3]" value="currency"> </TD> <TD><input type="text" name="leadtime[3]" value="lead time"> </TD> <TD><input type="text" name="vendor[3]" value="vendor"> </TD> <TD><input type="text" name="vendorsrv[3]" value="vendor service number"> </TD> <TD><input type="text" name="priceunit[3]" value="price per unit"> </TD> </TR> <!--and so on...--> </TABLE> <BR> <input type="submit" name="button1" value="submit to B2B"> </FORM> 1999, SAP AG </BODY> </HTML> 2 16