SAP Ariba Catalog integration guide

PUBLIC2022-02

SAP Ariba Catalog integration guideSAP Ariba CatalogSAP Ariba Spot Buy Catalog

© 2

022

SAP

SE o

r an

SAP affi

liate

com

pany

. All r

ight

s re

serv

ed.

THE BEST RUN

Content

SAP Ariba Catalog integration guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Integrating with Oracle iProcurement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Prerequisites for Oracle iProcurement integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

About PunchOut access methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Flow of data between iProcurement and SAP Ariba Catalog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Data flow sequence between iProcurement and SAP Ariba Catalog. . . . . . . . . . . . . . . . . . . . . . . . . . 7Configuring punchout in Oracle iProcurement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

How to create the iProcurement punchOut catalog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Advanced configuration settings for the Oracle Native XML punchout method. . . . . . . . . . . . . . . . . . . . 10

How to filter catalogs based on groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Mapping custom fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Troubleshooting Oracle iProcurement error messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Integrating with SAP SRM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14About SAP SRM 7.0 certification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

SAP SRM 7.0 requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Flow of Data Between SAP Ariba Catalog and SAP SRM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Secure Integration using secure OCI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

Overview of punching in to SAP Ariba Catalog using secure OCI. . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Overview of retrieving shopping cart data from SAP Ariba Catalog. . . . . . . . . . . . . . . . . . . . . . . . . . 21Secure OCI parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Advanced SAP SRM configuration settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Catalog filtering using OCI outbound parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Using standard customization to map custom fields for SAP SRM. . . . . . . . . . . . . . . . . . . . . . . . . . 26Supporting OCI functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Troubleshooting SAP SRM Integration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Invalid fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Missing scrollbar in SAP Ariba Catalog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34Validity of data in Open Catalog Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Configuring SAP Ariba Catalog features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Support for sending item type information from SAP Ariba Catalog. . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Support for punching in during contract creation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38Support for displaying external contract links. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Configuring support for external contracts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39

2 PUBLICSAP Ariba Catalog integration guide

Content

Supporting catalog search using web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43Web services catalog search implementation overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Revision history. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

SAP Ariba Catalog integration guideContent PUBLIC 3

SAP Ariba Catalog integration guide

This guide is describes how administrators can configure their external systems to integrate with SAP Ariba Catalog.

Integration between SAP Ariba Catalog and external systems enables buyers to handle their catalog management and selecting goods and services processes in SAP Ariba Catalog while the other stages of the procurement process occur in the external systems.

This guide applies to:

● SAP Ariba Catalog

Related guides

Catalog administration guide for buyers

Catalog user guide

Shopping cart user guide


SAP Ariba Catalog integration guide

https://help.sap.com/viewer/c9b2518a80f1409aae8660cd58612a65/cloud/en-US/dbb6508fde234831aa1af9f440670edd.html

https://help.sap.com/viewer/fa7cf76d77b34c6daa1679816d37fefb/cloud/en-US/87b39c75a7c641799754c48b612bb610.html

https://help.sap.com/viewer/bc38c54987774e359eb3a2a930cb8018/cloud/en-US/96cc6708cde6473c880d582dcbc2aec9.html

Introduction

Integration between SAP Ariba Catalog and E-procurement applications uses standards-based communication.

SAP Ariba Catalog supports integration using the following protocols:

● cXML (commerce eXtensible Markup Language)● Oracle native XML (Oracle native eXtensible Markup Language)● OCI (Open Catalog Interface)

SAP Ariba Catalog integrates with Oracle iProcurement using cXML and Oracle native XML based protocols. For more information, see Integrating with Oracle iProcurement [page 6].

SAP Ariba Catalog integrates with SAP Supplier Relationship Management (SAP SRM) using OCI based protocols. For more information, see Integrating with SAP SRM [page 14].

Ariba Spot Buy Catalog

SAP Ariba Spot Buy Catalog is a separate solution to SAP Ariba Catalog and must be enabled by SAP Ariba. The SAP Ariba Spot Buy Catalog solution uses the SAP Ariba Catalog platform.

SAP Ariba Catalog integration guideIntroduction PUBLIC 5

Integrating with Oracle iProcurement

Oracle iProcurement integrates with SAP Ariba Catalog using the cXML and Oracle native XML protocols.

Prerequisites for Oracle iProcurement integration [page 6]

Flow of data between iProcurement and SAP Ariba Catalog [page 7]

Configuring punchout in Oracle iProcurement [page 8]

Advanced configuration settings for the Oracle Native XML punchout method [page 10]

Troubleshooting Oracle iProcurement error messages [page 12]

Prerequisites for Oracle iProcurement integrationBefore you start the integration process you must contact SAP Ariba customer support to obtain an Ariba Network Id for iProcurement, an Ariba Network ID for SAP Ariba Catalog, and a Shared Secret for authentication. In addition you must select a punchout model before configuring your integration.

About PunchOut access methods

Oracle iProcurement supports two punchout models: Direct PunchOut using Oracle native XML, and Direct PunchOut using cXML.

You must select a punchout model before configuring the integration.

Choose Direct PunchOut using Oracle native XML if:

● You want to access catalogs from multiple suppliers in SAP Ariba Catalog.● You want to work with collaborative items. Oracle native XML enables you to customize 15 custom fields for

collaboration.

Choose Direct PunchOut using cXML if you want to:

● Access catalogs only from one supplier.



Flow of data between iProcurement and SAP Ariba CatalogData flows across different systems during a punchout transaction: iProcurement, SAP Ariba Catalog, andAriba Network, the e-commerce hub that authenticates both the parties involved in a transaction.

To understand the specifications of a transaction, see the cXML User's Guide at the following URL:

http://xml.cxml.org/current/cXMLUsersGuide.pdf

The cXML version supported is cXML 1.2.

The iProcurement application and SAP Ariba Catalog must be registered with Ariba Network. After being registered on Ariba Network, the iProcurement application needs to set up a relationship with SAP Ariba Catalog.

Data flow sequence between iProcurement and SAP Ariba Catalog

Data flows from iProcurement through Ariba Network to SAP Ariba Catalog and back again in a series of steps during a complete transaction.

1. The Oracle iProcurement application initiates a transaction by sending an HTTPS/SSL POST request with a PunchoutSetupRequest document to the Ariba Network.

2. Ariba Network authenticates the iProcurement application and opens an HTTPS session with SAP Ariba Catalog to pass the request.

3. SAP Ariba Catalog processes the incoming request, performs necessary setup and returns a redirect-encoded URL as part of the response through Ariba Network to the iProcurement application.

4. The iProcurement application redirects the user's browser to the SAP Ariba Catalog URL.5. The user can now browse catalogs in SAP Ariba Catalog.6. After the user completes the shopping session, SAP Ariba Catalog sends an HTTPS form POST request back to

the iProcurement application with the contents of the shopping cart.

SAP Ariba Catalog integration guideIntegrating with Oracle iProcurement PUBLIC 7

Configuring punchout in Oracle iProcurementTo configure a punchout transaction in Oracle iProcurement, create a punchout catalog.

How to create the iProcurement punchOut catalog

Create a punchout catalog to enable Oracle iProcurement to interact with SAP Ariba Catalog.

Procedure

1. Log in to Oracle iProcurement as a catalog administrator.2. Click the iProcurement Catalog Administration link.3. Click Manage Content and then Catalogs.4. Click Create to set up a new catalog.5. Select Punchout catalog and click Continue.6. Choose Supplier as the source.7. Choose either Direct punchout (Oracle native XML) or Direct punchout (cXML) as the Access Method and

click Continue.8. In the Create Supplier Punchout (cXML) Catalog page enter the following information as applicable:

Field Name Value

Buyer Company Identification

Company Name Enter the name of your realm.

Domain Enter Ariba Network ID.

Identity Enter the iProcurement ANID.

PunchOut Identification

Catalog Name Enter a name for the punchout catalog. The name will be displayed in the catalog store.

Description Enter a description. This is an optional field.

Keywords Enter keywords. This is an optional field.

Mapping Information

Key 1 Enter Ariba.

Supplier This is an optional field.

PunchOut Supplier Configuration

Supplier Name Enter the name of the supplier.

Supplier ID Enter the supplier ID. This is an optional field.



Field Name Value

Punchout URL Enter the URL that Oracle iProcurement will use to log in to the supplier site. It should include not only the URL, but the program name that will receive and process the login request.

For more information, see Specifying the Punchout URL [page 9].

Image This is an optional field.

Password Enter the Ariba Network shared secret password required by the supplier. The password will be used as a site-level password to access the supplier site. The supplier needs to provide you with the value.

Retype Password Retype the shared secret password.

Prevent changes to items returned from Punchout Site Select this checkbox.

All Prices are negotiated De-select this checkbox.

Specifying the punchout URL

Depending on your chosen punchout method (cXML or Oracle native XML), you must specify different punchout URLs with different parameters.

For cXML use the following URL:

https://s1.ariba.com/Buyer/Main/ad/transform/ariba.htmlui.content.POSRListener?ANURL=https://service.ariba.com/service/transaction/cxml.asp&APCANID=<myAPCANID>&SupplierDomain=<My SupplierDomain>&SupplierIdentity=<MySupplierID>

NoteReplace the values in < > with the following values:

● APCANID - Ariba Network ID for SAP Ariba Catalog● SupplierDomain - supplierid followed by one of the available organizational ID domains. For example,

supplierid.buyersystemid or supplierid.duns● SupplierIdentity - The value you choose for the SupplierDomain. For example, if you choose

buyersystemid, enter the buyersystemid domain value.

For Oracle native XML use the following URL:

https://s1.ariba.com/Buyer/Main/ad/transformPOSR/ariba.content.transform.TransformListener?ANURL=https://service.ariba.com/service/transaction/cxml.asp&Groups=<myGroup>&ShipTo=oracle&PreferredSupplierDomain=<mySupplierDomain>&SelfRedirect=FALSE&OverrideShipTo=FALSE


Note: Replace the values in < > with the following values:

● Groups - Enter the group name.● PreferredSupplierDomain - Enter the preferred organizational ID domain. For example, duns.

NoteIf the value of the OverrideShipTo parameter is set to False, the ShipTo Address will not be replaced with the ANID of the external procurement system. If the value of the parameter is not set or set to True, the ShipTo Address is replaced with the the ANID of the external procurement system. The default value of the OverrideShipTo parameter is True.

