SAP Ariba Catalog integration guide
Transcript of 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
4 PUBLICSAP Ariba Catalog integration guide
SAP Ariba Catalog integration guide
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.
6 PUBLICSAP Ariba Catalog integration guide
Integrating with Oracle iProcurement
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.
8 PUBLICSAP Ariba Catalog integration guide
Integrating with Oracle iProcurement
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
SAP Ariba Catalog integration guideIntegrating with Oracle iProcurement PUBLIC 9
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.
10 PUBLICSAP Ariba Catalog integration guide
Integrating with Oracle iProcurement
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.
SAP Ariba Catalog integration guideIntegrating with Oracle iProcurement PUBLIC 11
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
12 PUBLICSAP Ariba Catalog integration guide
Integrating with Oracle iProcurement
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.
SAP Ariba Catalog integration guideIntegrating with Oracle iProcurement PUBLIC 13
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.
14 PUBLICSAP Ariba Catalog integration guide
Integrating with SAP SRM
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
Field NameMandatory Description
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.
16 PUBLICSAP Ariba Catalog integration guide
Integrating with SAP SRM
Field NameMandatory Description
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.
SAP Ariba Catalog integration guideIntegrating with SAP SRM PUBLIC 17
Field NameMandatory Description
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
18 PUBLICSAP Ariba Catalog integration guide
Integrating with SAP SRM
Field Name Description Example
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.
NEW_ITEM-CUST_FIELD2[#] Userdefined custom field. The maximum length is 10 characters.
NEW_ITEM-CUST_FIELD3[#] Userdefined custom field. The maximum length is 10 characters.
NEW_ITEM-CUST_FIELD4[#] Userdefined custom field. The maximum length is 20 characters.
NEW_ITEM-CUST_FIELD5[#] Userdefined custom field. The maximum length is 50 characters.
If you are using the SAP Ariba Spot Buy Catalog solution, the following additional fields are included to identify spot buy purchases:
Field Name Description Example
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
SAP Ariba Catalog integration guideIntegrating with SAP SRM PUBLIC 19
Field Name Description Example
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].
20 PUBLICSAP Ariba Catalog integration guide
Integrating with SAP SRM
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
SAP Ariba Catalog integration guideIntegrating with SAP SRM PUBLIC 21
Parameter Description Value
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:
Parameter Description Value
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
22 PUBLICSAP Ariba Catalog integration guide
Integrating with SAP SRM
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:
Parameter Description Value
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>
SAP Ariba Catalog integration guideIntegrating with SAP SRM PUBLIC 23
<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')
24 PUBLICSAP Ariba Catalog integration guide
Integrating with SAP SRM
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.
SAP Ariba Catalog integration guideIntegrating with SAP SRM PUBLIC 25
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.
26 PUBLICSAP Ariba Catalog integration guide
Integrating with SAP SRM
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
SAP Ariba Catalog integration guideIntegrating with SAP SRM PUBLIC 27
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
28 PUBLICSAP Ariba Catalog integration guide
Integrating with SAP SRM
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
NEW_ITEM-CUST_FIELD2[n] Userdefined field
NEW_ITEM-CUST_FIELD3[n] Userdefined field
NEW_ITEM-CUST_FIELD4[n] Userdefined field
NEW_ITEM-CUST_FIELD5[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.
SAP Ariba Catalog integration guideIntegrating with SAP SRM PUBLIC 29
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.
30 PUBLICSAP Ariba Catalog integration guide
Integrating with SAP SRM
Parameter Name Mandatory Value Description
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.
SAP Ariba Catalog integration guideIntegrating with SAP SRM PUBLIC 31
Parameter Name Mandatory Value Description
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.
32 PUBLICSAP Ariba Catalog integration guide
Integrating with SAP SRM
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
SAP Ariba Catalog integration guideIntegrating with SAP SRM PUBLIC 33
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.
34 PUBLICSAP Ariba Catalog integration guide
Integrating with SAP SRM
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");
SAP Ariba Catalog integration guideIntegrating with SAP SRM PUBLIC 35
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
36 PUBLICSAP Ariba Catalog integration guide
Integrating with SAP SRM
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
38 PUBLICSAP Ariba Catalog integration guide
Configuring SAP Ariba Catalog features
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.
SAP Ariba Catalog integration guideConfiguring SAP Ariba Catalog features PUBLIC 39
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.
40 PUBLICSAP Ariba Catalog integration guide
Configuring SAP Ariba Catalog features
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.
SAP Ariba Catalog integration guideConfiguring SAP Ariba Catalog features PUBLIC 41
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>
42 PUBLICSAP Ariba Catalog integration guide
Configuring SAP Ariba Catalog features
</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]
SAP Ariba Catalog integration guideConfiguring SAP Ariba Catalog features PUBLIC 43
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
44 PUBLICSAP Ariba Catalog integration guide
Configuring SAP Ariba Catalog features
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.
Element Required Description
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.
46 PUBLICSAP Ariba Catalog integration guide
Configuring SAP Ariba Catalog features
Element Required Description
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).
SAP Ariba Catalog integration guideConfiguring SAP Ariba Catalog features PUBLIC 47
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">
48 PUBLICSAP Ariba Catalog integration guide
Configuring SAP Ariba Catalog features
<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/>
SAP Ariba Catalog integration guideConfiguring SAP Ariba Catalog features PUBLIC 49
<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/>
50 PUBLICSAP Ariba Catalog integration guide
Configuring SAP Ariba Catalog features
<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
SAP Ariba Catalog integration guideConfiguring SAP Ariba Catalog features PUBLIC 51
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> <!--You may enter the following 4 items in any order--> <urn:SearchTerms> <!--1 or more repetitions:--> <urn:item> <!--You may enter the following 3 items in any order--> <urn:Field>MatchAll</urn:Field> <urn:Operator>like</urn:Operator> <urn:Values> <!--1 or more repetitions:--> <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)
52 PUBLICSAP Ariba Catalog integration guide
Configuring SAP Ariba Catalog features
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
SAP Ariba Catalog integration guideConfiguring SAP Ariba Catalog features PUBLIC 53
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.
54 PUBLICSAP Ariba Catalog integration guide
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