Advanced configuration settings for the Oracle Native XML punchout method

Advanced configuration settings for the Oracle native XML punchout method include catalog filtering and mapping custom fields.

How to filter catalogs based on groups

Context

Catalogs Views created based on groups can be used to filter catalogs. You can then specify the group name in the Punchout URL to filter catalogs based on the catalog views created in SAP Ariba Catalog

Procedure

1. Create catalog views in SAP Ariba Catalog based on groups.2. Enter the name of the group on which the catalog view is based as the value for the parameter in the Punchout

URL.

When a user punches in to SAP Ariba Catalog, the catalogs are filtered based on the group value in the Punchout URL. See, Specifying the Punchout URL [page 9].

For more information on Catalog Views, see the Catalog administration guide for buyers.



Results

NoteIf you enter the No Ad-hoc Item group name as the value, then users are not be able to add non-catalog items to the shopping cart.

Mapping custom fields

You can map custom catalog fields and category fields to any of the fifteen custom fields in a standard Oracle native XML message.

Standard customization for custom field mappings

An Oracle native XML message from Oracle iProcurement contains fifteen custom fields. Custom catalog fields can be mapped to any of these fifteen custom fields in SAP Ariba Catalog.

Custom Catalog fields are the fields created by loading Type Definitions. Contact your SAP Ariba Catalog Management resource or SAP Ariba Customer Support to load type definitions.

For example, to map the Hazardous Material field value to cus_Attribute1:

<inClass name="ariba.content.core.ShoppingCartLineItem"> <derived> <field name="cus_Attribute1" expression="getAnalyzableAttributes('hazmat')" templates="OXMLAttributes"> <type class="java.lang.String"/> <properties label="attribute1"/> </field> </derived> </inClass>

For more information on customization and managing type definitions, contact SAP Ariba Customer Support.


Troubleshooting Oracle iProcurement error messagesError message from Oracle iProcurement usually indicate that something is not set up correctly. A page might no longer be active, a category/UOM is not configured for purchasing, the SSL handshake failed, or there is an invalid field.

Page No Longer Active

Issue: When creating a requisition, the following error is displayed after punchout:

Error: You are trying to access a page that is no longer active. The referring page may have come from a previous session. Please select Home to proceed.

Reason: The punchout flow generates an error when attempting to return from the supplier site to the iProcurement shopping cart if the values of the two profile options Framework Validation Level and FND Function Validation Level are set to Error. (These two profile options are automatically be set to Error after applying 11.5.10.2CU.)

Fix: Contact your iProcurement administrator.

Error Category/UOM is not configured for Purchasing

Issue: An error message indicating that a category/UOM has not been configured for purchasing is displayed in Oracle iProcurement after checking out an item from SAP Ariba Catalog.

Reason: The unit of measure and category values that the supplier sends have not been mapped to the values in Oracle iProcurement.

Fix: Contact your iProcurement administrator.

SSL Handshake Failed

Issue: An error occurs after clicking the Punchout catalog link and the following message is displayed when you choose to view the additional technical details for this failure:

Error Code: 201 Unable To Reach Supplier Site Unable to send the Login Request XML.Supplier Login URL:..…..……ProcessorExceptionProxy Host: nullProxy Port: -1CA Certification File Location: e:\oracle\visora\iAS\Apache\Apache\conf\ssl.crt\svcitg.ariba.com.cer



URL: https://ariba.com/Buyer/Main/ad/transform/POSRListener java.io.IOException: javax.net.ssl.SSLException: SSL handshake failed: X509CertChainInvalidErr

Reason: The certification chain has not been configured as needed by Oracle.

Fix: Contact your Oracle iProcurement administrator.

Invalid Fields

Issue: An error occurs on punchin indicating that one or more field values are invalid.

Reason: One or more mandatory field values have not been populated. For example: Email Address, APCANID etc.

Fix: Populate all the mandatory fields with relevant values.


Integrating with SAP SRM

SAP Supplier Relationship Management (SAP SRM) integrates with SAP Ariba Catalog using Open Catalog Interface (OCI) based protocols. OCI is the standard format used by SAP SRM when connecting to external punch-out catalogs.

About SAP SRM 7.0 certification [page 14]

Flow of Data Between SAP Ariba Catalog and SAP SRM [page 15]

Secure Integration using secure OCI [page 20]

Advanced SAP SRM configuration settings [page 24]

Troubleshooting SAP SRM Integration [page 33]

About SAP SRM 7.0 certificationSAP Ariba Catalog has been certified to integrate with SAP SRM version 7.0 when users punchin through the SAP NetWeaver Portal.

Users can punchin to SAP Ariba Catalog from SAP SRM 7.0 in one of the following ways:

● Punchin through SAP NetWeaver Portal● Punchin through Portal-Independent Navigation Frame

Punchin through Portal-Independent Navigation Frame to SAP Ariba Catalog from SAP SRM 7.0 has NOT been certified yet and is being planned for in a future service pack release.

SAP SRM 7.0 requirementsThere are two requirements specific to SAP SRM 7.0: the returntarget call structure parameter, and the ModifyURL parameter.

Returntarget

A new call structure parameter, returntarget is required for OCI integration in SAP SRM 7.0.

The value specified for this parameter in the OCI call structure will be used in the HTTP form POST as part of the target attribute. The target attribute is used on the return path from SAP Ariba Catalog and it specifies the frame in SAP SRM 7.0 to which SAP Ariba Catalog needs to send data.

If you are using Internet Explorer 6.0 and higher, then the value of the parameter is _top or _parent. If you are using Firefox then the value should be _top only.



For more information, see SAP Note: 1287412.

ModifyURL

After checkout, SAP Ariba Catalog returns the shopping cart contents to SAP SRM using the HOOK_URL parameter value.

Previously, SAP Ariba Catalog truncated the HOOK_URL parameter value, preventing users from returning the shopping cart contents to SAP SRM 7.0.

NoteCustomers using SAP SRM 5.0 did not experience this issue as the truncated values were accepted in this version.

Now, a new parameter has been introduced to ensure the HOOK_URL parameter is not truncated. The ModifyURL parameter value specifies whether the HOOK_URL value needs to be truncated or not. You must ensure that this parameter is defined as an Outbound Parameter in the OCI Call Structure. It should be entered above the HOOK_URL.

If you do not want the HOOK_URL parameter value to be truncated, set the ModifyURL parameter value to False.

The default value of this parameter is True.

Flow of Data Between SAP Ariba Catalog and SAP SRMDuring a punchout transaction data flows across SAP Ariba Catalog and SAP SRM. To enable integration with SAP Ariba Catalog, you must configure parameters in SAP SRM.

Set the following parameters in SAP SRM:

Field NameMandatory Description

NoteThe field names are case-sensitive.

PunchinId Ariba Network ID

Unique identifier of SAP Ariba Catalog

PunchinPassword Yes The password associated with the PunchinId.

UniqueName Yes User ID to login to SAP Ariba Catalog

SAP Ariba Catalog integration guideIntegrating with SAP SRM PUBLIC 15


EmailAddress Yes The user's email address.

URL Yes The URL to punch in to SAP Ariba Catalog. Ensure that you append the URL with the PunchinId.

For example, https://s1.ariba.com/Buyer/Main/..../<ANID>. <ANID> indicates the Ariba Network ID value for SAP Ariba Catalog.

SAP Ariba recommends that you add this URL to the Trusted Sites security zone in your web browser.

ModifyURL Yes Specifies whether the HOOK_URL value needs to be truncated at checkout.

Default value is True.

HOOK_URL Yes The URL to which SAP Ariba Catalog redirects the User’s browser using HTTP FORM POST containing the Shopping Cart contents.

You can append additional parameter values to the HOOK_URL value by specifying them as a list of values to the Application.Content.OCI.CustomOutboundParameters site configuration option.

ReturnTarget Yes Specifies the frame in SAP SRM 7.0 to which SAP Ariba Catalog needs to send data.

The value specified for this parameter in the OCI call structure will be used in the HTTP form POST as part of the target attribute.

If you are using Internet Explorer 6.0 and higher, then the value of the parameter is _top or _parent. If you are using Firefox then the value should be _top only

PurchasingUnit No The purchasing unit associated with the user. SAP Ariba Catalog is enabled to receive purchasing units as an extrinsic field from SAP SRM. The User Profile and Purchasing Unit associations help filter the content that a user can view in SAP Ariba Catalog.

DefaultCurrency No The currency associated with the user.

UserLocale No The locale associated with the user.

CustomFilterQuery No Used for filtering based on territory. For example: AvailableTerritories = ('US').

SAP Ariba recommends that you encode this field value using the Base64 encoding scheme and append the encoded value to @ARIBAHEADER@. For example, if the encoded value of AvailableTerritories = ('US') is QXZhaWxhYmxlVGVycml0b3JpZXMgPSAoJ0RFJykgQU5 then enter, @ARIBAHEADER@QXZhaWxhYmxlVGVycml0b3JpZXMgPSAoJ0RFJykgQU5.

Groups No The groups associated with the user.




ShoppingCartAuxID No The shopping cart ID

PreferredSupplierDomain No The supplier domain value that needs to be returned in the shopping cart. For example: duns or networkid.

If left blank, the buyersystemid value is returned by default.

If your system cannot accommodate fields that are over 20 characters in length, use SupplierDomain.

SupplierDomain No The supplier domain value that needs to be returned in the shopping cart.

Use this instead of PreferredSupplierDomain if your system cannot accommodate fields that are over 20 characters in length.

User.Address.UniqueName No SAP Ariba Catalog looks up the value of this field and updates the users address when creating the user.

If your system cannot accommodate fields that are over 20 characters in length, use User.Address.UName.

User.Address.UName No Use this instead of User.Address.UniqueName if your system cannot accommodate fields that are over 20 characters in length.

User.Address.Street No The part of the address that contains the house/apartment number and street/cross name.

User.Address.City No The name of the city in the address.

User.Address.State No The name of the State.

User.Address.PostalCode No The postal code of the address.

If your system cannot accommodate fields that are over 20 characters in length, use User.Address.PCode.

User.Address.PCode No Use this instead of User.Address.PostalCode if your system cannot accommodate fields that are over 20 characters in length.

User.Address.Country No The name of the country/region. The name should be in the format that is loaded in SAP Ariba Catalog.

User.Address.Phone No The phone number of the user.

User.Address.Fax No The fax number of the user.

User.Address.Organization No The name of the organization.

If your system cannot accommodate fields that are over 20 characters in length, use User.Address.Org.



User.Address.Org No Use this instead of User.Address.Organization if your system cannot accommodate fields that are over 20 characters in length.

HTTP_CONTENT_CHARSET

No The name of the character encoding system that the HTTP form POST needs to be encoded in. If the parameter is left blank, the message is encoded in Unicode (UTF-8) by default.

Data flow is as follows:

1. The SAP SRM application initiates the OCI protocol by sending a HTTPS POST request to SAP Ariba Catalog.2. After receiving the request, SAP Ariba Catalog redirects the request to a corporate authenticator. SAP Ariba

Catalog should be configured to use a corporate authenticator when enabling the customer site for punchin users.

3. The corporate authenticator authenticates the user and redirects the user to SAP Ariba Catalog.4. The user can now browse catalogs in SAP Ariba Catalog.5. After the user completes the shopping session, SAP Ariba Catalog sends the shopping cart contents to SAP

SRM as part of form fields as specified by the OCI specifications below:

Field Name Description Example

NEW_ITEM-ShoppingCartID[#] The lookup key for the shopping cart in SAP Ariba Catalog.

NEW_ITEM-DESCRIPTION[#] The description of the item in the catalog.(Only the first 40 characters are displayed.)

Rayovac 1.5V Alkaline Maximum Batteries

NEW_ITEM-MATGROUP[#] The material group for the item in SAP SRM.

NEW_ITEM-EXT_CATEGORY[#] The commodity code value. 26111702

NEW_ITEM-EXT_SCHEMA_TYPE[1] The commodity code domain. unspsc

NEW_ITEM-MATNR[1] The product number of the item in SAP SRM. [Partitioned Commodity Code]

NEW_ITEM-QUANTITY[1] The item quantity. 1

NEW_ITEM-UNIT[1] The type of the item quantity. BX

NEW_ITEM-PRICE[1] The price of the item. 3.02

NEW_ITEM-PRICEUNIT[1] The price of one unit. 1

NEW_ITEM-CURRENCY[1] The currency of the item. USD

NEW_ITEM-LEADTIME[1] The lead time for the item to be available. 0

NEW_ITEM-VENDOR[1] The Supplier ID. sid498

NEW_ITEM-VENDORMAT[1] The Supplier Part Number. RAY19844

NEW_ITEM-MANUFACTCODE[1] The manufacturer number of the item.

NEW_ITEM-MANUFACTMAT[1] The manufacturer's part number for the item. 824-2




NEW_ITEM-SERVICE The flag indicating if an item is a services procurement item (defined by category definitions).

"X" indicates a services procurement item.

NEW_ITEM-EXT_PRODUCT_ID[1] The unique key for this item in the catalog which is a combination of Supplier ID ,SupplierPartID and SupplierAuxillaryPartID and separated by the ¦ character.

Sid498 ¦ RAY19844¦

NEW_ITEM-LONGTEXT_1:132[] SAP Ariba uses long text attribute to add description and other details associated with catalog items. The format is as below:

Catalog Item Description nlCOLLABORATION_ATTRIBUTES nlattribute: value nlnlCOLLABORATION_ATTRIBUTES_BASE64 nlITEM_ATTRIBUTES nlattribute: value nlnlCLASSIFICATION_CODES nldomain: value nlnl

Where nl represents new line separators in the input.

Rayovac 1.5V Alkaline Maximum Batteries - AAA - 2/Pack

NEW_ITEM-CUST_FIELD1[#] Userdefined custom field. The maximum length is 10 characters.





If you are using the SAP Ariba Spot Buy Catalog solution, the following additional fields are included to identify spot buy purchases:


NEW_ITEM-StoreNetworkID The marketplace on which the purchase is being made. The maximum length is 128 bytes. This is stored in the SRM at item level. It is not transferred to the ERP.

eBay



NEW_ITEM-StoreSupplierID The supplier ID. The maximum length is 64 bytes. This is stored in the SRM at item level. It is not transferred to the ERP.

NEW_ITEM-VENDORMAT This a standard OCI field that stores a transaction number for spot buy. This is transmitted to the SRM and later to Ariba Network. This is used to identify and match the spot buy item on Ariba Network.

A combination of NEW_ITEM-StoreNetworkID and NEW_ITEM-StoreSupplierID is required to identify a supplier. These fields are used to split items into corresponding purchase orders.

Secure Integration using secure OCI

SAP Ariba Catalog supports secure OCI parameters in punchin requests from external systems. Secure OCI available in OCI 5.0 enables transfer of login information such as username, Punchin ID, and Punchin Password over backend HTTP calls thereby ensuring enhanced security of sensitive information.

For more information on enabling your SAP SRM system to support this feature, see SAP Note 2213376.

Overview of punching in to SAP Ariba Catalog using secure OCI

Punching in to SAP Ariba Catalog using secure OCI involves the following high level steps:

1. SAP SRM sends a backend call to SAP Ariba Catalog.

The backend call must contain the following data along with other required parameters such as username and password :

○ SECURE_AUTH_URL○ SECURE_TRANSMISSION○ FUNCTION (Value must be set to INITIALIZE)○ SECURE_AUTH_METHOD

2. SAP Ariba Catalog persists the incoming data, generates a SessionId and a SessionTransmissionId, and sends them to SAP SRM as an XML.

3. SAP SRM sends a request to SAP Ariba Catalog with the SessionId to launch the catalog.4. SAP Ariba Catalog pocesses the request and displays the catalog after authentication.

For more information about the parameters, see Secure OCI parameters [page 21].



Overview of retrieving shopping cart data from SAP Ariba Catalog

Retrieving shopping cart data from SAP Ariba Catalog using secure OCI involves the following high level steps:

1. SAP SRM sends a backend call to SAP Ariba Catalog to retrieve the shopping cart details.

The backend call must contain the following data along with other required parameters :

○ SessionTransmissionId○ FUNCTION (Value must be set to RETRIEVEOCI)○ SECURE_AUTH_METHOD

2. SAP Ariba Catalog pocesses the request and sends the shopping cart details associated with the SessionTransmissionId to SAP SRM.

For more information about the parameters, see Secure OCI parameters [page 21].

Secure OCI parameters

Secure OCI parameters for initial handshake

The following table lists the parameters and the possible values to be sent to SAP Ariba Catalog in the initial backend call using Secure OCI:

Parameter Description Value

username The user id to punch in to SAP Ariba Catalog. User ID

password The password associated with the PunchinId. password

The following special characters are not supported: " , < , > , [ , \ , ] , ^ , ` , { , | , }

SECURE_AUTH_URL The URL to punch in to SAP Ariba Catalog. URL

For example: http://s1.ariba.com:8050/Buyer/test-catserver/content/ContentDataReceiver

SECURE_TRANSMISSION

Indicates the call for retrieving session data X



FUNCTION Indicates the action to be taken by SAP Ariba Catalog.

The value INITIALIZE indicates that SAP Ariba Catalog must generate a SessionId and a SessionTransmissionId.

INITIALIZE

SECURE_AUTH_METHOD

Determines the HTTP method to be used by SAP Ariba Catalog to send the response to the backend call.

GET/POST

Default to POST

XML response to the initialization backend call

In response to the initialization backend call, SAP Ariba Catalog generates a SessionId and a SessionTransmissionId, and sends them to the external system as an XML. These elements along with username and password are persisted in SAP Ariba Catalog for further communication. For example:

<SecureOCI> <SessionId>8081457345719230120</SessionId><SessionTransmissionId>7551489217863242754</SessionTransmissionId> </SecureOCI>

The SessionId is used by the external system in the request to SAP Ariba Catalog to launch the catalog, and the SessionTransmissionId in the request to retrieve the shopping cart contents from SAP Ariba Catalog.

NoteThe SessionId and SessionTransmissionId are valid only in the current session and will be deleted from the database after the shopping cart contents have been checked out to the external system.

Request to launch the catalog

The external system sends a request to SAP Ariba Catalog with the SessionId to launch the catalog. The following table lists the parameters and their possible values required to launch the catalog using Secure OCI:


HOOK_URL The URL of the external system to which SAP Ariba Catalog must return the catalog data.

URL

PunchinId Unique identifier of SAP Ariba Catalog Ariba Network ID

SessionId The Session ID generated by SAP Ariba Catalog for the current punchin session.

SessionId



A sample request to launch the catalog is as follows:

HOOK_URL=http://sapnw07.ariba.com:50100/... PunchinId:AN29843529843 SessionId=8081457345719230120

Backend call to retrieve the shopping cart contents from SAP Ariba Catalog

The following table lists the required parameters and their possible values to be sent in the backend call to retrive the shopping cart contents from SAP Ariba Catalog using secure OCI:


SessionTransmissionId The Session Transmission ID generated by SAP Ariba Catalog for the current punchin session.

Session Transmission ID

FUNCTION Indicates the action to be taken by SAP Ariba Catalog.

The value RETRIEVEOCI indicates that SAP Ariba Catalog must send the shopping cart contents associated with the specified SessionTransmissionId to the external system.

RETRIEVEOCI

SECURE_AUTH_METHOD Determines the HTTP method to be used by SAP Ariba Catalog to send response to the backend call.

POST

A sample backend call to retrieve shopping cart contents is as follows:

HOOK_URL=http://sapnw07.ariba.com:50100/... PunchinId:AN29843529843FUNCTION= RETRIEVEOCISECURE_AUTH_METHOD:POSTSessionTransmissionId=7551489217863242754

A sample response from SAP Ariba Catalog with the shopping cart contents is as follows:

<?xml version="1.0"?> <ocisecurity> <OCIField>NEW_ITEM-ShoppingCartID[1] </OCIField> <OCIValue>SH73 </OCIValue> <OCIField>NEW_ITEM-DESCRIPTION[1] </OCIField> <OCIValue>SSP-3793 Catalog-Item For JCN </OCIValue> <OCIField>NEW_ITEM-MATGROUP[1] </OCIField> <OCIValue></OCIValue> <OCIField>NEW_ITEM-EXT_CATEGORY[1] </OCIField> <OCIValue>43211800 </OCIValue> <OCIField>NEW_ITEM-EXT_SCHEMA_TYPE[1] </OCIField> <OCIValue>unspsc </OCIValue> <OCIField>NEW_ITEM-MATNR[1] </OCIField> <OCIValue></OCIValue> <OCIField>NEW_ITEM-QUANTITY[1] </OCIField> <OCIValue>1.000 </OCIValue> <OCIField>NEW_ITEM-UNIT[1] </OCIField> <OCIValue>EA </OCIValue> <OCIField>NEW_ITEM-PRICE[1] </OCIField> <OCIValue>44.000 </OCIValue> <OCIField>NEW_ITEM-PRICEUNIT[1] </OCIField> <OCIValue>1 </OCIValue>


<OCIField>NEW_ITEM-CURRENCY[1] </OCIField> <OCIValue>USD </OCIValue> <OCIField>NEW_ITEM-LEADTIME[1] </OCIField> <OCIValue>3 </OCIValue> <OCIField>NEW_ITEM-VENDOR[1] </OCIField> <OCIValue>sid496 </OCIValue> <OCIField>NEW_ITEM-VENDORMAT[1] </OCIField> <OCIValue>SSP-3793CAT </OCIValue> <OCIField>NEW_ITEM-MANUFACTCODE[1] </OCIField> <OCIValue>Hallmark Cables </OCIValue> <OCIField>NEW_ITEM-MANUFACTMAT[1] </OCIField> <OCIValue>SSP-3793CAT </OCIValue> <OCIField>NEW_ITEM-CONTRACT[1] </OCIField> <OCIValue></OCIValue> <OCIField>NEW_ITEM-CONTRACT_ITEM[1] </OCIField> <OCIValue></OCIValue> <OCIField>NEW_ITEM-EXT_PRODUCT_ID[1] </OCIField> <OCIValue>sid496|SSP-3793CAT </OCIValue> <OCIField>NEW_ITEM-LONGTEXT_1:132[] </OCIField> <OCIValue>SSP-3793 Catalog-Item For JCN </OCIValue> <OCIField>NEW_ITEM-SERVICE[1] </OCIField> <OCIValue></OCIValue></ocisecurity>

Advanced SAP SRM configuration settingsAdvanced configuration settings for SAP SRM included catalog filtering, mapping custom fields, and supporting open catalog interface functions.

Catalog filtering using OCI outbound parameters

Catalogs can be filtered in SAP Ariba Catalog based on certain OCI outbound (from SAP SRM) parameters.

CustomFilterQuery

All out of the box catalog fields and custom catalog fields that have one the following type attribute properties set to yes can be specified as constraints in the CustomFilterQuery extrinsic element:

● isSearchable● isRefinable

TerritoryAvailable is used as a name pair value in CustomFilterQuery values. TerritoryAvailable is a field available out of the box in catalogs. Each catalog item needs to be loaded with Territory Available (single or multiple) field values. When a user punches in with Territory Available values, the catalogs are filtered based on territoryavailable value in the OCI outbound parameter.

For example, if the OCI outbound parameter field CustomFilterQuery has the following values:

AvailableTerritories = ('DE') AND AvailableTerritories = ('US')



then SAP Ariba Catalog displays only the catalog items that have DE and US as Territory Available values.

Supplier ID is used a constraint to filter catalogs based on suppliers. The following formats can be used to specify the constarint in the OCI outbound parameter:

● supplierID.SupplierDomain = (’Value’) to specify a single value● supplierid IN (‘SupplierDomain:Value1’, ‘SupplierDomain:Value2’) to specify multiple values

For example:

● supplierid.buyersystemid = (‘sid497’)● supplierid IN ('buyersystemid:sid497', buyersystemid:sid499

RecommendationSAP Ariba recommends that you encode the CustomFilterQuery field value using the Base64 encoding scheme and append the encoded value to @ARIBAHEADER@. For example, if the encoded value of AvailableTerritories = ('US') is QXZhaWxhYmxlVGVycml0b3JpZXMgPSAoJ0RFJykgQU5 then enter, @ARIBAHEADER@QXZhaWxhYmxlVGVycml0b3JpZXMgPSAoJ0RFJykgQU5.

Groups

Catalog Views can be used to filter catalogs. The OCI outbound parameter Group must have the value of the group on which a catalog view is based in SAP Ariba Catalog.

To filter based on groups:

1. Create catalog views in SAP Ariba Catalog based on groups.2. Enter the name of the group on which the catalog view is based as the value for the OCI outbound parameter

Group.When a user punches in to SAP Ariba Catalog, the catalogs are filtered based on the group value in the OCI outbound parameter. For more information on Catalog Views, see the Catalog administration guide for buyers.

Purchasing Units

Purchasing Units can be used to filter suppliers. Catalogs can then be filtered based on the filtered suppliers.

To filter based on purchasing units:

● Map the purchasing units to suppliers when importing suppliers in SAP Ariba Catalog.● Enter the name of the purchasing unit as the value for the OCI outbound parameter Purchasing Unit.

When a user punches in to SAP Ariba Catalog, the catalogs are filtered based on the suppliers that are mapped to the purchasing unit.For more information on Purchasing Units, see the Purchasing unit administration guide.


Using standard customization to map custom fields for SAP SRM

You can pass custom fields from SAP Ariba Catalog as OCI parameters to SAP SRM. Custom catalog fields can be mapped to any of these custom fields in SAP Ariba Catalog.

Creating custom catalog fields involves defining supplemental attributes (extensible catalog fields) in type definition files. Contact SAP Ariba Customer Support to load type definitions.

For example, to map the Hazardous Material field value to the NEW_ITEM-CUST_FIELD2[#] OCI parameter:

<inClass name="ariba.content.core.ShoppingCartLineItem"> <derived> <field name="cus_Attribute1" expression="getAnalyazableAttributes('hazmat')" templates="OCIAttributes"> <type class="java.lang.String"/> <properties label="NEW_ITEM-CUST_FIELD2[#]"/> </field> </derived> </inClass>

For more information on customization and managing type definitions, contact SAP Ariba Customer Support.

Supporting OCI functions

Validating item details

SAP Ariba Catalog supports catalog item validation requests in OCI format from SAP SRM.

SAP SRM sends a request to SAP Ariba Catalog to validate the catalog items using the OCI VALIDATE function. SAP Ariba Catalog then responds with an HTML page that contains a form with the latest product data in the OCI 4.0 format.

A sample punchin URL is as follows: https://s1.ariba.com/Buyer/Main/ad/contentPunchin/OCIPunchinDirectAction/<ANID> where <ANID> is the Ariba Network ID value for SAP Ariba Catalog.

Copy Requisition in SAP Supplier Relationship Management

In SAP SRM, you can select and copy a requisition. SAP SRM initiates the OCI VALIDATE function in SAP Ariba Catalog. SAP Ariba Catalog, then, validates the catalog items and returns a response. Based on the response from SAP Ariba Catalog, SAP SRM copies the items.



OCI VALIDATE function implementation overview

Consider the following guidelines while implementing the OCI VALIDATE function for SAP SRM inSAP Ariba Catalog:

● Blank search of catalog items are not allowed. Product ID must be provided to search for catalog items.● Search for Product ID is case sensitive. If the case for product IDs does not match with the product ID in SAP

Ariba Catalog, then the search for the product ID fails and the “No line item found” error message is sent back as a response to OCI VALIDATE function request.

● When search for Product ID has multiple results, only the first result will be sent back as a response to OCI validate function request.

● No retry option is available for catalog search. However, SAP SRM can have its own retry option in case of a failure.

Support for catalog item validation requests from SAP SRM in SAP Ariba Catalog involves the following steps:

● SAP SRM sends a HTTPS POST request to SAP Ariba Catalog with certain parameter values that initiates the VALIDATE function in OCI protocol.

● SAP Ariba Catalog sends a HTTPS POST response to SAP SRM with the relevant catalog item details associated with each PRODUCT ID parameter value.

The Open Catalog Interface (OCI) uses the following structure to provide all the information that is necessary to support OCI with a product catalog. The request comprises of the following:

Parameter Description

HOOK_URL The parameter name must be HOOK_URL.The value of the return URL must be empty; the actual return URL is determined during run time by SAP SRM.

PunchinId Ariba Network ID that allows suppliers to punch in to SAP Ariba Catalog and use the PunchOut capability.

PunchinPassword A password that allows suppliers to punch in to SAP Ariba Catalog and use the PunchOut capability.

realm SAP Ariba Catalog realm ID

PRODUCTID Database key for the product in the catalog.

The Product ID is a combination of the Buyer System ID, Supplier Part ID, and the Supplier Part Auxiliary ID.

QUANTITY Current quantity

FUNCTION VALIDATE

UniqueName A variable that holds a unique name ID of the user punchin to SAP Ariba Catalog


Sample CodeSample OCI Request

HOOK_URL=http://fakhan1.ariba.com:8050/Buyer/test-catserver/content/ContentDataReceiver? PunchinId=AN02000429399PunchinPassword=welcome1arealm=apcAippSapPRODUCTID=sid498|RAY45047|aux83667QUANTITY=1FUNCTION=VALIDATE UniqueName=adavis

Sample CodeSample OCI Response

NEW_ITEM-MANUFACTMAT[1]=714-2 NEW_ITEM-SERVICE[1]=NEW_ITEM-QUANTITY[1]=1NEW_ITEM-PRICE[1]=7.840NEW_ITEM-EXT_CATEGORY[1]=26111701NEW_ITEM-EXT_PRODUCT_ID[1]=sid498|RAY45047|aux83667NEW_ITEM-VENDORMAT[1]=RAY45047NEW_ITEM-VENDOR[1]=sid498NEW_ITEM-UNIT[1]=BXNEW_ITEM-MATGROUP[1]=R1133NEW_ITEM-DESCRIPTION[1]=Rayovac Renewal Reusable Alkaline Batteries -...NEW_ITEM-PRICEUNIT[1]=1NEW_ITEM-CUST_FIELD1[1]=NEW_ITEM-LONGTEXT_1:132[1]=Rayovac Renewal Reusable Alkaline Batteries - C - 2/PackNEW_ITEM-MANUFACTCODE[1]=NEW_ITEM-CURRENCY[1]=USDNEW_ITEM-LEADTIME[1]=1NEW_ITEM-EXT_SCHEMA_TYPE[1]=unspscNEW_ITEM-CONTRACT[1] ::NEW_ITEM-CUST_FIELD1[1] ::collared:falseNEW_ITEM-CUST_FIELD2[1] ::size:small, medium, largeNEW_ITEM-CUST_FIELD3[1] ::color:orange, blueNEW_ITEM-CUST_FIELD4[1] ::bestprice: NEW_ITEM-CUST_FIELD5[1] ::hazardousmaterials:

The naming convention for the fields in OCI is as follows:

NoteNEW_ITEM-<Field name>[<index>]. The field type is always CHAR.

Field Description

NEW_ITEM-MANUFACTMAT Item’s manufacturer part number

NEW_ITEM-SERVICE Flag: the item is a service.

NEW_ITEM-QUANTITY Item quantity

NEW_ITEM-PRICE Price of an item per price unit



Field Description

NEW_ITEM-EXT_CATEGORY Unique key for an external category from the schema above, dependent of the version of the schema

NEW_ITEM-EXT_PRODUCT_ID Unique database key for this item in the catalog

NEW_ITEM-VENDORMAT Vendor product number for the item

NEW_ITEM-VENDOR SRM vendor number (business partner) for the item

NEW_ITEM-UNIT Quantity unit for item quantity

NEW_ITEM-MATGROUP SRM Material group for the item

NEW_ITEM-DESCRIPTION Description of the item

NEW_ITEM-PRICEUNIT Price unit of the item (if empty, 1 is used)

NEW_ITEM-CUST_FIELD[n] User defined field

NEW_ITEM-LONGTEXT_n:132 Long text for the item

NEW_ITEM-MANUFACTCODE Manufacturer number of the item

NEW_ITEM-CURRENCY[n] Item currency

NEW_ITEM-LEADTIME[n] Delivery time of the item in days

NEW_ITEM-EXT_SCHEMA_TYPE[n] Name of a schema via which it was imported in the Server

NEW_ITEM-CONTRACT[n] SRM contract to which the item refers

NEW_ITEM-CUST_FIELD1[n] Userdefined field





Displaying item details

SAP Ariba Catalog supports requests for catalog item details from SAP SRM and displays the relevant item details page. The OCI DETAIL function supports this functionality.

SAP Ariba Catalog does not support requests for item details for the following types of items:

● Non-Catalog items● PunchOut items

You must configure SAP SRM, to send relevant data in the requests for the details of catalog items that had previously been added from SAP Ariba Catalog.


The following table lists the mandatory outbound parameters that must be configured in the outbound requests from SAP SRM to SAP Ariba Catalog:

Parameter Value Description

FUNCTION DETAIL The function value required to request catalog item details.

PRODUCTID <Databse key for the item in the catalog>

The unique ID of the catalog item that had previously been added from SAP Ariba Catalog

Extracting catalog data in JSON format

SAP Ariba Catalog supports requests to extract catalog data in JavaScript Object Notation (JSON) format from SAP SRM. SAP Ariba Catalog processes and authenticates the requests, and sends the relevant catalog data over HTTP in JSON format that is compatible with the OCI 5.0 specification.

As part of supporting this functionality, SAP Ariba Catalog supports the DOWNLOADJSON value for the FUNCTION parameter and supports requests for both full and delta extraction of catalog data.

By default, all catalog subscription data that has been validated and is available for search in the SAP Ariba Catalog user interface is available for extraction, but the following data cannot be extracted:

● Catalog data related to punchout items.● Catalog data related to catalog subscriptions generated by contracts and category definitions.● Catalog data related to advanced pricing details, such as Price Unit, Price Unit Quantity, Unit

Conversion, Pricing Description.

Parameters to Configure Requests for Catalog Data Extraction

You must configure SAP SRM, to send relevant data in the requests for catalog data extraction from SAP Ariba Catalog and to consume the data that is sent as a response.

The following table lists the parameters that must be configured in the requests for catalog data extraction:

Table 1:

Parameter Name Mandatory Value Description

URL Yes https://s1-integration.ariba. com/Buyer/downloadJson/<ANID>

Replace <ANID> with the Ariba Network ID value for SAP Ariba Catalog.

The HTTP URL provided by SAP Ariba Catalog through which catalog data can be extracted to external systems.




PunchinId Yes Ariba Network ID Unique identifier of SAP Ariba Catalog.

UserId Yes Login User ID to login to SAP Ariba Catalog.

password Yes password Password for a specific user ID.

FUNCTION Yes DOWNLOADJSON The function value required to extract catalog data from SAP Ariba Catalog.

EXTRACTIMAGE No true Set to true to extract data related to catalog image files.

NoteThe extracted catalog image data may contain some proprietary information such as, copyright notices or watermarks. No part of the image-related data may be distributed, reproduced, or transmitted in any form other than for the intended catalog use.

PAGESIZE No X The number of items that would be sent/received in one single call. For example, 20.

REQUESTEDPAGE No X The page requested by the external system. This parameter value is specified in requests for delta extraction of catalog data.

LASTUPDATED No Timestamp in DDMMYYYYHHMMSS format

Indicates the time when the last successful catalog extraction request was processed. This value is blank for the initial request and must be populated for subsequent requests for delta extraction of catalog data.



TRANSACTIONID No Transaction ID A unique identifier sent by SAP Ariba Catalog with the catalog data for each request. This value is blank for the initial request and must be populated for subsequent requests for delta extraction of catalog data.

CATALOGPREFIX No keyword You can request for data from specific catalogs to be extracted from SAP Ariba Catalog.

Catalog data that is extracted can be filtered based on the associated catalog filenames.

Data from only those catalogs are extracted whose filename starts with the value speified as the CATALOGPREFIX.

A sample URL to punch in to SAP Ariba Catalog to extract catalog data with images is as follows: https://<localhost>:<port>/Buyer/downloadJson/<ANID>?PunchinId=<ANID>&UserId=<username>&password=<password>&PAGESIZE=<Page_Size_Number>&realm=<site_name>&FUNCTION=downloadjson&EXTRACTIMAGE=true&CATALOGPREFIX=<keyword>

If you site is configured for basic access authentication, you must specify the userid and password values encrypted using the Base64 encoding scheme. The encrypted userid and password must be specified in the HTTP authorization header in the Authorization = “Basic base64Encypted(user:pass)” format. For example: Authorization = “Basic Y25vbGw6YXJpYmE=”

A sample URL with basic access authentication is as follows: https://<localhost>:<port>/Buyer/downloadJson/<ANID>?PunchinId=<ANID>&realm=<site_name>&FUNCTION=downloadjson

Response to Catalog Data Extraction Requests

SAP Ariba Catalog processes and authenticates the requests for catalog data and sends the relevant catalog data to the external system in JSON over HTTP if the request passes authentication. If the request fails authentication, SAP Ariba Catalog sends relevant error messages to the external system over HTTP.



The following table lists the parameters that are sent by SAP Ariba Catalog as a response to catalog data extraction requests:

Name Value

CURRENTPAGE The number of the current page that is being sent by SAP Ariba Catalog.

TOTALPAGES The total number of pages that the catalog data is being delivered in for a particular transaction.

TOTALITEMS The total number of items being delivered in a particular transaction.

TRANSACTIONID The unique identifier sent by SAP Ariba Catalog for a given transaction.

CTI Complete Transmission Indicator. This value, when set to true, indicates that the transaction is a request for a full catalog data extract. If not set, it indicates that the request is for a delta catalog data extract.

Troubleshooting SAP SRM IntegrationUse a web-debugging tool (for example, Fiddler) to debug any errors or missing data. Errors may include invalid fields, validity of data in OCI, and missing scroll bars in SAP Ariba Catalog.

A sample debug output is as following:

Setup Request

POST /Buyer/Main/ad/contentPunchin/OCIPunchinDirectAction?realm=realm_5 HTTP/1.1 Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, application/vnd.ms-excel, application/vnd.ms-powerpoint, application/msword, application/x-shockwave-flash, */*Accept-Language: en-usContent-Type: application/x-www-form-urlencodedAccept-Encoding: gzip, deflateCookie: DefaultTab=buyerUser-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; InfoPath.1; .NET CLR 1.1.4322; .NET CLR 2.0.50727)Host: svcdevss.ariba.comContent-Length: 585Connection: Keep-AliveCache-Control: no-cache


PunchinId=ANXXXXXXXXXXX&PunchinPassword=secret&UserName=bwayne&realm=realm_5&Url=+&HOOK_URL=http://customer.com/returnURL

Setup Response

HTTP/1.1 302 Moved Temporarily Date: GMTServer: Apachecache-control: no-cachepragma: no-cacheVary: Accept-Encoding,User-AgentContent-Encoding: gzipKeep-Alive: timeout=120, max=100Connection: Keep-AliveTransfer-Encoding: chunkedContent-Type: text/html;charset=UTF-8NEW_ITEM-ShoppingCartID1=SH138&NEW_ITEM-DESCRIPTION1=Testing+Partial+Item&NEW_ITEM-MATGROUP1=&NEW_ITEM-EXT_CATEGORY1=22&NEW_ITEM-EXT_SCHEMA_TYPE1=unspsc&NEW_ITEM-MATNR1=&NEW_ITEM-QUANTITY1=20.000&NEW_ITEM-UNIT1=EA&NEW_ITEM-PRICE1=30.000&NEW_ITEM-PRICEUNIT1=1&NEW_ITEM-CURRENCY1=USD&NEW_ITEM-LEADTIME1=0&NEW_ITEM-VENDOR1=sid483&NEW_ITEM-VENDORMAT1=supplier+part+no+123&NEW_ITEM-MANUFACTCODE1=&NEW_ITEM-MANUFACTMAT1=&NEW_ITEM-EXT_PRODUCT_ID1=& NEW_ITEM-LONGTEXT_1132=Item Description&

Invalid fields

Issue: An error occurs on punchin indicating that one or more field values are invalid.

Reason: One or more mandatory field values have not been populated. For example: Email Address, PunchinId etc.

Fix: Populate all the mandatory fields with relevant values.

Missing scrollbar in SAP Ariba Catalog

Issue: The scrollbar is not displayed in SAP Ariba Catalog when users punchin from SAP SRM 7.0 through the SAP NetWeaver Portal.

Reason: This is happening because the appropriate parameter in the window.open JavaScript method (that enables the scrollbar to be displayed in the new popup window) is not configured correctly.



Fix: Configure the windowFeatures parameter in the window.open JavaScript method to enable the scrollbars to be displayed in the new popup window as following:

To enable the scrollbars to be displayed in the new popup window:

window.open ("http://www.correctsitename.com", "mywindow","location=1,status=1,scrollbars=1")

For more information, see Using the window.open Method [page 35].

Using the window.open method

The syntax of the window.open method is as following:

open (URL, windowName[, windowFeatures])

URL: The URL of the page to open in the new window. This argument could be blank.

windowName: A name to be given to the new window. The name can be used to refer this window again.

windowFeatures: A string that determines the various window features to be included in the popup window (like statusbar, address bar etc).

The following code opens a new browser window with standard features.

window.open ("http://www.javascript-coder.com","mywindow")

Changing the features of the popup window

You can control the features of the popup using the last argument to the window.open method. The following table shows the features and the string tokens you can use in the windowfeatures parameter:

status The statusbar at the bottom of the window

toolbar The standard browser toolbar, with buttons such as Back and Forward

location The Location entry field where you enter the URL

menubar The menu bar of the window

directories The standard browser directory buttons, such as What’s New and What’s Cool

resizable Allow/Disallow the user to resize the window

scrollbars Enable the scrollbars if the document is bigger than the window

height Specifies the height of the window in pixels. (example: height=’350?)

width Specifies the width of the window in pixels

Examples:

The following code opens a window with a statusbar and no extra features.

window.open ("http://www.correctsitename.com","mywindow","status=1");


The following code opens a window with toolbar and statusbar:

window.open ("http://www.correctsitename.com", "mywindow","status=1,toolbar=1");

The following code opens a window with menu bar. The window is re-sizable and is having 350 pixels width and 250 pixels height:

window.open ("http://www.correctsitename.com","mywindow","menubar=1,resizable=1,width=350,height=250");

The following code opens a window with location bar, statusbar, scrollbar and of size 100 X 100:

window.open ("http://www.correctsitename.com", "mywindow","location=1,status=1,scrollbars=1, width=100,height=100");

The following code opens a window with location bar and no scrollbars:

window.open ("http://www.correctsitename.com", "mywindow","location=1,status=1,scrollbars=0");

Validity of data in Open Catalog Interface

SAP SRM users may encounter the following errors related to the validity of data in Open Catalog Interface:

Error Resolution

Unable to retrieve product ID Ensure the product ID is correct and try again

Invalid user ID Ensure the user ID is correct and try again

No record was found for the given product ID Ensure the product ID is correct and try again

Invalid value for the Ariba Network ID field Ensure the value for the Ariba Network ID is correct and try again

Product ID validation failed due to an unexpected error Enter the correct product ID and try again



Configuring SAP Ariba Catalog features

Support for sending item type information from SAP Ariba Catalog [page 37]

Support for punching in during contract creation [page 38]

Support for displaying external contract links [page 39]

Supporting catalog search using web services [page 43]

Support for sending item type information from SAP Ariba Catalog

SAP Ariba Catalog sends information regarding the type of items in the shopping cart to external systems.

The item type information for each item in a shopping cart is sent from SAP Ariba Catalog to external procurement systems at checkout, to help identify if an item is a catalog, non-catalog, punchout, or a partial item. However, the information if an item is collaborative or not, is not available to be sent to the external procurement system. The item type information is sent as cXML extrinsic elements or can be mapped to one or more OCI custom fields.

NoteThis feature is applicable only to external procurement systems that integrate with SAP Ariba Catalog using cXML or OCI-based protocols.

For external procurement systems that integrate with SAP Ariba Catalog using cXML-based protocols, the item type information is sent as extrinsic elements. For external procurement systems that integrate with SAP Ariba Catalog using OCI-based protocols, such as SAP SRM, the item type information can be mapped to one or more custom fields as per the OCI specification.

SAP Ariba Catalog sends the item type information of the items in the cart in the PunchOutOrderMessage document. Your external procurement system must be configured to consume and process this item type information sent by SAP Ariba Catalog.

The following table lists the cXML extrinsic elements and their values for each type of item:

Table 2:

Type of Item cXML Extrinsic Element Value

Regular Catalog Item IsAdHoc No

Non-Catalog Item IsAdHoc Yes

PunchOut Item IsPunchOut Yes

SAP Ariba Catalog integration guideConfiguring SAP Ariba Catalog features PUBLIC 37

Type of Item cXML Extrinsic Element Value

Partial Item IsPartial Yes

The following is a sample cXML PunchOutOrderMessage document indicating a punchout item in a shopping cart:

Sample Code

<ItemDetail> ... <Extrinsic name="IsAdHoc">No</Extrinsic> <Extrinsic name="IsPartial">No</Extrinsic> <Extrinsic name="IsPunchOut">Yes</Extrinsic> ... </ItemDetail>

Support for punching in during contract creation

SAP Ariba Catalog supports punchin from an external system to add items to a contract.

NoteThis feature is applicable only to external procurement systems that integrate with SAP Ariba Catalog using cXML-based protocols.

You can punch in to SAP Ariba Catalog to add items, when creating an item level contract in an external procurement system. To enable this functionality, you must configure your external procurement system to insert the following extrinsic element data in the PunchOutSetupRequest document that is sent to SAP Ariba Catalog:

● APCMode - The value of this extrinsic element must be set to Modal.● ModalTitle - The value of this extrinsic element is displayed as the title of the page in SAP Ariba Catalog.

For example,

Sample Code

<PunchOutSetupRequest operation="create"> <BuyerCookie>12345678</BuyerCookie> <Extrinsic name="User">adavis</Extrinsic> <Extrinsic name="APCMode">Modal</Extrinsic> <Extrinsic name="ModalTitle ">CR12 : Select catalog items</Extrinsic> ...

When you add items to a contract, the following information is not sent to the external procurement system:

● Values of item attributes in partial items● Contractible properties in services items

Hence, you cannot define contract terms based on these fields



NoteYou can add only one item in each punchin session.

Support for displaying external contract linksSAP Ariba Catalog supports the display of external contract IDs as hyperlinks on all relevant catalog pages.

SAP Ariba Catalog can receive and process basic contract information (such as contract ID, contract type, and status) from external systems through AribaWeb Services. To enables users to identify items associated with external contracts, SAP Ariba Catalog displays the external contract IDs as hyperlinks on all relevant catalog pages.

Additional information such as pricing terms and conditions of external contracts is not available in SAP Ariba Catalog. To view this information, users can click the external contract ID hyperlinks displayed in the catalog pages in SAP Ariba Catalog. The links direct users to the relevant pages in the external system. So, when users add catalog items associated with external contracts to shopping carts, SAP Ariba Catalog does not apply the contract terms to the items, because the relevant contract information is not available in SAP Ariba Catalog.

This feature is applicable to the following types of contracts:

● Supplier-level contract● Commodity-level contract● Item-level contract

To enable this functionality, you must:

● Set up your external system to send basic contract information to SAP Ariba Catalog usingWeb Services.● Configure your customer site to receive basic contract information from external systems using Web Services.

For more information, see Configuring support for external contracts [page 39]

Configuring support for external contracts

SAP Ariba Web Services use the W3C SOAP messaging framework to exchange messages over HTTPS. Your external system, when configured, sends basic contract information to SAP Ariba Catalog as a SOAP message.

As part of configuring your customer site to receive the contract information sent by external systems, you must do the following:

● Configure the inbound end point for the communication channel used by the Web Service● Enable the External Contract Information Web Services integration task

NoteYou must be a member of the Customer Administrator or Integration Admin groups to perform these tasks.

For more information about, SAP Ariba Web Services and configuring end points, see the Administration and data maintenance fundamentals.


How to configure the inbound end point

Context

To configure the inbound end point for the communication channel used by the Web Service:

Procedure

1. In Ariba Administrator, choose Integration Manager > End Point Configuration.2. Click Create New to create a new end point.3. In the Name field, enter a name for the end point.4. Select Inbound as the type of end point. Inbound end points are used when the task is initiated by the external

system.5. To use HTTP Basic Authentication, navigate to the HTTP Authentication area. Enter the user ID in the Login

field and the password in the Password fields.You must provide this information to the administrator of the external system.

6. Click Save.

How to enable the Web Services integration task

Context

To enable the External Contract Information Web Services integration task

Procedure

1. In Ariba Administrator, choose Integration Manager > Integration Configuration.2. Find the External Contract Information task. Choose List All or enter search criteria and click Search.3. Choose Actions > Edit for the task.4. In the Status field, click Enabled, and make sure the Format field specifies Web Service.5. In the End Point pull-down menu, select the inbound end point that you created earlier.6. Click Save.



Sample soap messages

Your external system, when configured, publishes a SOAP message (Request) to SAP Ariba Catalog with basic contract information. SAP Ariba Catalog consumes this SOAP message and sends an acknowledgement back as an ID or error in a SOAP message (Response).

Sample SOAP Request Message

The following table describes the elements in the SOAP request message:

Table 3:

Element Mandatory Value Description

Contract Yes Contract ID The unique ID of the contract.

ContractLine Yes Contract Line Number The line number of the item in the contract.

ExternalContractURL Yes URL The URL provided by the external system to access the contract details in the external system.

MAState Yes 8 or 16 Indicates the contract state.

8 - Open

16 - Closed

TermType Yes 0, 1, or 2 Indicates the contract type.

0 - supplier-level contract.

1 - commodity-level contract.

2 - item-level contract.

SupplierId Yes Supplier ID The unique ID of the supplier.

SupplierPartId Yes for item-level contracts.

Supplier Part ID The supplier part ID.


Element Mandatory Value Description

CCHierarchy Yes for commodity-level contracts.

Commodity Code The commodity code number.

A sample SOAP request message is as follows:

Sample Code

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:Ariba:Buyer:vrealm_30"> <soapenv:Header> <urn:Headers> <urn:variant>vrealm_30</urn:variant> <urn:partition>prealm_30</urn:partition> </urn:Headers> </soapenv:Header> <soapenv:Body> <urn:WSExternalContractPullRequest partition="prealm_30" variant="vrealm_30"> <urn:ExternalContractData_ExternalContractPull_Item> <urn:item> <urn:CCHierarchy></urn:CCHierarchy> <urn:Contract>C20388</urn:Contract> <urn:ContractLine>1</urn:ContractLine> <urn:ExternalContractURL>http://www.extcontractsystem.com</urn:ExternalContractURL> <urn:MAState>8</urn:MAState> <urn:SupplierId>sid509</urn:SupplierId> <urn:SupplierPartAuxiliaryId></urn:SupplierPartAuxiliaryId> <urn:SupplierPartId></urn:SupplierPartId> <urn:TermType>1</urn:TermType> </urn:item> </urn:ExternalContractData_ExternalContractPull_Item> </urn:WSExternalContractPullRequest> </soapenv:Body> </soapenv:Envelope>

Sample SOAP Response Message

A sample SOAP response message from SAP Ariba Catalog is as follows:

Sample Code

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soap:Header> <Headers xmlns="urn:Ariba:Buyer:vrealm_30"> <variant>vrealm_30</variant> <partition>prealm_30</partition> </Headers> </soap:Header> <soap:Body> <WSExternalContractPullReply variant="vrealm_30" partition="prealm_30" xmlns="urn:Ariba:Buyer:vrealm_30"> <ExternalContractData_ExternalContractResponse_Item> <item> <Contract>C20388</Contract>



</item> </ExternalContractData_ExternalContractResponse_Item> </WSExternalContractPullReply> </soap:Body> </soap:Envelope>

Supporting catalog search using web services

SAP Ariba Catalog supports web services requests for catalog search from external systems. The supported search options include free text, product key, and specific attributes, among others.

SAP Ariba web services use the W3C SOAP messaging framework to exchange messages over HTTP or HTTPS. SAP Ariba strongly recommends that you use SAP Ariba web services over an HTTPS link to the EAI system as SAP Ariba web services provide integration tasks, or integration events, that send and receive SOAP messages. An integration task requires an end point for the logical communication channel used by web services. An end point consists of the URL and authentication information that controls access to the end point.

For information on SAP Ariba Web Services and how to configure an end point, see the Administration and data maintenance fundamentals.

NoteYou must ensure your site is configured for web services and the Inbound end point. Inbound end points are used when the task is initiated by the Enterprise Application Integration (EAI) system.

Web services catalog search implementation overview [page 43]

Troubleshooting [page 53]

Web services catalog search implementation overview

Search implementation involves configuring web service, understanding catalog item search web services, common SOAP headers, and WSCatalogSearchRequest and WSCatalogSearchResponse elements.

Configuring web services [page 44]

Understanding catalog item search web service [page 44]

Common header elements in catalog item search [page 45]

WSCatalogSearchRequest elements [page 45]

WSCatalogItemSearchReply elements [page 47]

Site configuration option to prevent issues with numeric formatting in web services catalog search [page 52]


Configuring web services

Consider the following guidelines before implementing catalog item validation requests from external systems using web services:

● Blank search of catalog items are not allowed. At least one search term must be provided.● Refining of search results is not supported.● Image files are not transferred while searching for catalog items.● A maximum of 100 search results is returned.● Search using parametric fields is not supported.

Understanding catalog item search web service

Searching for catalog items with web services involves using CatalogItemSearch and its supported search terms.

CatalogItemSearch web service

SAP Ariba Catalog uses the CatalogItemSearch web service to search for catalog items. The following general guidelines apply to the CatalogItemSearch web service:

● The supported operators are like and or.● Operator like is supported for all searchable fields.● Operator or is supported only for the Key field.● In case of operator like, only one value is supported. In case of operator or multiple values are supported.● If multiple search terms are specified; and operation is applied on all the search terms.● Use MatchAll field for free text search. e.g. ‘Monitor OR Keyboard’.

Catalog search terms supported by CatalogSearchItem

CatalogSearchItem supports specific catalog search terms. Search terms are specified by attribute name, type, and data type.

The following search terms are supported in the CatalogSearchItem web service and are defined using the following properties:

● Attribute Name- Name of an attribute● Attribute Type- Type of an attribute● Data Type - Determines the value of an attribute



Attribute Name Attribute Type Data Type

SupplierID DomainValuePair

CatalogName Id literal

SupplierPartId PartId string

TerritoryAvailable TerritoryCode literal

PunchoutEnabled Flag boolean

AribaInternalMAId Id literal

IsPartial Flag boolean

ClassificationCode DomainValuePair

TypeName Id literal

PunchoutStore Id literal

Language Id literal

Price Money

ManufacturerName Name

ManufacturerPartId PartId string

Keywords Id List of literal

The CatalogItemSearch web service receives CatalogSearchQueryRequest messages and sends CatalogSearchQueryResponse messages.

Common header elements in catalog item search

All SOAP headers for web service events share common elements.

The following table lists the elements common to all SOAP headers for web services.

Element Required Description

variant Mandatory String. Specify a value for this element

partition Mandatory String. Specify a value for this element

WSCatalogSearchRequest elements

A search for catalog items involves a catalog search request using the WSCatalogSearchRequest element.

The WSCatalogSearchRequest element consists of the following sub-elements

WSCatalogItemSearchRequest WSCatalogSearchQueryRequest_Item SAP Ariba Catalog integration guideConfiguring SAP Ariba Catalog features PUBLIC 45

WSCatalogSearchQueryRequest

WSCatalogSearchQueryRequest consists of the following sub-elements.


SearchTerms Mandatory Consists of one or more WSCatalogSearchTerm elements (at least one search term is mandatory). Child elements WSCatalogSearchTerm are:

● Field - Key ● Operators - Like,

or● Values

Sort Optional You can sort the catalog item search results with the following options:

● For sort, validation is applied if the value is provided. The supported fields are Relevance, Price, Description, and Short Name.○ Relevance - sorts

the items with the best or most complete string match and is set as the default value.

○ Price - Ascending sorts the items by price in ascending order.

○ Price - Descending sorts the items by price in descending order.

○ Best Selling sorts items by popularity.

○ Name - Ascending sorts the items by name in ascending order.

○ Name - Descending sorts the items by name in descending order.




SortDirection Optional ● For sort direction, validation is applied if the value is provided. The supported values are asc and desc.

UserID Mandatory This element searches for user information. The user search is based on the user’s unique name and the locale of the search results is based on the user’s locale.

WSCatalogItemSearchReply elements

When a web service returns the results of a search request, it does so with a WSCatalogSearchReply element.

WSCatalogItemSearchReply consists of the following sub-elements:

WSCatalogSearchResponse WSCatalogSearchResponse_Item CatalogItems WSCatalogItem

Each WSCatalogItem element contains sub-elements with attributes such as BuyerPartId, Price, and SupplierId.

Domain-Value pair elements

Some attributes, such as SupplierId and UnitOfMeasure, contain WSDomainValuePair elements.

For example,

<UnitOfMeasure> <Domain>ANSI</Domain> <Value>EA</Value> </UnitOfMeasure>

Money

The Money element has two child elements: Amount, and Currency.

● Amount (optional decimal): Decimal amount.● Currency (optional complex type): Contains UniqueName (optional string). Specifies the currency type using

the ISO 4217 alphabetic code (for example, USD, EUR, or CNY).


For example,

<NonContractPrice> <Currency>USD</Currency> <Amount>408</Amount> </NonContractPrice>

Custom attributes

Custom attributes are returned in ExtrinsicAttributes elements, which contain a FieldName element and one or more Values elements.

For example:

<ExtrinsicAttributes> <item> <Values>Acceptable</Values> <FieldName>Condition</FieldName> </item> </ExtrinsicAttributes>

Errors

The Errors element consists of a list of items and its severity is (error or confirmation) returned by the web service in the response.

For example,

<Errors> <item>Provide valid search field and value - MatchAll:[] </item> </Errors>

For more information on resolving errors, see Troubleshooting [page 53].

Sample specific catalog item search request

You can search for a specific catalog item in SAP Ariba Catalog using web services with the product ID. A product ID is a unique identifier of an item in SAP Ariba Catalog and search by product ID consists of BuyerSystemID, SupplierPartID, and SupplierPartAuxID.

Search for single or multiple product IDs in a requisition at the same time is allowed.

The following example is a search for a specific item in SAP Ariba Catalog using web services with the product ID. This is a request to search for a specific product sid498|RAY41400 for the user adavis. The value of the searchable field name is <urn:Field>Key</urn:Field> with <urn:Operator>like</urn:Operator>.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"tha xmlns:urn="urn:Ariba:Buyer:vrealm_1">



<soapenv:Header> <urn:Headers> <urn:variant>vrealm_1</urn:variant> <urn:partition>prealm_1</urn:partition> </urn:Headers> </soapenv:Header> <soapenv:Body> <urn:WSCatalogItemSearchRequest partition="prealm_1" variant="vrealm_1"> <urn:WSCatalogSearchQueryRequest_Item> <urn:item> <urn:SearchTerms> <urn:item> <urn:Field>Key</urn:Field> <urn:Operator>like</urn:Operator> <urn:Values> <urn:item>sid498|RAY41400</urn:item> </urn:Values> </urn:item> </urn:SearchTerms> <urn:Sort></urn:Sort> <urn:SortDirection></urn:SortDirection> <urn:UserId>adavis</urn:UserId> </urn:item> </urn:WSCatalogSearchQueryRequest_Item> </urn:WSCatalogItemSearchRequest> </soapenv:Body> </soapenv:Envelope>

Sample catalog item search response

A web service search returns results in a WSCatalogItemSearchReply element.

The following is a response returned for the specific catalog item search request for sid498|RAY41400 on variant vrealm_1 and partition prealm_1.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soap:Header> <Headers xmlns="urn:Ariba:Buyer:vrealm_84"> <variant>vrealm_84</variant> <partition>prealm_84</partition> </Headers> </soap:Header> <soap:Body> <WSCatalogItemSearchReply xmlns="urn:Ariba:Buyer:vrealm_84"> <WSCatalogSearchResponse_Item> <item> <Errors/> <CatalogItems> <item> <SupplierPartAuxiliaryId/> <ManufacturerPartId>303/357-1W</ManufacturerPartId> <Key>sid498|RAY41400</Key> <PunchoutEnabled>false</PunchoutEnabled> <CatalogName>SchaferOffice</CatalogName> <EffectiveDate/> <Thumbnail/> <InKitOnly>false</InKitOnly> <ExpirationDate/> <ManufacturerName/> <ErrorSeverity/>


<AribaInternalMAId/> <PriceBasisQuantityUOM> <Domain/> <Value/> </PriceBasisQuantityUOM> <LinkedBuyerFacility/> <ReportingPath/> <BuyerPartId/> <ManufacturerURL/> <ContractPrice> <Currency>USD</Currency> <Amount>1.56</Amount> </ContractPrice> <AribaInternalIsContractOrderable>false</AribaInternalIsContractOrderable> <LeadTime>1</LeadTime> <SpecSheet/> <Price> <Currency>USD</Currency> <Amount>1.56</Amount> </Price> <ShortName/> <SupplierId> <item> <Domain>buyersystemid</Domain> <Value>sid498</Value> </item> </SupplierId> <OriginatingLineNumber>0</OriginatingLineNumber> <HazmatSheet/> <Filtered>false</Filtered> <ApplicableContracts/> <ClassificationCode> <item> <Domain>UNSPSC</Domain> <Value>26111711</Value> </item> </ClassificationCode> <PriceBasisQuantityDesc/> <OriginatingColumnNumber>0</OriginatingColumnNumber> <InternalPartId>false</InternalPartId> <ExtrinsicAttributes> <item> <Values> <item/> </Values> <FieldName>bestprice</FieldName> </item> <item> <Values> <item/> </Values> <FieldName>hazardousmaterials</FieldName> </item> <item> <Values> <item/> </Values> <FieldName>green</FieldName> </item> </ExtrinsicAttributes> <NonContractPrice> <Currency>USD</Currency> <Amount>1.56</Amount> </NonContractPrice> <PriceBasisQuantity/> <SubscriptionVersionId/> <Availability/>



<PunchoutLevel/> <UnitOfMeasure> <Domain>UN</Domain> <Value>EA</Value> </UnitOfMeasure> <Image/> <PreviewFilterName/> <SupplierPartId>RAY41400</SupplierPartId> <URL/> <PunchoutStore/> <PreviewFiltered>false</PreviewFiltered> <TerritoryAvailable/> <ConversionFactor/> <CatalogTypeName>system:catalogitem</CatalogTypeName> <Partial>false</Partial> <Description>Watch/Calculator Batteries - 1.5 Silver</Description> <Demo/> <LinkedBuyerPart/> <ProcureItemType/> <PropertiesMask/> <ItemNumber>0</ItemNumber> <Language>en_US</Language> <SupplierName>Schafer Office</SupplierName> </item> </CatalogItems> </item> </WSCatalogSearchResponse_Item> </WSCatalogItemSearchReply> </soap:Body> </soap:Envelope>

Sample multiple item search request

You can search for multiple catalog items in SAP Ariba Catalog using web services with the product ID. A product ID is a unique identifier of an item in SAP Ariba Catalog and search by product ID consists of BuyerSystemID, SupplierPartID, and SupplierPartAuxID.

Search for single or multiple product IDs in a requisition at the same time is allowed.

The following is an example of searching for multiple catalog items in SAP Ariba Catalog using web services with the product IDs. A request to search for multiple products is as follows:

<urn:SearchTerms> <urn:item> <urn:Field>Key</urn:Field> <urn:Operator>or</urn:Operator> <urn:Values> <urn:item>sid498|RAY41400</urn:item> <urn:item>sid498|RAY45052</urn:item> </urn:Values> </urn:item> </urn:SearchTerms>

Where

Products are sid498|RAY41400, sid498|RAY45052

Value of the searchable Field name is Key

Supported Operator is or


Sample Free Text Search Request

You can perform free text search for catalog items. For example, you can search for a catalog item “monitors and keyboards” and monitor and keyboards across multiple catalogs, within a single catalog, or within categories across multiple catalogs are retrieved.

The following is an example of free text searching in SAP Ariba Catalog using web services using the MatchAll field with the like operator as like is supported for all searchable fields.

<urn:SearchTerms> <urn:item> <urn:Field>MatchAll</urn:Field> <urn:Operator>like</urn:Operator> <urn:Values> <urn:item>Monitor or Keyboard</urn:item> </urn:Values> </urn:item> </urn:SearchTerms>

Attribute search request

You can search on item attributes. An attribute search is a search that requires you to specify the set of attributes to perform the search.

The following is an example of searching catalog items for <SupplierPartAuxiliaryId/> and <SupplierId> attributes.

<urn:item>  <urn:SearchTerms>  <urn:item>  <urn:Field>MatchAll</urn:Field> <urn:Operator>like</urn:Operator> <urn:Values>  <urn:item>JohnDoef1513</urn:item> </urn:Values> </urn:item> </urn:SearchTerms> <urn:Sort></urn:Sort> <urn:SortDirection></urn:SortDirection> <urn:UserId>jham</urn:UserId> </urn:item>

Site configuration option to prevent issues with numeric formatting in web services catalog search

By default, web services catalog search passes BigDecimal values through a formatter, which can cause issues with middleware. SAP Ariba can set a site configuration option to prevent this.Application.Messaging.Channels.WS.UseBigDecimalFormatter (set by SAP Ariba Support)

This parameter determines whether BigDecimal values sent through remote procedure call (RPC) based web services are passed through a formatter called BigDecimalFormatter. The formatter adjusts the formatting and rounding of the values. For example, it adds thousands separators. With RPC-based web services, some of the adjustments the formatter makes cause issues for middleware.

Troubleshooting

When you encounter searching errors, they are usually a result of a request error.

The following table lists the commonly-encountered errors related to searching catalog items using web services:

Error Resolution

Invalid user ID Provide a valid user ID

Invalid search term Provide a valid search term

Product ID validation failed due to an unexpected error Provide a valid product ID

Search term not supported Provide a search term that is supported.

Invalid search field and value Provide a valid search value

Invalid search operator Provide a correct search operator

Search request has reached the maximum limit The search request has reached the maximum of 10000 search results. You can narrow down the search operations and try again.

Search field already exists. Duplicate search fields are not allowed. Provide a unique search field

Specified sort by field is incorrect Provide the correct sort by field option

Invalid sort direction Provide a correct sort direction


Revision history

The following table provides a brief history of the updates to this guide. SAP Ariba updates the technical documentation for its cloud solutions if:

● software changes delivered in service packs or hot fixes require a documentation update to correctly reflect the new or changed functionality

● the existing content is incorrect or user feedback indicated that important content is missing

SAP Ariba reserves the right to update its technical documentation without prior notification. Most documentation updates will be made available in the same week as the software service packs are released, but critical documentation updates may be released at any time.

Month/year of update

Updated chapter/section Short description of change

November 2018 n/a Updated topic naming convention

August 2018 Extracting catalog data in JSON format

Added information about the EXTRACTIMAGE parameter.

Flow of Data Between SAP Ariba Catalog and SAP SRM

Added the following fields to the table:

● User.Address.UName● User.Address.PCode● User.Address.Org

May 2018 Parameters to Configure Requests for Catalog Data Extraction

Updated integration URL.

July 2017 Flow of Data Between SAP Ariba Catalog and SAP SRM

Updated the description of the HOOK_URL field with information about the Application.Content.OCI.CustomOutboundParameters site configuration option.

June 2017 All Updated SAP Ariba solution names.

May 2019 Flow of Data Between SAP Ariba Catalog and SAP SRM

Updated the description of the NEW_ITEM-SERVICE field.

Extracting catalog data in JSON format

Added the CATALOGPREFIX parameter to the Parameters to Configure Requests for Catalog Data Extraction table.

August 2019 Extracting catalog data in JSON format

Added information about basic access authentication.

November 2019 Flow of Data Between SAP Ariba Catalog and SAP SRM

Added a note that the field names are case-sensitive.


Revision history

Important Disclaimers and Legal Information

HyperlinksSome links are classified by an icon and/or a mouseover text. These links provide additional information.About the icons:

● Links with the icon : You are entering a Web site that is not hosted by SAP. By using such links, you agree (unless expressly stated otherwise in your agreements with SAP) to this:

● The content of the linked-to site is not SAP documentation. You may not infer any product claims against SAP based on this information.● SAP does not agree or disagree with the content on the linked-to site, nor does SAP warrant the availability and correctness. SAP shall not be liable for any

damages caused by the use of such content unless damages have been caused by SAP's gross negligence or willful misconduct.

● Links with the icon : You are leaving the documentation for that particular SAP product or service and are entering a SAP-hosted Web site. By using such links, you agree that (unless expressly stated otherwise in your agreements with SAP) you may not infer any product claims against SAP based on this information.

Videos Hosted on External PlatformsSome videos may point to third-party video hosting platforms. SAP cannot guarantee the future availability of videos stored on these platforms. Furthermore, any advertisements or other content hosted on these platforms (for example, suggested videos or by navigating to other videos hosted on the same site), are not within the control or responsibility of SAP.

Beta and Other Experimental FeaturesExperimental features are not part of the officially delivered scope that SAP guarantees for future releases. This means that experimental features may be changed by SAP at any time for any reason without notice. Experimental features are not for productive use. You may not demonstrate, test, examine, evaluate or otherwise use the experimental features in a live operating environment or with data that has not been sufficiently backed up.The purpose of experimental features is to get feedback early on, allowing customers and partners to influence the future product accordingly. By providing your feedback (e.g. in the SAP Community), you accept that intellectual property rights of the contributions or derivative works shall remain the exclusive property of SAP.

Example CodeAny software coding and/or code snippets are examples. They are not for productive use. The example code is only intended to better explain and visualize the syntax and phrasing rules. SAP does not warrant the correctness and completeness of the example code. SAP shall not be liable for errors or damages caused by the use of example code unless damages have been caused by SAP's gross negligence or willful misconduct.

Bias-Free LanguageSAP supports a culture of diversity and inclusion. Whenever possible, we use unbiased language in our documentation to refer to people of all cultures, ethnicities, genders, and abilities.

SAP Ariba Catalog integration guideImportant Disclaimers and Legal Information PUBLIC 55

www.ariba.com

© 2022 SAP SE or an SAP affiliate company. All rights reserved.

No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company. The information contained herein may be changed without prior notice.

Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary.

These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP or SAP affiliate company products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.

SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE (or an SAP affiliate company) in Germany and other countries. All other product and service names mentioned are the trademarks of their respective companies.

Please see https://www.sap.com/about/legal/trademark.html for additional trademark information and notices.

THE BEST RUN

http://www.ariba.com

https://www.sap.com/about/legal/trademark.html

SAP Ariba Catalog integration guide

Documents

Transcript of SAP Ariba Catalog integration guide