ariba buyer 8.2 data load guide - connect.ariba.com · copyright © 1996-2004 ariba, inc. ariba and...

Ariba BuyerData Load GuideVersion 8.2 May 2004

Copyright © 1996-2004 Ariba, Inc.Ariba and the Ariba logo are registered trademarks of Ariba, Inc. Ariba Spend Management, Ariba Analysis, Ariba Buyer, Ariba Category Management, Ariba Contracts, Ariba Travel & Expense, Ariba Workforce, Ariba Invoice, Ariba eForms, Ariba Enterprise Sourcing, Ariba Category Procurement, Ariba Contract Workbench, Ariba Settlement, Ariba Supplier Network, BPM Services, Power Sourcing, Total Spend Capture and PO-Flip are trademarks or service marks of Ariba, Inc. All other trademarks are property of their respective owners.

CONTAINS IBM Runtime Environment for AIX (R), Java (TM) 2 Technology Edition Runtime Modules(c) Copyright IBM Corporation 1999, 2000All Rights Reserved

Some versions of this product include software licensed from International Business Machines Corp. Such software is protected by copyright as provided in the proprietary notices included with the software.

Some versions of this product include software licensed from BEA Systems, Inc. Such software is protected by copyright as provided in the proprietary notices included with the software.

All other brand or product names may be trademarks or registered trademarks of their respective companies or organizations.

ALL LICENSES OF ARIBA SOFTWARE PROGRAMS AND RELATED DOCUMENTATION (“PROGRAMS”) ARE SUBJECT TO ANY EXPORT LAWS, REGULATIONS ORDERS OR OTHER RESTRICTIONS IMPOSED BY THE UNITED STATES OF AMERICA OR BY ANY OTHER GOVERNMENT ENTITY ON THE PROGRAMS OR INFORMATION RELATING THERETO. A LICENSEE OF ANY PROGRAM WILL NOT IMPORT, EXPORT, OR ALLOW THE EXPORT OR REEXPORT, DIRECTLY OR INDIRECTLY, OF THE PROGRAM (OR TECHNICAL DATA OR OTHER INFORMATION RELATED THERETO) OR ANY DIRECT PRODUCT THEREOF, TO ANY COUNTRY TO WHICH SUCH IMPORT, EXPORT, OR REEXPORT IS RESTRICTED OR PROHIBITED, OR AS TO WHICH SUCH GOVERNMENT OR ANY AGENCY THEREOF REQUIRES ANY EXPORT LICENSE OR OTHER GOVERNMENTAL APPROVAL AT THE TIME OF IMPORT, EXPORT OR REEXPORT, WITHOUT FIRST OBTAINING SUCH APPROVAL.

THIRD PARTY SOFTWARESee this URL for a complete list of third-party software copyright information: http://www.ariba.com/copyrights.cfm

http://www.ariba.com/copyrights.cfm

Ariba Buyer Data Load Guide iii

Table of Contents

Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiAudience and Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiTypographic Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiAriba Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

How to Use This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Chapter 2 Data Sources for Integration Events . . . . . . . . . . . . . . 17

Introduction to Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Types of Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Integrations from CSV Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

CSV File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Single CSV File as the Data Source . . . . . . . . . . . . . . . . . . . . . . 20Multiple CSV Files as the Data Source . . . . . . . . . . . . . . . . . . . . 20Additional Data Files in the Data Source . . . . . . . . . . . . . . . . . . 21Multilingual Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Mapped Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Data Files for Mapped Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Mapping File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Integration Event for the Canonical List . . . . . . . . . . . . . . . . . . . 27Integration Event for the Mapping . . . . . . . . . . . . . . . . . . . . . . . 27SimpleMapTypePull Integration Event . . . . . . . . . . . . . . . . . . . . 28

Sources of Field Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29sourceOfTruth Field Property . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Supplemental Source of Truth Control . . . . . . . . . . . . . . . . . . . . 30

Load Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33LoadDB.txt File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33LoadDBLanguage.txt File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

iv Ariba Buyer Data Load Guide 82en_us2004.5.95

Table of Contents

Chapter 3 Integration Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Introduction to Integration Events . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Integration Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Integration Event Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Understanding Message Definition Files. . . . . . . . . . . . . . . . . . . 39Understanding Message Configuration Files. . . . . . . . . . . . . . . . 41Location of Configuration Files. . . . . . . . . . . . . . . . . . . . . . . . . . 45Working with Integration Event Files . . . . . . . . . . . . . . . . . . . . . 45Reinitializing Integration Events . . . . . . . . . . . . . . . . . . . . . . . . . 46

Integration Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Schema Specification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Default Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Accessibility and Scope of Field Values. . . . . . . . . . . . . . . . . . . . . . . 50

Chapter 4 Ariba File Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Introduction to the Ariba File Channel . . . . . . . . . . . . . . . . . . . . . . . . 53Finding Configuration Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Parameters.table Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Simple Pull Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55The Message Definition File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56The Message Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . 57The Integration Mappings File . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Language Pull Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Header-Detail Pull Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Loading Header and Detail in Separate Events . . . . . . . . . . . . . . 62Loading Header and Detail Data In a Single Event. . . . . . . . . . . 63

Excel as a Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Localized Header Columns in Spreadsheets . . . . . . . . . . . . . . . . 66Multiple Worksheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Loading Vector Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Logging Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Export Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Message Definition for an Export Event . . . . . . . . . . . . . . . . . . . 70Message Configuration for an Export Event . . . . . . . . . . . . . . . . 70How to Export Manually Maintained Data . . . . . . . . . . . . . . . . . 73Export Events in Ariba Buyer Administrator . . . . . . . . . . . . . . . 73

Ariba Buyer Data Load Guide v

Table of Contents

Customizing Data Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Creating an Integration Mappings Extension File . . . . . . . . . . . . 74Using the integration Field Property . . . . . . . . . . . . . . . . . . . . . . 75Using the metaDataIntegration Field Property . . . . . . . . . . . . . . 79Specifying a Custom Date Formatter . . . . . . . . . . . . . . . . . . . . . 80Adding a New Field to a Group. . . . . . . . . . . . . . . . . . . . . . . . . . 81Removing the Mapping for a Field . . . . . . . . . . . . . . . . . . . . . . . 81

Chapter 5 Ariba cXML Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Introduction to the Ariba cXML Channel. . . . . . . . . . . . . . . . . . . . . . 83Ariba cXML Channel Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Parameters in Application.Messaging . . . . . . . . . . . . . . . . . . . . . 84Parameters in System.Messaging . . . . . . . . . . . . . . . . . . . . . . . . 85

Ariba cXML Channel Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Customizing a cXML Template. . . . . . . . . . . . . . . . . . . . . . . . . . 85Template File Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

AW Components in Template Files . . . . . . . . . . . . . . . . . . . . . . . . . . 89AW Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89AX Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Chapter 6 Ariba HTTP Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Introduction to the Ariba HTTP Channel . . . . . . . . . . . . . . . . . . . . . . 95Ariba HTTP Channel Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Application and System Parameters . . . . . . . . . . . . . . . . . . . . . . 96Message Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . 96

Chapter 7 Languages, Countries, and Locales . . . . . . . . . . . . . . . 97

Introduction to Locales and Resource Files . . . . . . . . . . . . . . . . . . . . 97Locales. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Resource Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Date Strings in Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . 100Integration Events and Parameters for Locales. . . . . . . . . . . . . . . . . 100

LocaleIDPull Integration Event . . . . . . . . . . . . . . . . . . . . . . . . . 100LocaleMapPull Integration Event . . . . . . . . . . . . . . . . . . . . . . . 102Parameters for Default Locales . . . . . . . . . . . . . . . . . . . . . . . . . 103

vi Ariba Buyer Data Load Guide 82en_us2004.5.95

Table of Contents

Integration Events and Parameters for Languages . . . . . . . . . . . . . . 104LanguagePull Integration Event . . . . . . . . . . . . . . . . . . . . . . . . 104LanguageMapPull Integration Event . . . . . . . . . . . . . . . . . . . . . 105Parameters for Default Languages. . . . . . . . . . . . . . . . . . . . . . . 106

Integration Events and Parameters for Countries . . . . . . . . . . . . . . . 107CountryPull Integration Event . . . . . . . . . . . . . . . . . . . . . . . . . . 107CountryMapPull Integration Event . . . . . . . . . . . . . . . . . . . . . . 108

Database Character Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Character Encoding Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Customizing Encoding Mappings . . . . . . . . . . . . . . . . . . . . . . . 110Where to Find Additional Information . . . . . . . . . . . . . . . . . . . . . . . 111

Chapter 8 Non-English Configurations . . . . . . . . . . . . . . . . . . . . 113

Database Character Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Data File Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Parameters in config/Parameters.table . . . . . . . . . . . . . . . . . . . . . . . 115Considerations for Asian Language Configurations. . . . . . . . . . . . . 117

Requirements for Asian Language Support. . . . . . . . . . . . . . . . 117Where to Find Additional Information . . . . . . . . . . . . . . . . . . . . . . . 119

Chapter 9 Currencies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Introduction to Currencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Defining Currency Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Choosing a Currency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Currency Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Conversion Rates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Euro Restrictions and Conversion Rates . . . . . . . . . . . . . . . . . . 125UpdateMoneyFields Trigger Action . . . . . . . . . . . . . . . . . . . . . 126ARFHintTotalCost Field Controller . . . . . . . . . . . . . . . . . . . . . 127Historical Currency Conversion . . . . . . . . . . . . . . . . . . . . . . . . 128

Currency Considerations for ERP Systems . . . . . . . . . . . . . . . . . . . 129Oracle Currency Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129PeopleSoft Currency Support . . . . . . . . . . . . . . . . . . . . . . . . . . 130SAP Currency Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Ariba Buyer Data Load Guide vii

Table of Contents

Integration Events for Currency Information . . . . . . . . . . . . . . . . . . 131CurrencyPull Integration Event . . . . . . . . . . . . . . . . . . . . . . . . . 131CurrencyMapPull Integration Event . . . . . . . . . . . . . . . . . . . . . 133CurrencyConversionRatePull Integration Event . . . . . . . . . . . . 135CurrencyGroupPull Integration Event . . . . . . . . . . . . . . . . . . . . 139

Choosing a Currency. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Chapter 10 Product Classification Codes . . . . . . . . . . . . . . . . . . . 141

Introduction to Classification Codes. . . . . . . . . . . . . . . . . . . . . . . . . 141Classification Code Standards . . . . . . . . . . . . . . . . . . . . . . . . . . 141Classification Code Hierarchies . . . . . . . . . . . . . . . . . . . . . . . . 142

Commodity Codes in Ariba Buyer . . . . . . . . . . . . . . . . . . . . . . . . . . 143Commodity Codes in the Object Model . . . . . . . . . . . . . . . . . . 143Commodity Code Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Commodity Code Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Integration Events for Commodity Codes . . . . . . . . . . . . . . . . . . . . 146CommodityCodePull Integration Event . . . . . . . . . . . . . . . . . . 147CommodityCodeParent Pull Integration Event . . . . . . . . . . . . . 149PartitionedCommodityCodePull Integration Event . . . . . . . . . . 150ClassificationCodeDomainMetaPull Integration Event. . . . . . . 150ClassificationCodeMapPull Integration Event . . . . . . . . . . . . . 152CommodityExportMapPull Integration Event. . . . . . . . . . . . . . 153Detecting Mapping Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Export Events and Language Pull Events . . . . . . . . . . . . . . . . . 157

Commodity Codes for PunchOut Items . . . . . . . . . . . . . . . . . . . . . . 157

Chapter 11 Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Introduction to Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Creating Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Using Organizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Maintaining User Profile Data. . . . . . . . . . . . . . . . . . . . . . . . . . 160Using Ariba Buyer Administrator . . . . . . . . . . . . . . . . . . . . . . . 161Adding New Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

viii Ariba Buyer Data Load Guide 82en_us2004.5.95

Table of Contents

Integration Events For User Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 161OrganizationPull Integration Event . . . . . . . . . . . . . . . . . . . . . . 162OrganizationExport Integration Event. . . . . . . . . . . . . . . . . . . . 162SharedUserPull Integration Event . . . . . . . . . . . . . . . . . . . . . . . 163SharedUserSupervisorPull Integration Event . . . . . . . . . . . . . . 165UserPull Integration Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165SharedUserShipToAddressMap Integration Event . . . . . . . . . . 167

How to Maintain User Profile Information. . . . . . . . . . . . . . . . . . . . 167sourceOfTruth Field Property . . . . . . . . . . . . . . . . . . . . . . . . . . 168User Profile Changes on Initial Login . . . . . . . . . . . . . . . . . . . . 168

User Profile Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Organic User Growth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Chapter 12 Permissions, Roles, and Groups . . . . . . . . . . . . . . . . . 171

Introduction to Permissions, Roles, and Groups. . . . . . . . . . . . . . . . 171Integration Events to Define Data . . . . . . . . . . . . . . . . . . . . . . . 172Configuration Design: Inheriting Permissions . . . . . . . . . . . . . 173

Integration Events for Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . 175PermissionPull Integration Event . . . . . . . . . . . . . . . . . . . . . . . 175PermissionExport Integration Event . . . . . . . . . . . . . . . . . . . . . 176EditPermissionPull Integration Event . . . . . . . . . . . . . . . . . . . . 176ExecutePermissionPull Integration Event . . . . . . . . . . . . . . . . . 177

Integration Events for Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177RolePull Integration Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177RoleChildRoleMapPull Integration Event. . . . . . . . . . . . . . . . . 178RoleExport Integration Event . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Integration Events for Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179GroupPull Integration Event . . . . . . . . . . . . . . . . . . . . . . . . . . . 179GroupChildGroupMapPull Integration Event . . . . . . . . . . . . . . 180GroupExport Integration Event . . . . . . . . . . . . . . . . . . . . . . . . . 180

Integration Events for Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Mapping Events for Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Mapping Events for Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Mapping Events for Shared Users . . . . . . . . . . . . . . . . . . . . . . . 184

Load Order for Integration Events . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Chapter 13 Units of Measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Introduction to Units of Measure . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Ariba Buyer Data Load Guide ix

Table of Contents

Units of Measure in Catalog Files . . . . . . . . . . . . . . . . . . . . . . . . . . 188Canonical Units of Measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

UnitOfMeasure Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190UnitOfMeasureLanguagePull Integration Event . . . . . . . . . . . . 190

Unit of Measure Mappings in Partitions. . . . . . . . . . . . . . . . . . . . . . 191UnitOfMeasureMapPull Integration Event . . . . . . . . . . . . . . . . 191UnitOfMeasureCIFMapPull Integration Event . . . . . . . . . . . . . 192Considerations for Unit of Measure Mappings . . . . . . . . . . . . . 193

ERP-Specific Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194PunchOut Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Parameter for Default Unit of Measure . . . . . . . . . . . . . . . . . . . . . . 194

Chapter 14 Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Introduction to Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195AddressPull Integration Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Address Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197SharedUserShipToAddressMap Integration Event . . . . . . . . . . . . . . 199AddressExport Integration Event . . . . . . . . . . . . . . . . . . . . . . . . . . . 200Billing Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

Chapter 15 Accounting Information . . . . . . . . . . . . . . . . . . . . . . . 201

Introduction to Accounting Information. . . . . . . . . . . . . . . . . . . . . . 201Accounting Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202Default Accounting Information . . . . . . . . . . . . . . . . . . . . . . . . 202Line Item Split Accounting . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203Accounting Combinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

AccountPull Integration Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Accounting Entity Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Accounting Entities in the Default Configuration . . . . . . . . . . . 205

Parameters for Line Item Split Accounting . . . . . . . . . . . . . . . . . . . 207SplitAccountingTypePull Integration Event . . . . . . . . . . . . . . . . . . . 207

SplitAccountingType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 207AccountTypePull Integration Event . . . . . . . . . . . . . . . . . . . . . . . . . 209

AccountType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Account Types for Catalog Items . . . . . . . . . . . . . . . . . . . . . . . 210

Account Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210AccountingCombinationPull Integration Event . . . . . . . . . . . . . . . . 211Metadata XML for Accounting Combinations . . . . . . . . . . . . . . . . . 212

x Ariba Buyer Data Load Guide 82en_us2004.5.95

Table of Contents

Default Accounting Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . 213Defaulting Shipping Address. . . . . . . . . . . . . . . . . . . . . . . . . . . 213Defaulting from the Requester. . . . . . . . . . . . . . . . . . . . . . . . . . 214

Chapter 16 Supplier Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Introduction to Supplier Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217Suppliers and Supplier Locations . . . . . . . . . . . . . . . . . . . . . . . 218Common Suppliers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218IDs for Suppliers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

How Supplier Data Is Created . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221Loading Suppliers through Integration Events . . . . . . . . . . . . . 222Loading Suppliers from Ariba SN. . . . . . . . . . . . . . . . . . . . . . . 229Creating Suppliers During Catalog Load . . . . . . . . . . . . . . . . . 230

Suppliers and Common Suppliers. . . . . . . . . . . . . . . . . . . . . . . . . . . 232Assigning IDs to New Suppliers . . . . . . . . . . . . . . . . . . . . . . . . 232Linking Suppliers and Common Suppliers . . . . . . . . . . . . . . . . 233Using the Supplier Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . 234Creating Common Suppliers in Bulk. . . . . . . . . . . . . . . . . . . . . 236Adjusting Organization IDs During Catalog PunchOut . . . . . . 239

Supplier Location Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239SupplierLocationCheck Scheduled Task . . . . . . . . . . . . . . . . . . 240Validation at Submission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Appendix A Integration File Formats Reference. . . . . . . . . . . 243

Message Definition Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243Message Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

Message Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . 245Channel Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

Integration Mapping Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261The Integration Field Property. . . . . . . . . . . . . . . . . . . . . . . . . . 261

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Ariba Buyer Data Load Guide xi

Preface

The Ariba Buyer Data Load Guide describes how to load data into Ariba Buyer using comma-separated value (CSV) files, cXML data, or Enterprise Resource Planning (ERP) systems as the original source of the data.

Audience and Prerequisites

This document is appropriate for Ariba Solutions Delivery personnel or Ariba certified partners who have successfully installed Ariba Buyer.

This document does not describe all aspects of working with Ariba Buyer. For a complete list of Ariba Buyer documentation available in this release, see the Ariba Buyer Documentation Roadmap (doc_roadmap.htm). You can find the roadmap on Connect (http://connect.ariba.com) along with the other documentation for each release.

s To locate the Ariba Buyer Documentation Roadmap:

1 Log in to Connect.

2 On the left-hand panel, navigate to the Documentation page for the current release (where N.n is the current release) by clicking the following links:

Product Info > Ariba Procurement Solution > Buyer N.n > Documentation.

3 Under Product Documentation, click the link for the view-only documentation set.

4 Click the link for the language you want, such as Ariba Buyer Documentation: English.

5 In the section About the Release, click Ariba Buyer Documentation Roadmap.

On the same page, the Multi-Document Search link describes how to use Adobe's Multi-Document search feature to search all the Ariba Buyer guides simultaneously for specific words or phrases.

http://connect.ariba.com

Preface Typographic Conventions

xii Ariba Buyer Data Load Guide 82en_us2004.5.95

Typographic Conventions

The following table describes the typographic conventions used in this document:

Ariba Technical Support

For assistance with Ariba products, Ariba Technical Support is available by phone, email, or over the Web. For information on how to contact Ariba Technical Support, refer to the following page on the Ariba Technical Support Website:

http://connect.ariba.com/TechSupport_Contacting.htm

Typeface or Symbol

Meaning Example

AaBbCc123 Text you need to change is italicized.

http://server:port/app/inspector

AaBbCc123 The names of user interface controls, menus, and menu items.

Choose Edit from the File menu.

AaBbCc123 Files and directory names, parameters, fields in CSV files, command lines, and code examples.

There is one line in ReportMeta.csv for each report in the system.

AaBbCc123 The names of books. For more information, see the Ariba Buyer Data Load Guide.

http://connect.ariba.com/TechSupport_Contacting.htm

Ariba Buyer Data Load Guide 13

Chapter 1

Introduction

This document describes how to perform the data integration phase of the Ariba Buyer configuration process.

In this document, the descriptions of data integrations use comma-separated value (CSV) data files as examples of data sources, even for integrations that typically pull data from Enterprise Resource Planning (ERP) systems.

This document describes how to load data that is common to all Ariba Buyer features. It does not provide information on loading data for specific features. For information on loading data for specific features, see the following documents:

For this feature See this document

Ariba Procurement Solution Ariba Buyer Procurement Guide

Ariba Settlement Ariba Settlement Guide

Ariba Travel & Expense Ariba Travel & Expense Guide

Ariba Contract Compliance Ariba Contract Compliance Guide

Ariba Invoice Ariba Invoice Guide

Chapter 1 Introduction How to Use This Document

14 Ariba Buyer Data Load Guide 82en_us2004.5.95

How to Use This Document

In addition to this chapter, this document contains the following chapters and appendixes:

• Chapter 3, “Integration Events,” introduces integration events, describes the configuration files you use to define your integration with external systems, and explains how you use those files to configure Ariba Buyer with your own data.

• Chapter 2, “Data Sources for Integration Events,” describes how to define the data sources for your data integrations. It also explains how to set up comma-separated value (CSV) files to act as the data source for integration events.

• Chapter 4, “Ariba File Channel,” presents an overview of the Ariba File Channel architecture. It also describes integration events that use the Ariba File Channel and the files you modify to customize those events.

• Chapter 5, “Ariba cXML Channel,” presents an overview of the Ariba cXML Channel. Ariba Buyer uses the Ariba cXML Channel to exchange data with Ariba Supplier Network (Ariba SN).

• Chapter 6, “Ariba HTTP Channel,” presents an overview of the Ariba HTTP Channel. Ariba Buyer uses the Ariba HTTP Channel to pull common data from, and send updates to, the Common Data Server (CDS).

• Chapter 8, “Non-English Configurations,” summarizes the steps involved in setting up Ariba Buyer for configurations that do not use English as the primary language.

• Chapter 7, “Languages, Countries, and Locales,” describes the integration events and parameters you use to define and support a multilingual configuration. A multilingual configuration is a configuration where either the data or the Ariba Buyer user interface, or both, can be in languages other than English.

• Chapter 9, “Currencies,” describes how to set up the integration events and parameters for currency information.

• Chapter 10, “Product Classification Codes,” describes how to set up and configure commodity codes.

• Chapter 11, “Users,” describes how to define and maintain user lists and user profile data, such as default accounting information, shipping information, and other user preferences.

• Chapter 12, “Permissions, Roles, and Groups,” introduces roles and permissions, and describes how to set up your configuration to authorize appropriate users with administrative privileges.


How to Use This Document Chapter 1 Introduction

• Chapter 13, “Units of Measure,” describes how to set up and configure units of measure (UOM) in Ariba Buyer to accommodate the terminology in use at your company.

• Chapter 14, “Addresses,” describes how to set up a list of shipping and billing addresses. Every Ariba Buyer configuration defines a standard set of addresses, used both for shipping addresses and billing addresses.

• Chapter 15, “Accounting Information,” describes how to define accounting information, associate it with users, and enable the optional features for split line item accounting or account combinations. It also describes the defaulting mechanism for copying accounting information from users onto line items.

• Chapter 16, “Supplier Data,” describes how to configure Ariba Buyer with your set of preferred suppliers and how to extend supplier data with extrinsics.

• Appendix A, “Integration File Formats Reference,” provides complete information on integration event files and their parameters.

Chapter 1 Introduction How to Use This Document



Chapter 2

Data Sources for Integration Events

This chapter describes how to define the data sources for your data integrations. It also explains how to set up comma-separated value (CSV) files to act as the data source for integration events.

This chapter includes the following sections:

• “Introduction to Data Sources” on page 17

• “Types of Data” on page 18

• “Integrations from CSV Files” on page 19

• “Mapped Data” on page 25

• “Sources of Field Values” on page 29

• “Load Order” on page 33

The integration events described in this chapter use the Ariba File Channel, which is the recommended integration channel for reading data from CSV files.

For information on using enterprise integration channels, see the documentation for those channels. For example, for information on the TIBCO channel, see the Ariba Buyer TIBCO Configuration Guide.

Introduction to Data Sources

For each type of data you read into Ariba Buyer, you specify a data source for that data. Depending on the application, and on your chosen configuration, the data source can be a CSV file, or an underlying database system, such as an ERP system or a Human Resource Management System (HRMS). For example, in a typical Ariba Buyer configuration, you pull some data from HRMS and ERP systems, and add additional data by reading from CSV files.

Chapter 2 Data Sources for Integration Events Types of Data


The default configuration supplies a standard implementation of each data load event, typically one that reads from a CSV file. For information that is often read from another data source, such as ERP system or an HRMS system, the default configuration supplies two possible implementations: one that pulls from a database, and one that reads from a CSV file. As you set up your configuration, you choose one or the other, or sometimes a combination of both.

Types of Data

Some integration events store the data in a shared location, and others store it in a partitioned location. The following table describes different types of data in Ariba Buyer:

Type of Data Description

Global Data that is stored in one location and is accessible from all partitions. For example, catalog data is global data. You can set up filters to describe which of those shared items are visible in various partitions, but the catalog items themselves are stored only once in the database and not replicated in each partition

Partitioned Data that is defined in one partition and accessible only within that partition. For example, users, requisitions, accounting information, and lists of shipping addresses are partitioned data.

Mapped Data that is global (shared by all partitions), but can have different names in different partitions. Currencies, countries, languages, locales, and units of measure are examples of mapped data.

For example, each Ariba Buyer configuration defines one standard list of currencies, shared among all partitions, but different partitions might well use different names for those currencies.


Integrations from CSV Files Chapter 2 Data Sources for Integration Events

Integrations from CSV Files

To set up an integration event that reads from a CSV file, you specify one or more files as the data source for the event.

This section describes the format of CSV files used for data, and describes how to set up integration events that pull from those files. The complete syntax for CSV files is described in the Ariba Buyer Configuration Reference Guide.

CSV File Format

A valid CSV file has the following characteristics:

• The first row of the file is a header, listing the columns of the file. The remaining rows are data rows. The following example shows a header row and two rows of data:

"UniqueName","Name","Description""01","US- Global Computers","US- Global Computers""02","US- Global Designs","US- Global Designs"

• Each data row must include every column listed in the header. Every row must have the same number of columns. To omit a field, you must explicitly omit that field by lining up two commas side by side. In the following example, the second field is omitted:

“UniqueName”,”Name”,”Description”“01”,,”US-Global Computers”

• For multilingual use, the first line of a CSV file can optionally indicate the character encoding of the data in that file. In the following example, the CSV file uses ISO-8859-1 (ISO Latin 1) character encoding:

8859_1,,"UniqueName","Name","Description""01","US- Global Computers","US- Global Computers""02","US- Global Designs","US- Global Designs"

The encoding can be any value supported by the Java VM, such as ISO-8859-1, SJIS, EUC_JP, or ISO-2022-JP. For more information on the valid strings for character encodings, see the Ariba Buyer Configuration Reference Guide.

Chapter 2 Data Sources for Integration Events Integrations from CSV Files


Single CSV File as the Data Source

The simplest CSV integration event reads from one CSV file, which is located in the config directory under BuyerServerRoot.

In the default configuration, this type of integration event uses the schema SimpleFileSchema. SimpleFileSchema defines a Filename parameter, which is used to specify the name of the CSV file that contains the data.

The following example shows one data file used as the data source, and the Filename parameter specifies the pathname to that file:

Request = {Parameters = {EventSource = "psap110:Adjustment.csv";Filename = "config/variants/vsap/partitions/psap/data/Adjustment.csv";

Multiple CSV Files as the Data Source

You can define a CSV integration event that reads data from several data files. This approach provides a technique for modifying and extending default data without making modifications directly to the default configuration.

In the default configuration, this type of integration event uses the schema SimpleFileSchema. SimpleFileSchema defines a VectorFileName parameter, which is used to list a vector of file names as the data source. For example:

Request = {Parameters = {EventSource = "poracle11:SplitAccountingType.csv";VectorFilename =

"ariba/variants/voracle11/partitions/poracle11/data/SplitAccountingType.csv;config/variants/voracle11/partitions/poracle11/data/SplitAccountingType.csv";

When an integration event reads data from several files, all the input files must share the same format. For example, if the first data file has the columns UniqueName and Name, the second file must also have the same columns, in the same order.



Additional Data Files in the Data Source

Some integration events must pull header data from one data source, and detail data from one or more additional data sources. For example, the CommonSupplierIDMapPull integration event in the default configuration reads from two CSV files: CommonSupplierIDMapHeader.csv (the header data file) and CommonSupplierIDMap.csv (the detail data file).

In the default configuration, this type of integration event uses the schema HeaderDetailFileSchema. HeaderDetailFileSchema defines a HeaderFileName parameter to specify the file that contains the header data, and a DetailFileName parameter to specify the data file or files that contain the detail data.

In the following example from the CommonSupplierIDMapPull integration event, the DetailFileName parameter specifies the pathname to the CommonSupplierIDMap.csv file and the HeaderFileName parameter specifies the path to the CommonSupplierIDMapHeader.csv file.

Request = {Parameters = {EventSource = "None:CommonSupplierIDMap.csv";HeaderFileName =

"config/variants/Plain/partitions/None/data/CommonSupplierIDMapHeader.csv";Operation = "Create";Details = ( { DetailFileName =

"config/variants/Plain/partitions/None/data/CommonSupplierIDMap.csv";ParentField = "SupplierID.Ids";JoinFields = ( "JoinToken = JoinToken");

})

};

Multilingual Data

To define an integration event that reads multilingual data, you define a data source that reads from one of a variety of possible data sources, depending on locale. To create a CSV integration event that can interpret data in multiple languages, you must do the following:

• Define a simple pull event that reads data from a CSV file. In the default configuration, this type of integration event uses the schema SimpleFileSchema. SimpleFileSchema defines a Filename parameter, which is used to specify a CSV file.



• Define a language pull event that names a set of data files, each containing a translation of the data in a different language. In the default configuration, this type of integration event uses the schema ResourceFileSchema. ResourceFileSchema defines a ResourceFilename parameter, which is used to specify the set of data files.

• Supply implementations of that resource file for each language you plan to support.

• Make sure the two integration events use the same EventSource parameter. The EventSource links together the simple pull and language pull events.

The following example sets up the SplitAccountingTypePull integration event to read from CSV files in multiple languages:

SplitAccountingTypePull = {Channel = {ChannelContextMapFields = { Language = { defaultValue = English;

};};

};LoggingName = SplitAccountingType_CSV;MessageParameters = {Request = {Parameters = {EventSource = "poracle11:SplitAccountingType.csv";VectorFilename =

"ariba/variants/voracle11/partitions/poracle11/data/SplitAccountingType.csv;config/variants/voracle11/partitions/poracle11/data/SplitAccountingType.csv";

Operation = "Load And Delete";};SchemaName = ariba.integration.VectorFileSchema;

};};

TopicName = SplitAccountingTypePull;};SplitAccountingTypeLanguagePull = {Channel = {ChannelContextMapFields = { Language = { FieldName = Language;

};};

};LoggingName = SplitAccountingTypeLanguage_CSV;MessageParameters = {Request = {Parameters = {EventSource = "poracle11:SplitAccountingType.csv";



ResourceFilename = "ariba/variants/voracle11/partitions/poracle11/data/translations/*/SplitAccountingType.csv";

Operation = "Update"; };SchemaName = ariba.integration.ResourceFileSchema;

};};TopicName = SplitAccountingTypeLanguagePull;

};

In this example:

• The SplitAccountingTypePull entry defines a simple pull event that reads data from a CSV file.

• The SplitAccountingTypeLanguagePull entry defines a language pull event that loads the languages for this integration event.

Data Files for the Language Pull Event

The SplitAccountingTypeLanguagePull integration event loads one or more data files, which are named by the ResourceFilename parameter. Each file contains a translation of the data in a different language.

The ResourceFilename parameter names a set of data files by including a wildcard for one part of the directory path. For example, the definition in this example might include the following files:

resource/language/FrenchCanadian/csv/SplitAccountingType.csvresource/language/French/csv/SplitAccountingType.csv

The wildcards in the ResourceFilename parameter must name entire directories, and not individual file names. For example, you cannot specify *.csv. You can specify multiple file names, separated by semicolons.

The language pull integration event reads any languages defined in resource/language, looking for files named SplitAccountingType. To supply the data for this integration event, you create a version of SplitAccountingType.csv in resource/language for each language you want to support.



The SplitAccountingType.csv file contains the unique name of each key, the translated name, and the language. For example, the following CSV file is the French Canadian version of SplitAccountingType.csv:

"UniqueName","Name","Language""_Amount","Montant","FrenchCanadian""_Percentage","Pourcentage","FrenchCanadian""_Quantity","Quantité","FrenchCanadian"

The default configuration includes several language pull events. It also includes corresponding export events that export multilingual data. For a complete list of these integration events, see the Ariba Buyer Configuration Reference Guide.

Primary String

When a string has multiple translations, one of those translations is marked as the primary translation during the data load process. The primary translation of a string is displayed whenever a translation does not exist for the user’s chosen locale.

For example, the SplitAccountingTypeLanguagePull integration event loads translations for the unique identifiers _Amount, _Percentage, and _Quantity. The CSV file for the English version of the SplitAccountingType.csv file is as follows:

"UniqueName","Name","Language""_Amount","Amount","English""_Percentage","Percentage","English""_Quantity","Quantity","English"

Suppose the primary translation for _Amount is English, and no translation is provided for French. In this case, Ariba Buyer displays the string “Amount” when a user chooses French as his or her locale.

Each time a user modifies a multilingual string, the primary translation is also changed. For example, suppose a German translation is provided for _Amount, but a French translation is still unavailable. The next time a user logs in and chooses the French locale, he or she will see a German string for _Amount.

In addition, multilingual string edits are saved in the language of the user’s default locale, even if that locale is different fromdifferent from the default language. Users can change their default locale information from the user interface, by modifying their user preferences. For more information, see “Preferred Locales” on page 98. The default language is set by the parameter Application.Base.Data.DefaultLanguage. For more information see “Parameters for Default Languages” on page 106.


Mapped Data Chapter 2 Data Sources for Integration Events

Mapped Data

Mapped data is data that is shared data (accessible to all partitions), but can potentially have different names in different partitions or be visible only in certain partitions. Countries, currencies, and units of measure are examples of mapped data.

You define mapped data with two integration events: one that defines a set of canonical values, and one that filters that set of canonical values to specify which are visible in a partition and how they are named in that partition.

The canonical values are common data, shared across all partitions. The filters are associated with a particular partition and loaded into that partition.

This section describes how you define and configure mapped data.

Data Files for Mapped Data

You set up mapped data with two CSV files:

• One that defines the canonical set of names

• Another that determines which of those canonical names are visible in a partition, and what the names are within that partition

You can use the mapping file for two purposes: to rename canonical values within a partition, and to specify which canonical values are visible in that partition. The mapping file contains some (or possibly all) of the canonical names.

For example:

Canonical Names (unpartitioned) Mapping File (partitioned)

"UniqueName","LanguageID”“English”,”1”"French","2""Italian","3""German","4""Dutch","6""Japanese","7"“FrenchCanadian”,”8”"BrazilianPortuguese","9"

"Key","Value","Preferred","Comment""DUT","Dutch","","Dutch""ENG","English","","English"“FRA”,”French,””,”French”“GER”,”German”,””,”German”"JPN","Japanese","","Japanese"

Chapter 2 Data Sources for Integration Events Mapped Data


In this example, there are eight languages in the list of canonical languages, but only five of them are named in the mapping file.

Only the six languages that appear in the mapping file will be visible in the partition. The mapping file also renames each of the six languages, using ERP-specific language codes such as “DUT” for Dutch. The three languages that are in the canonical file but not in the mapping file (FrenchCanadian, BrazilianPortuguese and Italian) are not defined in the partition.

Mapping File Format

The data file for a mapping file has the following four fields:

A mapping file always defines exactly one mapping for each Key. A given Key can map to multiple Values, or just one, but each Key must appear only once in the mapping file.

The Preferred Boolean applies when you have defined a canonical value that maps to more than one partition-specific value. For example, when Ariba Buyer is creating a purchase order to send to an ERP, and needs to translate the unit of measure into a value that will be acceptable on the ERP system, it uses the Preferred Boolean to decide which of the possible partition-specific values to use.

Field Description

Key The name used in the underlying ERP system. Every Key in the data file must be unique.

Value The canonical name associated with the Key.

Preferred A Boolean, set to either true or false. If there are several entries in a mapping file with the same Value, the Preferred field indicates which one to pick when the map is inverted, if there is any ambiguity.

Comment An optional comment. This field is for documentation within the data file.


Mapped Data Chapter 2 Data Sources for Integration Events

In the following example, the term Ea is mapped to two different terms in the ERP:

If Ariba Buyer has a purchase order that includes the term Ea and needs to push that order into the ERP, it must choose whether to map to Piece or Each. You use the mapping file to handle this situation by specifying exactly one ERP-specific value as the “preferred” choice.

Integration Event for the Canonical List

To define mapped data you set up two entries in the message configuration file (MessageConfiguration.table): one for the canonical list, and one for the mapping.

The integration event for the canonical list resides in Plain, and is similar to any other CSV file integration event definition.

You can also supply multilingual versions of the canonical data. To do this, define the set of canonical names as a standard CSV file integration that is possibly multilingual.

Integration Event for the Mapping

The integration event definition for the mapping resides in a partition. The integration events for all mapped data look very much alike. The only elements that differentiate one mapping from another are the Request > Parameters parameters.

The following example is a typical configuration file entry for the UnitOfMeasureMapPull integration event:

UnitOfMeasureMapPull = {Channel = { };LoggingName = UnitOfMeasureMap;MessageParameters = {Request = {Parameters = {EventSource = "poracle11:UnitOfMeasureMap.csv";Filename =

"config/variants/voracle11/partitions/poracle11/data/UnitsOfMeasureMap.csv";MapType = UOM;

Key Value Preferred

Piece Ea false

Each Ea true

Chapter 2 Data Sources for Integration Events Mapped Data


Operation = "Load And Delete";};SchemaName = ariba.integration.SimpleFileSchema;

};};

TopicName = UnitOfMeasureMapPull;};

The parameters in Request > Parameters identify this definition as a unit of measure map. The MapType keyword matches the mapValueType attribute in a metadata XML file. For example:

<class name="ariba.basic.core.UnitOfMeasure"prefix="uom"datafile="ariba.small"super="ariba.base.core.ClusterRoot"partitioned="false"privacy="public"><lookupKey fields="UniqueName"/><field name="UniqueName"nullAllowed="false"privacy="public"><type class="java.lang.String"length="50"/>

<properties rank="25"label="@aml.Requisition/UniqueNameLabel"editable="false"metaDataIntegration="Reference"mapValueType="UOM"/>

</field>

For detailed information on the MapType parameter, see the Ariba Buyer Configuration Reference Guide.

SimpleMapTypePull Integration Event

Ariba Buyer uses the SimpleMapTypePull integration event to define the simple map types in a configuration. This integration event reads from the data file ariba/variants/Plain/partitions/None/data/SimpleMapType.csv.

Most configurations use this set of mapped types without modification, but you might occasionally want to refer to it for reference.


Sources of Field Values Chapter 2 Data Sources for Integration Events

The following example shows the SimpleMapType.csv file in the default configuration:

Name,MapType,EnumerationClass"Currency","Ccy","ariba.basic.core.Currency""Country","Cty","ariba.basic.core.Country""Units of Measure","UOM","ariba.procure.core.UnitOfMeasure""Units of Measure CIF","UOM_CIF","ariba.procure.core.UnitOfMeasure""Ad hoc CIF supplier id fixups","SupplierFixup","Equivalent Words","EquivalentWords","Language","Lng","ariba.base.core.Language""Global Company Code","GlobalCompanyCode","Oracle UOM Info","OracleUOMInfo",

Sources of Field Values

In some cases, both Ariba Buyer and an integration event can create or update the same data field. For example, you typically allow users to maintain some or all of their own profile information through the Ariba Buyer user interface, and update other information by pulling data through an integration event.

In addition, administrators can use object managers in Ariba Buyer Administrator to directly manage data in the Ariba Buyer database. You might not want data that is manually modified or created in Ariba Buyer Administrator to be overwritten when integration events are reloaded.

This section describes how you can control the sources of field values.

Chapter 2 Data Sources for Integration Events Sources of Field Values


sourceOfTruth Field Property

The sourceOfTruth property is a class-level field property that specifies whether integration events or user input are the “source of truth” for a given field. This field property can be one of the following values:

If you do not specify the sourceOfTruth field property, the “source of truth” for a field is assumed to be ERP.

For example, suppose you want users to be able update their own default currency and locale manually, from the user interface, but not allow them to update other user profile information.

The following metadata XML example shows how you would set the sourceOfTruth field property on the default currency and locale fields:

<inClass name="ariba.user.core.User"><inClassVariant name="vcsv">

<inField name="DefaultCurrency"><properties sourceOfTruth="ORMS"/>

</inField><inField name=”LocaleID”>

<properties sourceOfTruth=”ORMS”/></inField>

</inClassVariant></inClass>

Supplemental Source of Truth Control

When the sourceOfTruth field property for a field is set to ORMS, that field in all objects is assumed to be maintained in Ariba Buyer and cannot be overwritten or deleted by integration events.

Value Description

ERP Indicates that the field value comes from an external source, such as an ERP system or a CSV file. Existing data is overwritten each time data is loaded through an integration event.

ORMS Indicates that the value is maintained in Ariba Buyer. Integration events cannot overwrite or delete fields that are maintained in Ariba Buyer. The first time an object is created, however, an integration event can load data in the object.


Sources of Field Values Chapter 2 Data Sources for Integration Events

In some situations, such as after migration, you might want to reload data from an external source for objects that are maintained in Ariba Buyer, but that have never actually been manually modified in Ariba Buyer. Supplemental source of truth control allows Ariba Buyer to distinguish between objects that have actually been manually modified, and those that have not.

When supplemental source of truth control is enabled, the adapter source for an object is automatically set to ManuallyMaintained whenever any Ariba Buyer-maintained field in that object is manually modified.

• Objects that do not have an adapter source of ManuallyMaintained can be overwritten or deleted by integration events.

• Objects that have an adapter source of ManuallyMaintained cannot be overwritten or deleted by integration events, unless the message configuration parameter IgnoreSourceOfTruth is set to true for the integration event. For more information on this message configuration parameter, see “IgnoreSourceOfTruth Message Configuration Parameter” on page 33.

Viewing an Object’s Adapter Source

An object’s adapter source is displayed in Ariba Buyer Administrator. For example, the following screen shows that the CSV file User.csv is the adapter source for the User object in the pcsv01 partition:

Chapter 2 Data Sources for Integration Events Sources of Field Values


The adapter source is also shown in audit messages. For example, audit messages for object creation and deletion have the following formats:

Object-Level Source:type_of_object:External (adaptersource_value)Object-Level Source:type_of_object:Ariba (ManuallyMaintained)

The Object-Level Source indicates whether the adapter source for an object is external (External), or if the object is maintained in Ariba Buyer (ManuallyMaintained). Similarly, audit messages for edits of existing fields have the following formats:

Field-Level Source:type_of_parent_object:Ariba (ManuallyMaintained)Field-Level Source:type_of_parent_object:External

The Field-Level Source indicates the adapter source of the field’s parent object. For field-level changes that show an external adapter source, the adapter source might not be the actual source because fields can be populated by various sources depending on the sourceOfTruth field property. A field-level change that shows an adapter source of ManuallyMaintained means that the field value cannot be overwritten by integration events.

For more information on the adapter source, see the Ariba Buyer Administrator online help.

Enabling Supplemental Source of Truth Control

To enable supplemental source of truth control, you set both of the following parameters to true:

• System.Admin.AutoSetAdapterSourceAfterManualModification• System.Messaging.IgnoreSourceOfTruth

When you set the AutoSetAdapterSourceAfterManualModification parameter to true, the adapter source for an object is automatically set to ManuallyMaintained when any Ariba Buyer-maintained field in that object is manually modified.

When you set the IgnoreSourceOfTruth parameter to true, integration events always override data, regardless of sourceOfTruth property settings, when the adapter source is not ManuallyMaintained.

Objects with the adapter source ManuallyMaintained are not updated by integration events, unless the message configuration parameter IgnoreSourceOfTruth is set to true for the integration event. For more information on this message configuration parameter, see “IgnoreSourceOfTruth Message Configuration Parameter” on page 33.


Load Order Chapter 2 Data Sources for Integration Events

In the default configuration, the AutoSetAdapterSourceAfterManualModification parameter is set to false.

The IgnoreSourceOfTruth parameter is not included in the default config/Parameters.table file. When it is missing from the config/Parameters.table file, IgnoreSourceOfTruth is considered to be false.

IgnoreSourceOfTruth Message Configuration Parameter

When the IgnoreSourceOfTruth message configuration parameter is set to true, it allows an integration event to update an object, even when the object’s adapter source is ManuallyMaintained. This parameter is used for data that is sent to Ariba Buyer from other Ariba applications through the Ariba File Channel, and not from external systems.

For more information on this parameter, see Appendix A, “Integration File Formats Reference.”

Load Order

The integration event configuration file defines a set of integration events, but does not define the order for running those integration events.

You define load order with two additional configuration files: LoadDB.txt and LoadDBLanguage.txt. This section describes those files.

LoadDB.txt File

You specify load order with another configuration file called the initialization order table file. This file specifies the order in which the data will be loaded into the database during database initialization. It applies only at database initialization time and is not used at any other time.

This configuration file is always called LoadDB.txt. There is only one LoadDB.txt file, no matter how many partitions you have in your configuration. The file consists of a list of integration events, in the order in which you would like them to load. Because there is only one version of the file, the names in this file must be complete and include partition names.

Chapter 2 Data Sources for Integration Events Load Order


The LoadDB.txt file can also include scheduled tasks. For information on scheduled tasks, see the Ariba Buyer Configuration Guide.

You list the integration events in the order in which you would like them initialized. The order is important when there are dependencies among data. For example, you should load your list of currencies before you load a list of currency conversion rates, because the currency conversion rates reference currencies.

The following example defines both global integration events (None) and integration events in the partition europe:

None.IntegrationEvent.LanguageMapPullNone.IntegrationEvent.CommodityCodePullNone.IntegrationEvent.UnitOfMeasureMapPullNone.IntegrationEvent.CountryMapPullNone.IntegrationEvent.CurrencyMapPullNone.IntegrationEvent.LocaleMapPulleurope.IntegrationEvent.SplitAccountingTypePulleurope.IntegrationEvent.SupplierPulleurope.IntegrationEvent.SupplierLocationSupplementPulleurope.IntegrationEvent.ApprovableTypePull

Every entry in the LoadDB.txt file has three parts, separated by a period:

• The first part is the partition name (or the special value None).

• The second part is IntegrationEvent.

• The last part is the TopicName of the integration event.

LoadDBLanguage.txt File

You use the LoadDBLanguage.txt file only if you have a multilingual configuration. This file specifies the integration events that load multilingual data, in the order in which you would like those integration events loaded. For example:

None.IntegrationEvent.AccountLanguagePullNone.IntegrationEvent.AdjustmentTypeLanguagePullNone.IntegrationEvent.AutoTypeLanguagePullNone.IntegrationEvent.CommodityCodeLanguagePullNone.IntegrationEvent.CostCenterLanguagePulleurope.IntegrationEvent.ExpenseTypeLanguagePulleurope.IntegrationEvent.LocationTypeLanguagePulleurope.IntegrationEvent.PaymentLanguagePulleurope.IntegrationEvent.ProcureLineTypeLanguagePulleurope.IntegrationEvent.SplitAccountingTypeLanguagePull


Load Order Chapter 2 Data Sources for Integration Events

Every entry in the LoadDBLanguage.txt file has three parts, separated by a period:

• The first part is the partition name (or the special value None).

• The second part is IntegrationEvent.

• The last part is the TopicName of the integration event.

You load the language data by running the following command:

initdb -loaddblanguage

By default, the initdb command does not load language data. If you plan to have a multilingual configuration, you must load the list of languages explicitly.

For more information on options to the initdb command, see the Ariba Buyer Installation Guide.

Chapter 2 Data Sources for Integration Events Load Order



Chapter 3

Integration Events

This chapter introduces integration events, describes the configuration files you use to define your integration with external systems, and explains how you use those files to configure Ariba Buyer with your own data. It includes the following sections:

• “Introduction to Integration Events” on page 37

• “Integration Channels” on page 38

• “Integration Event Files” on page 39

• “Integration Schema” on page 46

• “Accessibility and Scope of Field Values” on page 50

Introduction to Integration Events

You specify the data you want to load into your configuration with a set of integration events. Each integration event defines the details of one particular data exchange, such as reading in a list of users or sending purchase orders from Ariba Buyer to an external system.

An integration event defines the properties of a specific data exchange, such as:

• The data source

• The type of data that is exchanged

• The schedule for that data exchange

• Any other parameters required for the integration

Integration events can operate either on partitioned data or global data. For integrations that operate on partitioned data, you must specify properties for the integration event in each partition where you want the event to run.

Chapter 3 Integration Events Integration Channels


Integration Channels

Integration event data is processed through an integration channel. An integration channel is a communications channel that passes data between Ariba Buyer and an external system. The information sent on the integration channel is called a message.

Ariba Spend Management currently supports the following integration channels:

Different Ariba Spend Management applications use different combinations of channels. For example, a typical Ariba Spend Management application uses Ariba HTTP Channel to read shared data such as users, addresses, and suppliers from the Common Data Server, but then reads additional data from other data sources, with other channels.

Each channel has its own ways of processing the data in response to an event. For example, if you are using TIBCO, the integration event sends a message to TIBCO and launches a TIB/MessageBroker worksheet, which then performs the data processing and transfer. Therefore, you can think of integration events as triggers that simply send instructions to the channel, which does the actual work of pulling or pushing the data.

Integration Channel Description

Ariba File Channel An integration channel that allows Ariba Buyer to exchange data with CSV files.

Ariba cXML Channel An integration channel that allows Ariba Buyer to exchange data with Ariba Supplier Network (Ariba SN).

Ariba HTTP Channel An integration channel that allows Ariba Buyer to pull common data from, and send updates to, the Common Data Server (CDS).

TIBCO ActiveEnterprise An enterprise integration channel that Ariba Buyer can use to exchange data with databases and ERP systems.

IBM WebSphere Business Integration Adapter

An enterprise integration channel that Ariba Buyer can use to exchange data with databases and ERP systems.


Integration Event Files Chapter 3 Integration Events

Integration Event Files

Basic information about an integration event, such as the shape of the data it exchanges and what action it takes, is defined at the variant level in a message definition file. This information is used for all partitions in that variant.

Because different partitions use different data sources and operate on different schedules, and because you can have different configuration settings for each integration channel, you specify most of the integration event settings in a message configuration file at the partition level, once for each channel. This file defines the data sources for each data pull, the destinations for any data pushes, and any parameters the channel requires for each integration event.

Understanding Message Definition Files

The message definition file (MessageDefinition.table) defines an integration event by specifying the topic name, schema, and message type.

The topic name uniquely identifies the message sent by the integration event and is the key to linking information for the event in the message definition file with information for the event in the message configuration file.

The schema specifies the type and shape of the data so that Ariba Buyer knows how to process it. For more information, see “Integration Schema” on page 46.

Chapter 3 Integration Events Integration Event Files


The message type must be one of the following:

Message Type Description

Request-Reply In push events, the data is sent as part of the request, and the reply is a confirmation that the data was pushed successfully. In pull events, the request specifies the data to pull, and the reply contains the pulled data. For example, Ariba Buyer behaves as a requester to send a request to a replier.

Service A Service type event can be configured to invoke a service handler. A service integration event can return multiple data objects. The service type message is the reverse of the Request-Reply message type. That is, Ariba Buyer acts as the replier and waits for the request to be served. For example, in the HTTP channel configurations that are shipped with Ariba Buyer Version 8.2, a Sourcing application can invoke a service within Ariba Buyer to retrieve common data on the HTTP channel.

Publish An integration event can push data without specifying the recipient of the data. Unlike a Request-Reply integration event, which specifies the ERP system or file where the data is to be sent, a Publish event simply broadcasts the data under a given topic name. The topic name can then be picked up by one or more Subscribe events listening for messages of that topic name.

Subscribe A Subscribe integration event listens for messages that are published under a particular topic name by a Publish integration event or by an external system. When a message using that topic name is published, the Subscribe integration event pulls the published data. If the message is coming from an external system, the message configuration file specifies the subject name (source) of the message in the external system, mapping it to the topic name of the Subscribe integration event.



Integration Event Example

The following is an example of an integration event defined in a message definition file:

AddressPull = {Signature = {

Error = {};Pull = { Schema = ( "ariba.common.core.Address:AddressPull" );};Reply = {};Request = {};

};TopicName = AddressPull;Type = Request-Reply;

};

The Signature key defines the schema to use for each type of message sent or received by this integration event.

The TopicName parameter defines the name used by the message that exchanges the data.

The Type parameter specifies the message type, in this case, Request-Reply.

In this example, the data that is pulled will contain the fields defined in the ariba.common.core.Address:AddressPull object.

The message definition file contains the most basic information about the integration event and therefore resides at the variant level. More specific information, such as the data source and channel parameters, is specified in the message configuration files at the partition level.

Understanding Message Configuration Files

Different partitions typically pull data from different data sources, and on different schedules. Therefore, although the basic structure of integration events is defined at the variant level in the message definition file, you configure specific information such as the data source and scheduling information at the partition level in the message configuration file (MessageConfiguration.table).



Because this file also contains parameters specific to the channel, you have one copy of MessageConfiguration.table for each channel within the partition. For example, if you had an SAP and CSV partition in a variant called Europe, you might have the following message configuration files:

config/variants/Europe/partitions/CSV/channels/File/MessageConfiguration.tableconfig/variants/Europe/partitions/SAP/channels/File/MessageConfiguration.tableconfig/variants/Europe/partitions/SAP/channels/TIBCO/MessageConfiguration.table

Notice that the CSV partition uses only the Ariba File Channel, so it has only one message configuration file, whereas the SAP partition uses both the Ariba File Channel and TIBCO and therefore has two message configuration files.

If there are multiple message configuration files in the same partition, each integration event should use only one channel and must be specified in only one message configuration file. Therefore, in the SAP partition in the previous example, the integration events would be divided between the two channels and would be specified in the message configuration file either for the Ariba File Channel or the TIBCO channel, but not in both.

Alternatively, you can specify the event in both files, but specify the Disable parameter to disable the event in the channel that will not process the event. For example:

AddressPull = { ...

TopicName = AddressPull;Disable=true;

}

Integration Event Examples

The following are examples of the same integration event configured in a CSV partition for the Ariba File Channel, and in PeopleSoft 8 and SAP partitions for the TIBCO channel. Note that the name of the event and topic are the same, but the values for LoggingName, Parameters, and SchemaName differ.

Address Pull Using the Ariba File Channel in a CSV Partition

AddressPull = {Channel = { };LoggingName = Address_CSV;MessageParameters = {

Request = {



Parameters = {EventSource = "pcsv:Address.csv";Filename =

"config/variants/vcsv/partitions/pcsv/data/Address.csv";Operation = "Load And Delete";

};SchemaName = ariba.integration.SimpleFileSchema;};

};TopicName = AddressPull;

};

Address Pull Using the TIBCO Channel in a PeopleSoft 8 Partition

AddressPull = {Channel = { Subject = "vpsoft8.AddressEventPS";

TibcoSheet = AddressEventPS;};LoggingName = Address_PS;MessageParameters = {

Request = {Parameters = {

EventSource = "ppsoft8:Address:PSAdapter";ExternalConnection = "PSoftEP8Oracle";

};SchemaName = ariba.integration.param.Database;

};};Schedules = {

Schedule1 = { DayOfWeek = Weekday; Hour = 2;};};TopicName = AddressPull;

};

Address Pull Using the TIBCO Channel in an Oracle 11.0 Partition

AddressPull = {Channel = { Subject = "vorcl11.AddressEvent"; TibcoSheet = AddressEvent;};LoggingName = Address_Oracle;MessageParameters = {


DefaultChartOfAccountsId = 50317;EventSource = "porcl11:Address:Oracle";ExternalConnection = "Oracle11_0Financial";

};SchemaName = ariba.integration.param.DefaultChartOfAccountsId;

};};



Schedules = {Schedule1 = {

DayOfWeek = Weekday; Hour = 20; Minute = 30; Second = 30;

};};TopicName = AddressPull;

};

For complete information on message configuration files and their parameters, see Appendix A, “Integration File Formats Reference.”

ExecutionNode Parameter

You can use the ExecutionNode parameter to specify the logical node on which an integration event should run. For example, the following integration event is configured to run on the logical node named Node2:

AddressPull = {Channel = {

Subject = vpsoft75.AddressEventPS; TibcoSheet = AddressEventPS;

};LoggingName = Address_PS;MessageParameters = {


EventSource = "ppsoft75:Address:PSAdapter";ExternalConnection = PSoftEP75Oracle;

};SchemaName = ariba.integration.param.Database;};

};Schedules = { Schedule1 = { DayOfWeek = Weekday; Hour = 2;};};TopicName = AddressPull;ExecutionNode = “Node2”;

};

Valid values for the ExecutionNode parameter are a valid node name, PrimaryNode, or AllNodes (used only for the ArchiveLog event). If this parameter is not specified, the event runs on the primary node.



Location of Configuration Files

The location of message definition and message configuration files is specified in config/Parameters.table, with the following parameters

• Application.Messaging.MessageConfigurationFiles • Application.Messaging.MessageDefinitionFiles

These parameters specify the location of configuration files for each channel (and each partition, if appropriate). The value of each is a path, or a comma-separated list of paths. For example, entries for variant v1 and partition p1 might be as follows:

MessageConfigurationFiles = {File = {“p1” = config/variants/v1/partitions/p1/File/MessageConfiguration.table”;

Tibco = {“p1” = config/variants/v1/partitions/p1/Tibco/MessageConfiguration.table”;

...

In general, you use the default values for these parameters without modification.

Working with Integration Event Files

Both types of integration event files are in table format. To make changes to the MessageDefinition.table or MessageConfiguration.table files, you download the files using Ariba Buyer Administrator, edit the files using any text editor, and then upload them again to the config directory under BuyerServerRoot.

In the integration event files, every integration event starts with a name, such as AddressPull. This same name is used for each configuration of that integration event in all integration event files. The LoggingName parameter in the message configuration file prepended by the partition name uniquely identifies each configuration of the event in the database log. Additionally, some events use unique LoggingName values in each configuration to help differentiate among them. For example, the AddressPull event appears in several integration event configuration files, but it uses the LogginName value Address_PS in the PeopleSoft partition, Address_Oracle in the Oracle partition, and so on.

When naming an integration event, make sure to choose a name that is not used by any other events. Additionally, ensure that the name contains only letters, numbers, and underscores. Do not include spaces or other punctuation characters. Names must be no more than 50 characters long.

Chapter 3 Integration Events Integration Schema


In the default configuration, the integration events appear in the integration event files in alphabetical order for convenience, but you can enter events in any order.

If you create a Publish type integration event, make sure to add the parameter visible=true in the message configuration file so that you can run it from Ariba Buyer Administrator. By default, Publish events are not visible.

The parameters you use in an integration event depend on the schema you choose. For more information, see “Integration Schema” on page 46.

Reinitializing Integration Events

If you make changes to an integration event in a message configuration file, you must reinitialize the list of integration events from Ariba Buyer Administrator.

Note: If you make changes to an integration event in a message definition file, you must restart Ariba Buyer.

s To reinitialize integration events:

1 Log in to Ariba Buyer Administrator.

2 Choose Server Manager > Integration Events.

3 Verify that no integration events are running (no event shows the status as Running), and then click Reinitialize.

Integration Schema

Each integration event specifies the schema that defines the shape of the data that is being pulled or pushed. Each schema defines a set of fields and their data types and is stored as an object in the Ariba object model. By specifying schema, you don’t have to define the field types in every integration event. Instead, Ariba Buyer reads the schema to know what types of data the integration event is processing.


Integration Schema Chapter 3 Integration Events

Schema Specification

An integration event can specify more than one schema; for example, the AddressPull event specifies the schema ariba.integration.param.Database for the request but specifies the schema ariba.common.core.Address:AddressPull for the data pull. In other words, the outgoing request for data uses one set of fields, and the data that is being pulled uses another.

The schema you specify for pulled data must be a specific object created for that particular type of data only. Therefore, the data pull schema must not change from partition to partition—it is specified in the message definition file at the variant level. Because the schema for outgoing data will probably vary by partition and channel, you specify this schema in the message configuration file.

When specifying the schema for pushed data or for requests, you can use an existing schema or create a new one. The existing schemas are specified in metadata XML in the file IntegrationSchemas.aml, which is located in the following directory:

ariba/variants/Plain/extensions

To create your own schema or modify an existing schema, you create a new IntegrationSchemas.aml file in the following directory:

config/variants/Plain/extensions

You can then add the schema you want to create or edit. When you add an existing schema, it overrides the entry in the original file.

For example, the ariba.integration.param.Database schema in IntegrationSchemas.aml appears as follows:

<class name="ariba.integration.param.Database"super="ariba.integration.param.SimpleParams"prefix="ei"datafile="ariba.small"noSchema="true">

<field name="ExternalConnection"><type class= "ariba.integration.param.DBConnection"/><properties metaDataIntegration = "Reference"/>

</field></class>

Chapter 3 Integration Events Integration Schema


Each schema is part of the class ariba.integration.param. This schema inherits all the fields from SimpleParams, plus it includes a field called ExternalConnection that specifies the data source to use for the event. Therefore, when you specify the Database schema for the request in an integration event, the request data must include all the fields in SimpleParams plus an ExternalConnection field.

After creating or editing schema, you must run initdb -reshapedb to load the changes.

Merged Schema

For events that push data, some cases, the outgoing data uses a merged schema, which merges together the application data fields specified in the message definition file and fields specified in the message configuration file.

You can use the optional MergedSchem aName parameter to specify a name for the merged schema. For example:

PurchaseOrderPush = {...

MessageParameters = {Request = {

MergedSchemaName = ariba.integration.param.PurchaseOrderOraclePush;...SchemaName = ariba.integration.param.DefaultPreparerId;

...TopicName = PurchaseOrderPush;

If not specified, the default is to use the naming convention TopicName_SchemaName.

When you specify a merged schema name, you still need to specify the SchemaName parameter. The SchemaName information (along with the schema from the message definition file) is used to physically construct the merged schema. The schema you specify with the MergedSchemaName parameter is used only after the message has been sent to the channel.


Integration Schema Chapter 3 Integration Events

Default Schema

The following table describes some of the basic schema in the default configuration. You can use these schema to build additional schema. For example, you might use the super parameter (see the previous example) to inherit the fields from the Database schema (which would include the fields from SimpleParams and DBConnection), plus add additional fields to define the data you want to process.

In addition to these schema, you can look through IntegrationSchemas.aml to see if there are any other schemas that might suit your needs before you create a new one. Because other schema can be used as building blocks, you can usually inherit from an existing schema and add additional fields, rather than defining all the fields in the new schema.

Schema Description

SimpleParams Specifies the most basic parameters for an event, including the EventSource (which gives a unique label to data that is processed by this event), the partition, and the variant. Most other schemas inherit the fields from this schema.

SimpleFileResourceFileVectorFile

Specifies a data file by combining SimpleParams and a field for the filename, which varies by the type of file.

DBConnection Specifies information for connecting to a database, including the user name and password.

Database Specifies a database by combining SimpleParams and DBConnection.

Chapter 3 Integration Events Accessibility and Scope of Field Values


Accessibility and Scope of Field Values

To specify the accessibility and scope of a field, set the metaDataIntegration field property to one of the following values:

The integration layer expects the type of the destination field to match that of the data source. To force an explicit data narrowing operation, use the field property metadataIntegrationTypeOverride, which specifies an explicit subtype that can be stored into a field of a supertype.

Value Description

None (Default) The field is not accessible to the integration layer and cannot be used in integration events. Use None for fields such as counters that are internal to Ariba Buyer and must not be pulled or pushed by an integration event.

Reference The field is accessible by reference, as a link to an existing object. Use Reference for most fields populated by pull events. The field will be populated by a pointer to the appropriate data. For example, if you are pulling addresses, many addresses share the same country, so you must set the Country field to Reference, so that different Address objects all point to the same single shared Country object. Should be used for pull events only.

Export Use to specify fields that are “pushed” to external systems in push events. Should be used for push events only.

FullObject All details of the field are accessible to the integration layer. Use FullObject for integration events that need to pull several related objects. For example, the SupplierPull integration event must create both Supplier and SupplierLocation objects. Suppliers cannot necessarily link to an existing SupplierLocation object. Fields for line items on a requisition must also be set to FullObject, because in most cases each line item will be different and cannot simply link to an existing object. Should be specified for pull events only.


Accessibility and Scope of Field Values Chapter 3 Integration Events

For example:

<groupField name="Supplier.Buyer"><properties>

<property name="integration"><table>

<entry key="metadataIntegrationTypeOverride"value="ariba.user.core.Group"/>

</table></property>

</properties>

In this example, the type of Supplier.Buyer is declared to be Principal, but the incoming data is of type Group. Because Group is a subclass of Principal, the metadataIntegrationTypeOverride key is used to narrow the type. If you do not specify this property, the pull fails.

Chapter 3 Integration Events Accessibility and Scope of Field Values



Chapter 4

Ariba File Channel

This chapter describes how to define and customize integration events that use the Ariba File Channel. It includes the following sections:

• “Introduction to the Ariba File Channel” on page 53

• “Simple Pull Events” on page 55

• “Language Pull Events” on page 60

• “Header-Detail Pull Events” on page 62

• “Excel as a Data Source” on page 65

• “Export Events” on page 70

• “Customizing Data Mappings” on page 74

Introduction to the Ariba File Channel

The Ariba File Channel is the recommended integration channel for exchanging data with disk files, such as CSV (comma-separated value) files and Excel spreadsheets.

The Ariba File Channel uses the following configuration files:

• MessageDefinition.table

• MessageConfiguration.table

• IntegrationMappings.aml

Chapter 4 Ariba File Channel Introduction to the Ariba File Channel


For example, the following diagram illustrates how Ariba Buyer uses the Ariba File Channel to exchange data with CSV files:

Finding Configuration Files

You specify the location of the message definition and message configuration files with the parameters Application.Messaging, as described in “Location of Configuration Files” on page 45.

The integration mappings file, which defines mappings between the data source and the object model, is located in the following directory:

ariba/variants/variant/extensions/IntegrationMappings.aml

The default configuration also includes a separate integration mappings file that defines integration mappings for Common Data Server (CDS) integration events. The Common Data Server integration mappings file is located in the following directory:

ariba/variants/variant/extensions/CommonDataMappings.aml

There are integration mapping files for each variant.

Ariba Buyer

Ariba File Channel CSV File

MessageConfiguration.table

MessageDefinition.table

“Pull” data

“Push” data

IntegrationMappings.amlAriba BuyerDatabase

1

2

3

4

5


Simple Pull Events Chapter 4 Ariba File Channel

You can create metadata XML extension files to add, delete, or change mappings and transformations in the default configuration. You never modify the integration mappings files in the ariba directory. For information on how to customize these files, see “Customizing Data Mappings” on page 74.

Parameters.table Settings

In config/Parameters.table, the parameters in the section System.Messaging.Channels.File define the default behavior of the Ariba File Channel. For example, the parameter System.Messaging.Channels.File.FileReaders specifies the mapping between file types and Java files used to parse files of that type. The default configuration defines the following Ariba File Channel file readers:

FileReaders = {CSV = "ariba.channel.io.CSVFileReader";SUPPLIER = "ariba.channel.io.SupplierFileReader";XLS = "ariba.channel.io.ExcelFileReader";

};

The values in the default configuration are appropriate for most configurations. Ariba recommends that you use the default settings.

For complete information on these parameters, see the Ariba Buyer Configuration Reference Guide.

Simple Pull Events

Pull events are integration events that pull data into Ariba Buyer. There are three types of pull events:

• Simple pull events

• Language pull events

• Header-detail pull events

This section describes the configuration file entries for a simple pull event. Later sections describe other kinds of pull events, as well as export events and events that pull from other data sources, such as Microsoft Excel.

Chapter 4 Ariba File Channel Simple Pull Events


The Message Definition File

As described in “Understanding Message Definition Files” on page 39, a message definition file (MessageDefinition.table) defines an integration event by specifying the topic name, schema, and message type.

The following is a typical example of a message definition file for a pull event:

RolePull = {Signature = {Error = {};Pull = { Schema = ( ariba.user.core.Role:RolePull ) };Reply = {};Request = {};

};TopicName = RolePull;Type = Request-Reply;

};

In this example:

• The Schema parameter specifies the type of object this integration event is pulling. The format is class:group, where:

• class is the class name of the object being created in Ariba Buyer

• group is the name of a group that defines how the columns in the CSV file map to the fields in the object

For more information on how to use this group to set up the mappings between columns in the data source and the fields in Ariba Buyer, see “The Integration Mappings File” on page 59.

• The TopicName is a unique identifier for this event, used to link the information in the message definition file with the information in the message configuration file

• The Type specifies whether this is a Request-Reply event or a Publish-Subscribe event. A Request-Reply event specifies the exact file or data source with which you are exchange data; a Publish-Subscribe event does not. All pull events are Request-Reply events.

The other parameters remain the same for all basic pull and export events. For complete information on the parameters that can appear in message definition files, see Appendix A, “Integration File Formats Reference.”



The Message Configuration File

The message configuration file defines partition-level information, such as the name of the file used as the data source. The following example shows the message configuration for the RolePull event, which imports roles from a single CSV file called Role.csv.

RolePull = {Channel = {

ChannelContextMapFields = { Language = { defaultValue = English };

};};LoggingName = Role_CSV;MessageParameters = {


EventSource = "None:Role.csv";Filename =

"config/variants/Plain/partitions/None/data/Role.csv";Operation = "Load And Delete";

};SchemaName = ariba.integration.SimpleFileSchema;

};};TopicName = RolePull;

};

In this example:

• The Channel section defines channel-specific parameters. In this case, the event is creating objects of type multilingual string, and so the parameter defines the default language in which those strings are to be created. For a complete list of channel-specific parameters for the Ariba File Channel, see “Channel Parameters” on page 255.

• The MessageParameters section defines the details of this event.

• The FileName parameter defines the data source for this event. In this case, the data source is a single CSV file, Role.csv. For more information on data sources, and how to specify multiple files, see “Multiple CSV Files as the Data Source” on page 20.

• The Operation is a keyword that indicates whether this integration event is loading, updating, or deleting data, and the EventSource is used to mark items originating from this event. For more information on these parameters, see “Using Operation and EventSource” on page 58.

Chapter 4 Ariba File Channel Simple Pull Events


• The SchemaName parameter specifies how to translate between the file types in the data source and the file types in the database. The value is usually ariba.integration.SimpleFileSchema, as shown here. This schema sets up the infrastructure and parameters for reading information from a disk file. For more information, see “Integration Schema” on page 46.

For information on all the parameters for pull events, see Appendix A, “Integration File Formats Reference.”

Using Operation and EventSource

The Operation parameter determines whether an integration event adds data, updates existing data, or deletes data. The Operation parameter interacts with the EventSource parameter to determine the behavior of the event.

Each integration event defines an EventSource, which is used to mark all items in the database that originated from that integration event. The EventSource parameter is used in mark and sweep operations, providing the ability to determine which items were loaded by previous runs of this integration event.

For example, the Load and Delete operation reads the data source and compares the list of items in the data source against the list of items in the Ariba Buyer database and does the following:

• Adds to the database any item that is in the data source but not in the database

• Updates in the database any item that is in the data source and also in the database

• Deletes from the database any item that is marked with this EventSource, but is currently in the data source

The EventSource parameter applies to the Load and Delete and Load and Update operations. The other possible operations operate on one record at a time, and do not use the EventSource. The single-record operations are as follows:

• Create—Reads the data source, and adds any items in the data source

• Delete—Reads the data source, and deletes all items in the data source

• Update—Reads the data source and updates all items in the data source

• Load—Reads the data source and creates or updates, as appropriate

In the default configuration, integration events are defined with appropriate Operation parameters, most commonly Load and Delete. By changing the operation, you can change the behavior of the event.



Deleting Data

The Delete operation does not actually delete data, but instead marks the data as inactive in the database. If you later run a pull with an Update operation that matches the deleted data, the old data will be reactivated.

Use the following procedure to delete all data loaded through an integration event.

s To delete data loaded with Ariba File Channel, do the following:

1 Edit your CSV data source to have one data record.

2 Set the operation field to Load and Delete.

3 Run the pull.

If the data source is empty, the integration framework does not delete the data. This is an intentional precaution to avoid accidental deletion of data.

If the values are set to null in the data source, the integration event sets those values to null in the database, but does not delete the data.

The Integration Mappings File

An integration mappings file defines how to map between the field names in Ariba Buyer and column names in the CSV data source. This file, which is in metadata XML format, defines the groups used in the schema definition. For example, this schema definition:

Pull = { Schema = ( ariba.user.core.Role:RolePull ) };

Refers to the group RolePull, which is defined in an integration mappings file. The following example shows the RolePull group as it appears in an integration mappings file:

<group name="RolePull"><groupClass name="ariba.user.core.Role">

<groupField name="UniqueName"/><groupField name="Name"/>

</groupClass></group>

In this example, the fields to be pulled from the CSV file are UniqueName and Name. In this example, the field names in the data source are the same as those in the data source.

Chapter 4 Ariba File Channel Language Pull Events


If there is a mismatch between the name of a field and the corresponding column name in the CSV file, the entry key mapField in the integration field property is used to specify the name of the column in the CSV file that maps to the field. For example, in the AddressPull group, the CSV column named Country is mapped to the field UniqueName.

<groupField name="Country.UniqueName"><properties rank="70">


<entry key="mapField" value="Country"/><entry key="defaultValue" value="US"/>

</table></property>

</properties></groupField>

If the field has a default value, the entry key defaultValue in the integration field property specifies that default value. For example, in the AddressPull group, the field UniqueName field is given the default value US:

<groupField name="Country.UniqueName"><properties rank="70">


<entry key="mapField" value="Country"/><entry key="defaultValue" value="US"/>

</table></property>


You never modify the integration mappings files in the ariba directory, but you can create extension files to add, delete, or change mappings and transformations in the default configuration. For information on how to customize mappings, see “Customizing Data Mappings” on page 74.

Language Pull Events

A language pull event is similar to a simple pull event, except that the data is read from multiple files, each containing a translation of the data in a different language.


Language Pull Events Chapter 4 Ariba File Channel

The following example shows the message configuration file entry for the LanguageLanguagePull integration event. LanguageLanguagePull is used in multilingual configurations to define language names in other languages.

LanguageLanguagePull = {Channel = {

ChannelContextMapFields = { Language = {

FieldName = Language;};

}};LoggingName = LanguageLanguage_CSV;MessageParameters = {


EventSource = "None:LanguageLanguage.csv";ResourceFilename =

"ariba/variants/Plain/partitions/None/data/translations/*/Language.csv";Operation = "Update";

};SchemaName = ariba.integration.ResourceFileSchema;

};};TopicName = LanguageLanguagePull;

};

In this example, note the following:

• The Channel section defines channel-specific parameters. In this case, the FieldName parameter specifies how to map the Language column in each of the CSV resource files to the language field on the event context. For a complete list of channel-specific parameters for the Ariba File Channel, see “Channel Parameters” on page 255.

• The request parameters define a set of resource files to be used as the data source. To name a set of files, you include a wildcard for one part of the directory path. The wildcard must name a directory, and not an individual file name. For example, you cannot specify *.csv. You can specify multiple file names, separated by semicolons.

Because each resource file might use a different encoding, a language pull event is invoked multiple times, once for each resource file.

• For a language pull event, the operation is usually Update. If you are pulling new translations, you do not want to delete translations that are already present.

Chapter 4 Ariba File Channel Header-Detail Pull Events


• For a language pull event, the schema is ariba.integration.ResourceFileSchema. For more information, see “Integration Schema” on page 46.

For information on all the parameters for language pull events, see Appendix A, “Integration File Formats Reference.”

Header-Detail Pull Events

Sometimes header data is located in one CSV file and detail data is located in another CSV file. In this situation, you can implement the integration event in either of the following ways:

• Read the header data and the detail data with separate pull events, and then use another pull event to update the header objects with the BaseIds of the detail objects.

• Load the header and detail data with a single pull event.

The first approach is usually more efficient because data is pulled from a single file, and a join is not required. However, there are some situations where you cannot load header and detail data separately.

For example, if the detail data is BaseObject (ariba.base.core.BaseObject) and not ClusterRoot (ariba.base.core.ClusterRoot), it can exist only in the context of the header object. Therefore, both the header and the detail data must be pulled in a single header-detail pull event.

This section describes how each type of header-detail pull event is defined in the message definition and message configuration files.

Loading Header and Detail in Separate Events

An example of loading header and detail data separately is the SharedUserShipToAddressMapPull integration event. This integration map defines a mapping between shared users and shipping addresses.

This integration event must run after the SharedUserPull integration event, and after the AddressPull integration event.


Header-Detail Pull Events Chapter 4 Ariba File Channel

SharedUserShipToAddressMapPull = {Channel = { };LoggingName = SharedUserShipToAddressMapPull_CSV;MessageParameters = {


EventSource = "pcsv:SharedUserShipToAddressMap.csv";Filename =

"config/variants/vcsv/partitions/pcsv/data/SharedUserShipToAddressMap.csv";Operation = "Update Elements Only";


};TopicName = SharedUserShipToAddressMapPull;

};

The Operation parameter must be set to “Update Elements Only”.

Loading Header and Detail Data In a Single Event

The CommonSupplierIDMapPull integration event defines a mapping between supplier IDs and common suppliers by pulling both detail data and header detail. CommonSupplierIDMapPull reads from two CSV files:

• CommonSupplierIDMapHeader.csv (the header data file)

• CommonSupplierIDMap.csv (the detail data file)

The following message configuration example shows how CommonSupplierIDMapPull is defined:

CommonSupplierIDMapPull = {Channel = { };LoggingName = CommonSupplierIDMap_CSV;MessageParameters = {


EventSource = "None:CommonSupplierIDMap.csv";HeaderFileName =

"config/variants/Plain/partitions/None/data/CommonSupplierIDMapHeader.csv";Operation = "Create";Details = ( { DetailFileName =

"config/variants/Plain/partitions/None/data/CommonSupplierIDMap.csv";ParentField = "SupplierID.Ids";JoinFields = ( "JoinToken = JoinToken");

}

Chapter 4 Ariba File Channel Header-Detail Pull Events


)};SchemaName = "ariba.integration.HeaderDetailSchema";

};};TopicName = CommonSupplierIDMapPull;

};

In the example, note the following:

• The HeaderFileName parameter specifies the CSV file with the header data and the DetailFileName specifies the name of the CSV file (or vector of files) that contains the detail data.

• For a header and detail data pull event, the operation is usually Create.

• For a header and detail data pull event, the schema is usually ariba.integration.HeaderDetailSchema.

• The JoinFields parameter specifies the join relationship between a field in the detail data and a field in the header data. In this example:

JoinFields = ("JoinToken = JoinToken");

The first JoinToken specifies a field in CommonSupplierIDMap.csv, and the second JoinToken specifies a field in CommonSupplierIDMapHeader.csv.

• The ParentField parameter specifies the field in the header object to which you want to map the detail data. For example:

ParentField = SupplierID.Ids;

For a complete list of possible parameters, see Appendix A, “Integration File Formats Reference.”

Specifying Multiple Levels of Header Details

The Details key can contain a vector of details. In addition, each DetailFileName can contain multiple details. The following example shows a vector of report permissions and report columns:

Parameters = {Details = (

{DetailFileName = "config/variants/vcsv/data/ReportPermissionMap.csv";JoinFields = ( "ReportUniqueName = UniqueName" );ParentField = ReportPermissions;},


Excel as a Data Source Chapter 4 Ariba File Channel

{DetailFileName = "config/variants/vcsv/data/ReportColumnMeta.csv";JoinFields = ( "ReportUniqueName = UniqueName" );ParentField = ReportColumns;}

);EventSource = "ReportMeta_vcsv";HeaderFileName = "config/variants/vcsv/data/ReportMeta.csv";

You can also nest details. For example:

RequisitionLineItems

Split Accounting

The following example shows this three-level nesting:

Parameters = {HeaderFileName = "somePath/Requisition.csv";Details = (

{DetailFileName = "somePath/LineItems.csv";JoinFields = ( "ReqNum = UniqueName" );ParentField = LineItems; Details = (

{ DetailFileName = “somePath/SplitAccounting.csv”;JoinFields = (“LineItem = UniqueName”);ParentField = SplitAccountings;

})

});

Excel as a Data Source

Integration events that read from Excel spreadsheets use the Excel file reader (ariba.channel.file.io.ExcelFileReader).

When you read from an Excel spreadsheet, the MessageDefinition.table file is the same as for a CSV data source. In MessageConfiguration.table, you set the FileType parameter to XLS.

Chapter 4 Ariba File Channel Excel as a Data Source


For example:

SomeExcelPull = {Channel = {

FileReaderParams = { };FileType = XLS;Locale=en_us;

};

This section describes additional message configuration file entries that apply only when reading data from Excel.

Localized Header Columns in Spreadsheets

If you are reading from Excel spreadsheets with localized headers, you can specify the locale as part of your channel parameters. For example:

SomeExcelPull = {Channel = {

FileType = XLS;Locale=en_us;

};

When a locale is specified, Ariba Buyer uses the locale to look up the header string in a resource file. For example, if the header in the spreadsheet is Nom, and the locale is fr_CA, then Ariba Buyer looks up the string Nom in the following resource file:

docroot/ariba/resource/fr_CA/strings/aml.Core.csv

In that resource file is the mapping from the localized string (“Nom”) to the key (“NameHeader”):

NameHeader,Nom,,

Multiple Worksheets

The Excel file reader can read Excel workbooks that contain multiple worksheets. Each Excel worksheet represents a level of detail, which is defined with the DetailFileName parameter in the MessageConfiguration.table entry.



For example:

Details = ({

DetailFileName = "@Contract Header”;JoinFields = ();ParentField = SupplierIDs;InternalVectorFields = "SupplierID Domain, SupplierID Value";RowDelimiter = "Requester";

},DetailFileName = “@Header Attachments”;ParentField = RemoteAttachments;Joinfields = ();EmptyVectorOnNoData = true;

},{

DetailFileName = "@Contract Item Information"; EmptyVectorOnNoData = true;JoinFields = ();ParentField = LineItems;

Details = ({

DetailFileName = "@Item Attachments";JoinFields = ("Item Number = Item Number");ParentField = RemoteAttachments;EmptyVectorOnNoData = true;

},{

DetailFileName = "@Item Attributes";JoinFields = ("Item Number = Item Number");ParentField = SourcingExtrinsics;EmptyVectorOnNoData = true;

},{

DetailFileName = "@Contract Item Information";JoinFields = ();ParentField = ClassificationCodes;InternalVectorFields = "Classification Code, Classification Domain";RowDelimiter = "Item Number";

},{

DetailFileName = "@Pricing Information";JoinFields = ("Item Number = Item Number");ParentField = TierPricingInfo;EmptyVectorOnNoData = true;

Details = ({

DetailFileName = "@Pricing Information";JoinFields = ();ParentField = MinTierValues;

Chapter 4 Ariba File Channel Excel as a Data Source


InternalVectorFields = "Minimum Tier Value";RowDelimiter = "Item Number";

},{

DetailFileName = "@Pricing Information"; JoinFields = ();ParentField = TierValues;InternalVectorFields = "Tier Value";RowDelimiter = "Item Number";

});

});

},{

DetailFileName = "@Header Attributes"; JoinFields = ();ParentField = SourcingExtrinsics;EmptyVectorOnNoData = true;

}EventSource = "@partition@:MasterAgreementRequest";HeaderFileName = "@Contract Header";Operation = "Load";};

During the details load, the Excel file reader uses the details worksheet to generate details records. The header worksheet is restored as the current sheet upon completion of the details record generation.

Loading Vector Fields

The InternalVectorFields parameter specifies how to load a column, or set of columns, to correspond to a vector detail field. In the following example, the Classification Code and Classification Domain columns are treated as the details vector for the parent field ClassificationCodes.

{DetailFileName = "@Contract Item Information";JoinFields = ();ParentField = ClassificationCodes;InternalVectorFields = "Classification Code, Classification Domain";RowDelimiter = "Item Number";

},



The RowDelimiter parameter specifies the column that is checked to see if the next record being read from the current worksheet is the next header-level record, or if it is an internal detail record.

In this example, the RowDelimiter parameter is set to Item Number. All the detail rows will be read until the Item Number column value becomes non-null (2 in the following example):

If the RowDelimiter parameter is not specified, then only the current row is read to load the vector details.

Logging Errors

For integration events that read from Excel, you can use the following Boolean parameters to control additional logging:

• LogNonFatalErrors. If this parameter is set to true, additional errors such as lookup errors are logged in the error log. The event status will be “Completed with warnings”. This parameter is false by default.

• IncludeLocationRef. If this parameter is set to true, the location of the error (columnName and line number) is included in the error message for invalid data fields. This parameter is false by default.

Chapter 4 Ariba File Channel Export Events


Export Events

An export event exports objects from the Ariba Buyer database to a CSV file. An Ariba Buyer administrator can import an exported CSV file into a different Ariba Buyer instance using Ariba Buyer Administrator.

This section describes how export events are defined in message configuration files.

Message Definition for an Export Event

The following example shows a message definition file entry for the UserExport export event:

UserExport = {Signature = {

Schema = "ariba.user.core.User:UserExport";};TopicName = UserExport;Type = Publish;

};

Message Configuration for an Export Event

The following example shows the message configuration file entry for the AddressExport integration event. AddressExport exports Address objects from a partition. In this example, it exports Address objects from a partition named pcsv.

AddressExport = {Channel = {

Encoder = { Name = FileChannelEncoder };};LoggingName = AddressExport_CSV;MessageParameters = {


Filename = "config/variants/vcsv/partitions/pcsv/data/Address_Export.csv";


};TopicName = AddressExport;

};


Export Events Chapter 4 Ariba File Channel

In the example, note that the FileName specifies the name of the exported file. All exported files should follow the naming convention originalname_Export.csv.

If you export data to the same filename as the original CSV file, you will overwrite the data in the original CSV file.

For an export event, the schema is usually ariba.integration.SimpleFileSchema.

You can set up filter conditions to restrict a query for an export event. For information, see “Filtering Export Events” on page 77.

For information on all the parameters for export events, see Appendix A, “Integration File Formats Reference.”

Specifying an Export Language

Export events export data in the default language for your system, as specified by the System.Base.Data.DefaultLanguage parameter in config/Parameters.table.

For example, suppose your default language is German. When you export roles from Ariba Buyer Administrator, the RoleExport event writes role data in German to the file Role_Export.csv.

Creating Language Export Events

You can create language export events to export data in different languages. You create one export event for each language you want to export.

For example, suppose you want to export the French translation of permissions. You could create an integration event named PermissionFrenchLanguageExport:

PermissionFrenchLanguageExport = {Channel = {

Encoder = {Name = FileChannelEncoder;Parameters = { };

}ChannelContextMapFields = {

Language = "French";};

}; LoggingName = PermissionLanguageExport;MessageParameters = {

Request = {

Chapter 4 Ariba File Channel Export Events


Parameters = {EventSource = "None:PermissionLanguageExport"Filename =

"config/variants/Plain/partitions/None/data/translations/French/Permission_Export.csv";

};SchemaName = ariba.integration.SimpleFileSchema;

};};TopicName = PermissionLanguageExport;

};

You use the Language parameter in the ChannelContextMapFields key to specify the language to be exported (French in this example). The TopicName should be the same for all languages.

Specifying Field Order in Exported Files

The rank field property is used to specify the order of fields in an exported file. For example, in the AddressPull group, the field UniqueName is first and the URL field is last:

<group name="AddressPull"><groupClass name="ariba.common.core.Address">

<groupClassVariant name="vcsv"><groupField name="UniqueName">

<properties rank="10"/></groupField>

...

<groupField name="URL"><properties rank="110"/>

</groupField> </groupClassVariant>

</groupClass></group>

Note: If the same group is used for both pull and export events, the rank field property is ignored in the pull event.


Export Events Chapter 4 Ariba File Channel

How to Export Manually Maintained Data

The export events in the default configuration do not export manually maintained data (objects that have the adapter source ManuallyMaintained). To export manually maintained data, do one of the following:

• Modify the filter condition in the export event to include manually maintained data.

• Create a new export event to export the manually maintained data to a different export file.

For information using filter conditions, see “Filtering Export Events” on page 77.

For more information on manually maintained data, see “Supplemental Source of Truth Control” on page 30.

Export Events in Ariba Buyer Administrator

This section describes how to invoke export events from Ariba Buyer Administrator.

Configuring a New Exporter

When you add a new export event to export a custom object, you might also want to add a new exporter to Ariba Buyer Administrator so that administrators can run the export event by clicking the Export button.

The following example shows the Export button in Ariba Buyer Administrator:

Chapter 4 Ariba File Channel Customizing Data Mappings


Exporters in the default Ariba Buyer Administrator configuration are defined in the object manager configuration file (ObjectManager.acf). For information on how to add a new exporter, see the Ariba Buyer Administrator Customization Guide.

Customizing the Default Exporters

The exporters in the default configuration use the sample data that ships with Ariba Buyer. To use these exporters in a production environment, you must customize them for your configuration.

For information on customizing the default exporters, see the Ariba Buyer Administrator Customization Guide.

Customizing Data Mappings

This section describes how to extend the data mappings and transformations in the default configuration. To make changes, you always create extension files in the config directory. Do not modify the integration mappings files in the ariba directory directly.

Creating an Integration Mappings Extension File

The following procedure summarizes the steps involved in creating a metadata XML extension file to extend or modify data mappings and transformations.

s To create an integration mappings extension file:

1 Create a file with extension aml. For example: IntegrationExt.aml.

2 Make sure the first line of the file names the metadata XML extension DTD file extensions.dtd and specifies the document type extension. For example:

<!DOCTYPE extension SYSTEM "../../../../ariba/base/meta/core/extensions.dtd">

The path from the DOCTYPE line must locate the DTD file in your configuration.


Customizing Data Mappings Chapter 4 Ariba File Channel

3 Make sure the second line of the file specifies the extension name and path:

<extension name=”config.variants.variant.extensions.IntegrationExt”>

4 In the third line of the file, use the <import> tag to reference the definitions in IntegrationMappings.aml. For example:

<import extension=”ariba.variants.Plain.extensions.IntegrationMappings”/>

Note: If you are defining groups for a custom class, you must also import the metadata XML extension file where the custom class is defined.

5 Make sure the inModule tag names the module where the group class is defined. For example, if you are extending the ApprovableTypePull event, you would specify:

<inModule name="ariba.common.meta.Core">

6 Store your IntegrationExt.aml file in the config directory under BuyerServerRoot. For example:

config/variants/variant/extensions/IntegrationExt.aml

For example:

<!DOCTYPE extension SYSTEM "../../../../ariba/base/meta/core/extensions.dtd"><extension name="config.variants.Plain.extensions.IntegrationExt">

<import extension="ariba.variants.Plain.extensions.IntegrationMappings”/><inModule name="ariba.common.meta.Core">

...</inModule>

</extension>

For information on metadata XML extension files, see the Ariba Buyer Customization Guide.

Using the integration Field Property

You use the integration field property to specify data mappings and transformations for groups in your integration mappings extension file, to set up filter conditions to restrict a query for an export event, or to handle type mismatches between the data source and the object model.

This section highlights common uses for the integration field property. For a complete list of the values you can specify for the integration property, see “Integration Mapping Files” on page 261.



Mapping Field Names

The integration field property defines a table of key/value pairs. For example:


<entry key="mapField" value="Group"/></table>

</property>

You use the mapField key to map the name of a field to the name of a column when the field name and the column name in the CSV file are different. The value parameter specifies the name of the column in the CSV file. In this example, the field UniqueName is being mapped to a the column named Group.

Another possible key is defaultValue, which maps the field to a hard-coded text value. For example:

<groupField name="Type.MapType"><properties>


<entry key="defaultValue" value="MyMap"/></table>

</property></properties>

</groupField>

Type Narrowing

The integration layer expects the type of the destination field to match that of the data source. To force an explicit data narrowing operation, use the key metadataIntegrationTypeOverride, which narrows the parent field to an explicit subtype. For example:

<groupField name="Supplier.Buyer"><properties>


<entry key="metadataIntegrationTypeOverride"value="ariba.user.core.Group"/>

</table></property>

</properties>



In this example, the type of Supplier.Buyer is declared to be Principal, but the incoming data is of type Group. Because Group is a subclass of Principal, the metadataIntegrationTypeOverride key is used to narrow the type. This property is required if you are pulling data that is a subtype.

Filtering Export Events

By default, an export event exports all data. To restrict the set of data being exported, you can add filters in the integration property. For example, to exclude State fields that have the value CA:

<groupField name="State"<properties>


<entry key="equals" value="CA"/><entry key="exclude" value="true"/>

</table></property>

<properties></groupField>

If you use the same group for both pull events and export events, the export filters are ignored during the pull event.

For a complete list of the filters that you can specify, see “Integration Mapping Files” on page 261.

In export events, the Rank field property determines the order of exported fields.For example:

<group name="CommodityImportMapExport"><groupClass name="ariba.common.core.CommonCommodityCode">

<groupField name="UniqueName"><properties rank="10">


<entry key="mapField" value="CommonId"/></table>


</groupField><groupField name="CommodityImportMap.Domain">

<properties rank="20"><property name="integration">

....



Setting Up Filter Conditions for Partition-Specific Data

To specify a filter condition that is based on partition-specific data, do the following:

• In the group defined for the export event, include a field that specifies the value for the condition as a substitutable parameter.

• In the message configuration file entry for the export event, specify the value to be substituted as an Encoder parameter.

The following example shows how to set up a filter condition to export only those users who belong to an adapter source in a particular partition. First, the field that specifies the substitutable value is added to the group for the export event:

<group name="UserExport"><groupClass name="ariba.core.User">

<groupClassVariant name="vcsv"><groupField name="AdapterSource">

<properties rank="40"><property name="integration">

<table><entry key="equals" value=":EventSource"/><entry key="exclude" value="true"/>

</table></property>


</groupClassVariant></groupClass>

</group>

The colon (:) indicates the substitutable value. The field is used only to constrain the result, so the entry key exclude is used to exclude the field from the export.

Next, the value to be substituted is specified at the partition level by including it in the Encoder > Parameters > EventSource parameter in the message configuration file definition for the export event:

UserExport = {Channel = {

Encoder = {Name = FileChannelEncoder;Parameters = { EventSource = "pcsv:User.csv" };

};};LoggingName = User_CSV;



If you are not sure of the exact value to which you want to restrict the query, or if you want to select multiple values, you can use the like entry key instead of the equals entry key. For example:

<groupField name="AdapterSource"><properties rank=”40”>


<entry key="like” value=":EventSource"/><entry key="exclude" value="true"/>

</table></property>


When you specify the like entry key, you use the percent sign (%) in the message configuration file entry to specify a pattern to match. For example:

SupplierLocationExport = {Channel = {

Encoder = {Name = FileChannelEncoder;Parameters = {

EventSource = "%:%";};

};};

In this example, the constraint would be translated in SQL as follows:

"WHERE Table.EventSource like "%:%"..."

Using the metaDataIntegration Field Property

You can use the metaDataIntegration field property in your integration mappings extension file to define nested groups by specifying the name of another group. For example:

<groupField name="PCards"/><properties metaDataIntegration="PCardDetail"/>

</groupField>

In this example, the fields defined in the group PCardDetail are also included.



The metaDataIntegration field property is also used to specify the accessibility and scope of a field value when it enters or leaves Ariba Buyer through an integration channel. For more information, see “Accessibility and Scope of Field Values” on page 50.

Specifying a Custom Date Formatter

The Ariba File Channel uses the ariba.util.formatter.DateFormatter class to format date fields. DateFormatter in turn uses java.text.SimpleDateFormat to do formatting and parsing. To use a different date format, you must write your own custom date formatter and specify that formatter in your integration mappings extension file.

s To specify a custom date formatter:

1 Create your own custom date formatter by subclassing ariba.util.formatter.DateFormatter and overriding the getStringValue method.

For information on creating custom formatters, see the Ariba Buyer API Guide.

2 Specify your custom date formatter in config/Parameters.table using the System.Messaging.Channels.File.Formatters parameter. For example:

Formatters = {MyCustomDateFormatter = {

"ariba.channel.file.formatter.MyCustomDateFormatter";};

};

3 In your integration mappings extension file, specify your custom formatter for the date field using the integration field property. For example:

<groupField name="ExpirationDate"><properties rank="30">


<entry key="mapField" value="expirationDate"/><entry key="formatterType" value="MyCustomDateFormatter"/>

</table></property>


For more information on the integration field property, see “Using the integration Field Property” on page 75.



Adding a New Field to a Group

The following example shows how to add a new field to the AccountPull group. The AccountPull group defines the field-to-column data mapping used by the AccountPull event.

In the default configuration, the AccountPull group in includes the following fields:

• AccountDescription• UniqueName• Name

The following metadata XML extension adds an additional field called MyNewField to the AccountPull group:

<inModule name=”ariba.common.meta.Core”><inGroup name=”AccountPull”>

<inGroupClass name=ariba.core.Account”><inGroupClassVariant name=”variant”>

<groupField name=”MyNewField”/></inGroupClassVariant>

</GroupClass></inGroup>

</inModule>

Removing the Mapping for a Field

You can use the <remove> element to remove the mapping for a field by removing the field from the group.

The following metadata XML extension removes the mapping for the CardNumber field from the PCardPull group:

<inGroup name="PCardPull"><inGroupClass name=”ariba.common.core.PCard”>

<remove><groupfield name="CardNumber"/>

</remove></inGroupClass>

<inGroup>

For more information on <remove>, see the Ariba Buyer Customization Guide.


Chapter 5

Ariba cXML Channel

This chapter presents an overview of the Ariba cXML Channel. It includes the following sections:

• “Introduction to the Ariba cXML Channel” on page 83

• “Ariba cXML Channel Parameters” on page 84

• “Ariba cXML Channel Templates” on page 85

• “AW Components in Template Files” on page 89

Introduction to the Ariba cXML Channel

The Ariba cXML Channel is the recommended integration channel for exchanging data over the Internet, using commerce XML (cXML) to represent data. For example, Ariba Buyer uses the cXML channel to:

• Send purchase orders in cXML format to Ariba SN

• Retrieve and reader order status messages from Ariba SN

• Read information about sourcing destinations from AppInfo.xml

The cXML Channel uses a template to describe the layout and content of the incoming or outgoing cXML. The template can include both static formatting and dynamic content. For example, when sending a purchase order to Ariba SN, Ariba Buyer uses the cXML channel to format an approvable document (purchase order) into a cXML document. The cXML document includes both static formatting and also dynamic content read from the business object.

Most uses of the Ariba cXML Channel use standard templates, which apply in all configurations. In a few situations, such as for the order formatter, you can customize the channel by providing a custom cXML template. The cXML template describes what information to include on the cXML document, and how to format it.

Chapter 5 Ariba cXML Channel Ariba cXML Channel Parameters


Ariba cXML Channel Parameters

This section summarizes the parameters in config/Parameters.table and MessageConfiguration.table that are used to configure the Ariba cXML Channel.

Parameters in Application.Messaging

In config/Parameters.table, you specify the name of the message configuration file for the cXML channel with the parameter Application.Messaging.MessageConfigurationFiles. For example:

Application = {Messaging = {

MessageConfigurationFiles = {CXML = {

"partition" = "config/variants/variant/partitions/partition/cxml/MessageConfiguration.table";

};};

};};

The MessageConfiguration.table file in turn contains entries for each event that uses the cXML channel. For example:

SupplierNetworkPurchaseOrderPush = {Channel = {

AttachmentsEnabled = false;Decoder = { DecodeTemplate = ResponseDecode;};DurableEventIDKey = DurableEventIDKey;Encoder = { BaseEncodeTemplate = OrderRequestEncode;};Name = CXML;PersistentDocumentLoggingEnabled = true;ReliableDeliveryEnabled = true;RequestType = OrderRequest;TimeoutEnabled = false;

};TopicName = SupplierNetworkPurchaseOrderPush;Visible = false;

};

You do not often need to change any of these parameters. Situations where you do make changes are described in the appropriate guides. For example, the Ariba Buyer Procurement Guide describes how to disable attachments to cXML orders by changing the AttachmentsEnabled parameter.


Ariba cXML Channel Templates Chapter 5 Ariba cXML Channel

Parameters in System.Messaging

The parameter System.Messaging.Channels is a nested table that defines settings for each channel in your configuration. The settings for the cXML channel are in the section System.Messaging.Channels.cXML.

For a complete list of these parameters, see the Ariba Buyer Configuration Reference Guide.

Ariba cXML Channel Templates

The Ariba cXML Channel uses templates to convert Ariba Buyer objects, such as purchase orders, into cXML format before sending them out on the cXML channel. These template files, which have the extension .awl, can contain two kinds of data:

• Standard cXML elements for tagging data, such as the <BillTo> element, which appear in the message exactly as they appear in the template.

• Dynamic elements that are replaced with real-time data when the message is created, such as data from the purchase order.

You can customize the templates to add, modify, or delete the data that is included in the cXML message.

Customizing a cXML Template

For each event that uses the Ariba cXML Channel, the channel looks up the template file by concatenating a template name (defined in MessageConfiguration.table) with a resource file search path (defined in config/Parameters.table). Most configurations always use the default templates. You can customize a template by adding the config directory to the template search path, and optionally changing the template name.

Chapter 5 Ariba cXML Channel Ariba cXML Channel Templates


s To use a custom cXML template:

1 In config/Parameters.table, set System.Messaging.Channels.CXML.EncodeService to include the config directory on the search path. For example:

EncodeService = {BaseEncodeTemplate = CXMLBaseEncodeTemplate;PackageName = ariba.channel.cxml;ResourceDirectory = ( "config/cXML/template",

"ariba/cXML/template", "ariba/resource/global" );

};

2 Change the name of the template in MessageConfiguration.table, if you want. For example:

ProviderSetupRequest = {Channel = {

Decoder = { DecodeTemplate = ProviderSetupResponseDecode;};Encoder = { EncodeTemplate = MyNewTemplateName;};Name = CXML;RequestType = ProviderSetupRequest;TimeoutEnabled = false;

};TopicName = ProviderSetupRequest;Visible = false;

};

3 Modify the template by making changes to the copy in the config directory (config/cXML/template/MyNewTemplateName.awl).

Template File Format

A template file is a text file, with extension .awl. The following is a short excerpt:

<BillTo><Address addressID=

"$poFormatter.li.BillingAddress|$poFormatter.fieldValueFormatter" isoCountry="$poFormatter.li.BillingAddress.Country.UniqueName">

<Name xml:lang="en"><AWString value="$poFormatter.li.BillingAddress.Name"/>

</Name><AXConditional notEqualNullOrEmptyOrBlank=

"$poFormatter.li.BillingAddress.Country.UniqueName"><PostalAddress name="$poFormatter.defaultName">......</PostalAddress>

</AXConditional>

Ariba cXML Channel Templates Chapter 5 Ariba cXML Channel

Some portions of this example, like <BillTo>, are standard cXML elements. The finished cXML page includes those cXML elements, just as they appear in the template. The template file also includes syntax that represents dynamic content:

• The $ syntax introduces a dynamic reference, which is replaced with data read from the business object (in this case, a purchase order).

• The <AXConditional> element is an AW component, which is replaced at runtime with dynamic content. All AW Components begin with either <AW or <AX. The component illustrated here (<AXConditional>) provides functionality like that of an if statement: the content of the component appears in the output only if the conditions hold true.

• The vertical bar (|) represents a call to a formatter class.

The rest of this section describes these dynamic references in more detail.

The $ Symbol For Bindings

The $ symbol indicates a dynamic binding to a method or field path defined in Java code. Every template file has an associated Java file, from which it can invoke methods using dynamic bindings. For example:

<AWRepetition list="$streetAddress" item="$street">

In this example, the binding $streetAddress maps to an accessor method for streetAddress, which is defined in the Java file associated with this template. The first line of the template names the associated Java file. For example:



When the channel encounters a dynamic binding in a template file, it binds that value to the associated Java file, looking for an accessor method. It looks for methods in the following order:

• The method getColor

• The method color

Therefore, $streetAddress matches getStreetAddress, if it exists. If there is no such method, the template processor looks next for the method streetAddress.

Chapter 5 Ariba cXML Channel Ariba cXML Channel Templates


A binding can use dot notation to traverse the object graph. For example:

<AWString value="$root.data.TotalCost.Amount"/>

This example refers to a field path $root, which is defined in the Java class associated with the template.

Bindings cannot pass arguments. To supply arguments, you assign the value to variables, and then call methods that expect to read data from those variables. For example:

<AXAssign from="li.ShipTo.Lines" to="$fields"/><AWRepetition list="$streetAddress" item="$street">

<Street><AWString value="$street"/></Street></AWRepetition>

This example (from OrderRequestEncode.awl) stores the value of li.ShipTo.Lines in the fields variable (defined in PurchaseOrderComponent), and then extracts that data with calls to getStreetAddress, also in PurchaseOrderComponent.

AW Components

Any component that begins with <AW...> or <AX....> is interpreted as an AW component. You use AW components to express primitive logic statements such as assignment, loop, and conditionals within a template file.

For a list of the AW components that can appear in template files, and how to interpret each, see “AW Components in Template Files” on page 89.

Formatters

A vertical bar | character in a dynamic binding means that the value is passed through the designated formatter before being sent to the output stream. For example:

<OrderRequestHeader orderDate="$root.data.CreateDate|$poFormatter.fieldValueFormatter" type="$poFormatter.purchaseOrderType" orderID="$root.data.OrderID">

In this example, $poFormatter.fieldValueFormatter defines a dynamic reference to the fieldValueFormatter method in the associated Java class, which is ariba.procure.core.cXMLFormatter. When encoding the business object into cXML,


AW Components in Template Files Chapter 5 Ariba cXML Channel

the date represented by the CreateDate field is formatted using the specified formatter. For detailed information on the data types accepted by a given formatter, see the Javadoc for the associated Java class.

A formatter must refer to a subclass of ariba.util.formatter.Formatter or java.text.Format. For more information on the Formatter class, see the Ariba Buyer API Guide. For more information on the Format class, see any Java reference.

AW Components in Template Files

This section lists the AW components that you can use in Ariba cXML Channel template files. It includes two sections

• “AW Components” on page 89

• “AX Components” on page 93

AW Components

This section describes the following AW components

• “AWConditional” on page 89

• “AWElse” on page 90

• “AWMappingRepetition” on page 91

• “AWMethodInvocation” on page 92

• “AWRepetition” on page 92

• “AWString” on page 93

AWConditional

Defines a block of output that is included only if specified conditions hold. For example:

<AWConditional ifTrue="$createdValidCXMLPhoneNumber"><Phone name="work">

....</Phone>

</AWConditional>

Chapter 5 Ariba cXML Channel AW Components in Template Files


This component recognizes the following attributes:

An AWConditional element must have exactly one of these attributes. AWConditional searches for the attributes in the order listed above: if you have an ifTrue attribute, it takes precedence over all others; if you have ifTrue, it takes precedence over ifFalse, equalNull, and notEqualNull, and so on. An AWConditional with no attributes raises an exception.

AWElse

Works with AWConditional to allow for else blocks. The bindings are the same as for AWConditional. You can have an arbitrary number of AWElse blocks. The first block that evaluates to true will be the only block of the entire conditional to display.

AWElse blocks recognize the same four attributes as AWConditional:

Attribute Description

ifTrue= Displays the contents if the value of this attribute is $true.

ifFalse= Displays the contents if the value of this attribute is $false.

equalNull= Displays the contents if the value of the binding is null.

notEqualNull= Displays the contents if the value of the binding is not null.


ifTrue= Displays the contents if the value of this attribute is $true.

ifFalse= Displays the contents if the value of this attribute is $false.

equalNull= Displays the contents if the value of the binding are null.

notEqualNull= Displays the contents if the value of the binding is not null.



The attributes are optional. If no attributes are specified, AWElse always evaluates true. For example:

<AWConditional ifTrue="$weekend">It’s a weekend!<AWElse ifTrue="$holiday"/>

It’s a holiday!</AWElse">It’s a workday.

</AWConditional>

AWMappingRepetition

Formats the contents of a hash table, by iterating over the key/value pairs. You can use this component to output a field of type java.util.Hashtable or java.util.Map. For example:

<AWMappingRepetition map="$addresses" key="$name" value="$address"><Address name="$name">

<Street><AWString value="$address.street"/></Street><City><AWString value="$address.city"/></City><State><AWString value="$address.state"/></State>

</Address></AWMappingRepetition>

In this example, suppose that the root is an object of type java.util.Map with the following contents:

java.util.Map { "John Doe" -> java.lang.String[street="123 Main St",city="Atlanta",state="GA"] "Jane Doe" -> java.lang.String[street="111 Oak Blvd",city="Roanoke",state="VA"] "John Q. Public" -> java.lang.String[street="5656 North Way",city="Houston",state="TX"] }

The template would render this data as follows:

<Address name="John Doe"><Street>123 Main St</Street><City>Atlanta</City><State>GA</State>

</Address><Address name="Jane Doe">

<Street>111 Oak Blvd</Street><City>Roanoke</City>

<State>VA</State></Address><Address name="John Q. Public">

<Street>5656 North Way</Street><City>Houston</City><State>TX</State>

</Address>

This component recognizes the following required attributes:

AWMethodInvocation

Makes a method call to a method in an associated Java file. For example:

<AWMethodInvocation invoke="$initialize"/>

The class directive instantiates an instance of the named class. The <AWMethodInvocation> component invokes a method within that named class.

This component recognizes the required attribute invoke=, which is the name of a method to call.

AWRepetition

Provides a simple loop construct, which uses a list as the loop control. To specify the loop control, you specify two attributes: the list, and a variable that maintains the index into the list. For example:

<AWRepetition list="$streetAddress" item="$street"><Street><AWString value="$street"/></Street>

</AWRepetition>


map= The hash table over which to iterate.

key= Temporary variable to which the key is assigned for each iteration.

value= Temporary variable to which the value is assigned for each iteration.




AWString

Appends a string value. For example:

<AWString value="$root.data.TotalCost.Amount"/>

This component recognizes the required attribute value=, which is the string to be appended.

AX Components

This section describes the following AX components:

• “AXAssign” on page 93

• “AXConditional” on page 94

AXAssign

Assigns the value of one binding to another. For example:

<AXAssign from="$fromInfo.primary" to="$po.buyer" />

This example is approximately equivalent to the Java assignment statement po.buyer = fromInfo.primary. The to attribute usually names a field in an associated Java object. For example, the following excerpt illustrates a postal address where an element in the XML called addressName is mapped to a property in the Java object streetAddress.

<PostalAddress><Name><AWString value="$root.addressName"/></Name><AXAssign from=value="$root.addressName" to="$root.streetAddress"/>


list= Specifies the loop control, which must be a vector or an array. The repetition iterates over the contents of the list. The length of the list determines the number of iterations.

item= Stores the current item from the list.



<City><AWString value="$root.city"/></City><State><AWString value="$root.state"/></State>

</PostalAddress>


AXConditional

Defines a block of output that is included only if the conditions expressed in the attributes hold true. You use this component to hide or display information based on whether fields in the data source are empty, blank, or null. For example:

<AXConditional notEqualNullOrEmptyOrBlank="$poFormatter.li.ShipTo.Country.UniqueName">

An AXConditional element must have exactly one of the following attributes. AXConditional searches for the attributes in the order listed:


from Specifies the binding whose value will be copied.

to Specifies the binding whose value will be replaced by the value of the from binding.


equalNullOrEmpty= Displays the contents if the value of the binding is null or empty.

notEqualNullOrEmpty= Displays the contents if the value of the binding is not null or empty.

equalNullOrEmptyOrBlank= Displays the contents if the value of the binding is null, empty, or blank.

notEqualNullOrEmptyOrBlank= Displays the contents if the value of the binding is not null, empty, or blank.


Chapter 6

Ariba HTTP Channel

This chapter presents an overview of the Ariba HTTP Channel. It includes the following sections:

• “Introduction to the Ariba HTTP Channel” on page 95

• “Ariba HTTP Channel Parameters” on page 96

This chapter assumes you are already familiar with the information in Chapter 3, “Integration Events.”

Introduction to the Ariba HTTP Channel

Ariba Buyer uses the Ariba HTTP Channel to pull common data from, and send updates to, the Common Data Server (CDS).

The Ariba HTTP Channel is mostly used internally by Ariba Buyer. In most configurations, you do not need to configure the Ariba HTTP Channel. This chapter describes the few modifications you can make to the Ariba HTTP Channel.

Chapter 6 Ariba HTTP Channel Ariba HTTP Channel Parameters


Ariba HTTP Channel Parameters

This section summarizes the parameters in config/Parameters.table and MessageConfiguration.table that are used to configure the Ariba HTTP Channel.

Application and System Parameters

The Ariba HTTP Channel uses one global parameter:

Application.Messaging.MessageConfigurationFiles

This parameter specifies the path to the message configuration table file for each integration channel in your configuration. For example:

Application = {Messaging = {

MessageConfigurationFiles = {HTTP = {

"partition" = "config/variants/variant/partitions/partition/http/MessageConfiguration.table";

};};

};};

There are also system parameters that configure the Ariba HTTP Channel. For a complete list of these parameters, see the Ariba Buyer Configuration Reference Guide.

Message Configuration Parameters

In most configurations, you do not need to change the message configuration parameters for the Ariba HTTP Channel.


Chapter 7

Languages, Countries, and Locales

This chapter describes the integration events and parameters you use to define and support a multilingual configuration. A multilingual configuration is a configuration where either the data or the user interface, or both, can be in languages other than English.


• “Introduction to Locales and Resource Files” on page 97

• “Date Strings in Configuration Files” on page 100

• “Integration Events and Parameters for Locales” on page 100

• “Integration Events and Parameters for Languages” on page 104

• “Integration Events and Parameters for Countries” on page 107

• “Database Character Encodings” on page 109

• “Character Encoding Mappings” on page 110

• “Where to Find Additional Information” on page 111

For information on setting up configurations that do not use English as the default language, see Chapter 8, “Non-English Configurations.”

Note: Not all Enterprise Resource Planning (ERP) systems and versions support multilingual data. If you have a configuration that uses Oracle Financials, you must provide the translated data by pulling from a comma-separated value (CSV) file.

Introduction to Locales and Resource Files

This section explains how Ariba Buyer uses locales and resource files to create a multilingual configuration.

Chapter 7 Languages, Countries, and Locales Introduction to Locales and Resource Files


Locales

Multilingual configurations center around the idea of a locale. Each user in Ariba Buyer has an associated locale. Ariba Buyer uses that locale to decide which data to show the user. The following data differs by locale:

• Strings that appear in the user interface, such as labels and error messages

• User interface display formats, such as dates and addresses

• Images, such as command button labels

• Help files, which include text and images in the help system

• Login Hints and News bulletins on the Ariba Buyer home page

Language, Country, and Language Variant

A locale contains a unique combination of the following components:

• Language

• Country

• Language variant

For example, American English and British English are locales that share the same language but have different countries (and no variant), while Norwegian and Norwegian Bokmal are two locales that share the same language and country but have different variants.

Preferred Locales

In Ariba Buyer, each user has a preferred locale, set from the SharedUserPull integration event. When a user logs in, Ariba Buyer checks the user’s preferred locale and uses that to determine the language for the user interface. (Users can also modify their shared locale from the user interface, by modifying their user preferences.)

For information on defining users and user profile information, see “Users” on page 159.

Locale Objects

As part of setting up your configuration, you define a set of locale objects. Locales are mapped data: you define a canonical set of locales that is shared across all partitions, and then define mappings in each partition to specify which locales are visible within that partition.


Introduction to Locales and Resource Files Chapter 7 Languages, Countries, and Locales

Locale in the Login URL

Users can include a locale as a parameter to the Ariba Buyer login URL. The locale argument specifies the name of a locale. This locale is only used for the login and partition selection pages (subsequently, Ariba Buyer uses the user’s preferred locale). For example:

https://myserver:444/Buyer/Main?locale=en_US

If a user does not specify a locale in the login URL, Ariba Buyer gets the locale from the Web browser’s preference.

Resource Files

Ariba Buyer supports multilingual configurations by externalizing data into resource files, one set of files for each locale. Those localized resource files contain data that is typically translated or represented differently based on locale.

In the default configuration, Ariba Buyer provides a set of resource files that define the data for each supported locale. Some resource files reside on the Ariba Buyer server and others in your Web Components directory. The locations are as follows, with corresponding directories under the config directories:

The resource files that reside in your Web Components directory are resource files presented by your web server, such as images, help system files, and JavaScript. The resource files that reside on your Ariba Buyer server directory are resources used by the Ariba Buyer server, such as user-interface labels, logging messages, and data formatting.

For more complete information on resource files, including how to find specific resource files and how to customize resource files, see the Ariba Buyer Customization Guide.

Type of Resource File Directory

Ariba Buyer server resource files

BuyerServerRoot/ariba/resource/locale/...

Web server resource files BuyerWebComponents/ariba/resource/locale/...

Chapter 7 Languages, Countries, and Locales Date Strings in Configuration Files


Language Directories

There are language directories for languages that have several variations. If Ariba Buyer cannot find specific localization data, it “steps up” to the higher level.

For example, the directory fr_CA has French Canadian resources, and the fr directory has French resources. If there are resources in the fr_CA directory, a French-Canadian user sees those resources. If a user has a locale such as fr_CH, and there is no such directory, that user sees the fr resources instead.

Date Strings in Configuration Files

When you enter dates in configuration files, such as config/Parameters.table or a metadata XML file, Ariba Buyer parses those dates as strings and then translates those strings into dates. The valid formats for dates vary by locale. An application can define the valid formats for dates in each locale.

Ariba Buyer uses the key SystemFormats in the resource file resource/en_US/strings/resource.date.csv to parse date strings in configuration files. This key defines a list of the possible date formats for parsing a date string, separated by a comma.

Date strings in CSV files loaded through the Ariba File Channel must be in en_US format.

For more information on date strings, see the chapter on file formats in the Ariba Buyer Configuration Reference Guide.

Integration Events and Parameters for Locales

This section describes the integration events and parameters you use to configure locales.

LocaleIDPull Integration Event

You use the LocaleIDPull integration event to define your canonical set of locales. The LocaleIDPull integration event loads common data, shared among all partitions.


Integration Events and Parameters for Locales Chapter 7 Languages, Countries, and Locales

Ariba Buyer supplies an implementation of the LocaleIDPull integration event that reads locale information from a CSV file. The default configuration provides a sample CSV file called LocaleID.csv with a list of standard locales.

Most configurations use this CSV implementation, and the sample data file in the default configuration, without modification.

LocaleID Fields

The LocaleIDPull integration event creates a Java locale, which has the following fields:

In the default configuration, the LocalIDPull integration event reads data from the following file:

ariba/variants/Plain/partitions/None/data/LocaleID.csv

The following example shows sample lines from LocaleID.csv:

UniqueName,Name,Language,Country,LocaleVariantda_DK,Danish-Denmark,da,DK,""de_AT,German-Austria,de,AT,""de_DE,German-Germany,de,DE,""de_LU,German-Luxembourg,de,LU,""en_AU,English-Australia,en,AU,""

Field Description

UniqueName A unique identifier for a locale. The UniqueName fields for each locale must be distinct from one another.

Name A name that corresponds to this UniqueName. The Name is the part that will be visible to users in the user interface.

Language A language for this locale. Language must be specified as two lowercase ISO language code characters.

Country A two-character ISO country code, naming the country for this locale. Country code must be uppercase.

LocaleVariant A local variant. A variant is similar to a dialect. For example, the Nynorsk and Bokmal dialects of Norwegian are handled as locale variants.

Chapter 7 Languages, Countries, and Locales Integration Events and Parameters for Locales


Your configuration includes an associated LocaleLanguage integration event, which defines translated versions of the locale names. For information on multilingual data integrations, see “Multilingual Data” on page 21.

LocaleMapPull Integration Event

The LocaleMapPull integration event defines a mapping between locales and languages. It determines which multilingual string translation (categorized by language) will be displayed to a user (based on the user’s preferred locale).

Typically, each ERP system has its own set of names for standard locales. You set up each Ariba Buyer partition to use the names already in use by the ERP system in that partition. The LocaleMapPull loads partitioned data.

LocaleMap Fields

In the default Ariba Buyer configuration, the LocaleMapPull integration event reads from the following file:

config/variants/variant/partitions/partition/data/LocaleMap.csv

The fields in LocaleMap.csv are as follows:

Field Description

Key The canonical locale name, a Java locale code.

Value The canonical language name, which must match a UniqueName column in the Language.csv file of the None partition. Some examples of locales are ja_JP (Japanese), nl (Dutch), pt_BR (Brazilian Portuguese), sv (Swedish), and zh_CN (Simplified Chinese).

Preferred A Boolean that defines the reverse mapping. For the LocaleMapPull integration event, you can omit this field, because Ariba Buyer never pushes locales back into the ERP system.



Integration Events and Parameters for Locales Chapter 7 Languages, Countries, and Locales

The following sample shows lines from a typical version of LocaleMap.csv:

"Key","Value","Preferred","Comment""da_DK","Danish",,"de_AT","German",,"de_CH","German",,"de_DE","German",,"de_LU","German",,

Parameters for Default Locales

If a user’s default locale is not set, Ariba Buyer looks first for the partition’s default locale, and then for the system’s default locale.

You set default locale values with the following values in config/Parameters.table:

Application.Base.Data.DefaultOrganicUserLocale

Specifies the value used for new users created with organic growth. For more information, see “Organic User Growth” on page 170.

System.Base.DefaultLocale Specifies the system-wide default locale, which is used as the last resort if the user has no default locale, and there is no partition-level locale defined.

Chapter 7 Languages, Countries, and Locales Integration Events and Parameters for Languages


Integration Events and Parameters for Languages

This section describes the integration events and parameters you use to configure languages.

LanguagePull Integration Event

Ariba Buyer defines languages as mapped data, with a canonical set of languages shared among all partitions, and a set of mappings defined in each partition. You use the LanguagePull integration event to define a canonical set of languages. The LanguagePull integration event loads common data.

Note: You cannot delete languages from a partition.

Ariba Buyer supplies an implementation of the LanguagePull integration event that reads a list of languages from a CSV file. Most configurations use this CSV implementation, and the data file from the default configuration, without modification.

Language Fields

In the default configuration, the LanguagePull integration event reads from the following file:

config/variants/Plain/partitions/None/data/Language.csv

The fields in Language.csv are as follows:

Field Description

UniqueName A name for the language. The UniqueName will be visible to users in the user interface.

ID A unique identifier for this language. The value must be an integer.


Integration Events and Parameters for Languages Chapter 7 Languages, Countries, and Locales

The following example shows the format of a typical Language.csv file:

"UniqueName", "ID""English", "1"

Your configuration also has an associated LanguageLanguagePull integration, which defines the language names in other languages. For information on multilingual data integrations, see “Multilingual Data” on page 21.

LanguageMapPull Integration Event

The LanguageMapPull integration event defines a mapping between language names from Language.csv and the names for those languages in a partition. The mapping serves both as a way to filter the set of canonical languages and as a way to set up different names in different partitions.

Typically, each ERP system has its own set of names for standard languages, and you set up each Ariba Buyer partition to use the names already in use by the ERP system in that partition. The LanguageMapPull integration event loads partitioned data.

Your mapping serves to:

• Translate from the canonical language names to the names used in your existing ERP system

• Filter the languages that are available in a partition

If a canonical value does not appear in the mapping, it is not visible in the partition.

Note: Every configuration must include English as a possible language, even configurations that use another language by default.

Chapter 7 Languages, Countries, and Locales Integration Events and Parameters for Languages


LanguageMap Fields

In the default configuration the LanguageMapPull integration event reads from the following file:

config/variants/variant/partitions/partition/data/LanguageMap.csv

The fields in LanguageMap.csv are as follows:

The following are sample lines from a typical version of LanguageMap.csv:

"Key","Value","Preferred","Comment""DUT","Dutch","","Dutch""ENG","English","","English""FRA","French","","French""GER","German","","German""JPN","Japanese","","Japanese"

Parameters for Default Languages

You must set the parameter Application.Base.Data.DefaultLanguage in the config/Parameters.table file to name the default language for each partition. The DefaultLanguage parameter determines which language’s translations are stored in the PrimaryString field for MLStrings (Multi-Lingual Strings). All other translations go into the translations vector. Because performance is better for the language set as the DefaultLanguage, set the language most widely used in your Buyer partition to be the default language.

Field Description

Key The name for the language in this partition.

Value The canonical language used with Key. It must match the UniqueName column in the Language.csv file.

Preferred A Boolean used to define the reverse mapping.

Comment An optional comment.


Integration Events and Parameters for Countries Chapter 7 Languages, Countries, and Locales

For example:

DefaultLanguage="English";

Changes to this parameter require database initialization (initdb -loaddb and initdb -loaddblanguage). The only way to change the default language for a partition after it has been created is to use initdb.

Integration Events and Parameters for Countries

This section describes the integration events and parameters you use to configure countries. Country objects are shared by all Ariba Spend Management applications.

CountryPull Integration Event

Ariba Buyer defines countries as mapped data, with a shared set of canonical country definitions, and a set of mappings defined in each partition.

The CountryPull integration event defines a canonical list of countries and maps those countries to locales and currencies. Ariba Buyer uses this mapping to choose the locale for supplier locations, based on the country. For example, if a supplier location has an address that specifies a location in the country of Belgium, Ariba Buyer chooses a preferred locale for that supplier by looking up the locale associated with the country of Belgium.

Ariba Buyer supplies one implementation of the CountryPull integration event, which reads from a CSV file. Most configurations use this implementation, and the data file from the default configuration, without modification.

Chapter 7 Languages, Countries, and Locales Integration Events and Parameters for Countries


Country Fields

In the default configuration, the CountryPull integration event reads a list of countries from the following file:

ariba/variants/Plain/partitions/None/data/Country.csv

The fields in Country.csv are as follows:

The following example shows sample lines from Country.csv:

UniqueName,Name,LocaleID,DefaultCurrencyUS,United States,en_US,USDGB,United Kingdom,en_GB,GBPAR,Argentina,es_AR,ARS

Your configuration also has an associated CountryLanguagePull integration event, which defines the canonical country names in other languages. For information on multilingual data integrations, see “Multilingual Data” on page 21.

CountryMapPull Integration Event

The CountryMapPull integration event maps the canonical set of country IDs into the names you want to use in a given partition. The CountryMapPull integration event loads partitioned data.

Field Description

UniqueName A two-character ISO country code specified in uppercase characters. This is the canonical value.

Name A name that corresponds to this UniqueName. This is the name that users see in the Ariba Buyer user interface.

LocaleID The unique name of a locale, which must match a locale defined by your LocaleIDPull integration event.

DefaultCurrency The unique name of a currency, used as the default for this country. The value must match a currency name as defined by your CurrencyPull integration event.


Database Character Encodings Chapter 7 Languages, Countries, and Locales

The CountryMapPull integration event can both filter the canonical set of country names and rename them. You must set up mappings for each canonical value that you want to use. If your mapping integration event doesn’t mention one of the canonical values, that canonical value won’t be available.

CountryMap Fields

In the default Ariba Buyer configuration, the CountryMapPull integration event reads from the following file:

config/variants/variant/partitions/partition/data/CountryMap.csv

The fields in CountryMap.csv are as follows:

The following example shows sample lines from a typical version of CountryMap.csv:

Key,Value,Preferred,CommentUSA,US,,United StatesGBR,GB,,United KingdomARG,AR,,ArgentinaAUT,AT,,Austria

Database Character Encodings

If you configure multiple languages in a single instance, it’s a good idea to specify Unicode encoding for the Ariba Buyer database. If you are using Simplified Chinese or Japanese, you must specify a Unicode encoding for the database.

Field Description

Key The name of the incoming (ERP system-specific) country name.

Value The canonical country name. It must match a UniqueName in the Country.csv file.

Preferred A Boolean used to define the reverse mapping.


Chapter 7 Languages, Countries, and Locales Character Encoding Mappings


For more information, see “Database Character Encodings” on page 113.

Character Encoding Mappings

The character encodings used by the Ariba Buyer user interface, HTML attachments, and email notification messages are specified for each locale in the following file:

BuyerServerRoot/ariba/encoding/EncodingMap.csv

The first line of the following table shows the mappings specified in the default configuration:

The defaultLocale character encodings (the ones on the first line) are used for all locales, except for those explicitly listed in EncodingMap.csv.

Customizing Encoding Mappings

You can override the character encodings in the default configuration by creating your own EncodingMap.csv file and storing it in the config directory as follows:

Locale User Interface HTML Attachments Email Notifications

defaultLocale UTF-8 UTF-8 UTF-8

Note: The defaultLocale character encodings are used for all locales, except for those explicitly listed in EncodingMap.csv. The following examples are possible values for locale in EncodingMap.csv:

ja UTF-8 Shift_JIS ISO-2022-JP

ja_jp UTF-8 Shift_JIS ISO-2022-JP

ko UTF-8 KS_C_5601-1987 KS_C_5601-1987

ko_kr UTF-8 KS_C_5601-1987 KS_C_5601-1987

zh_cn UTF-8 GB2312 GB2312

zh_tw UTF-8 Big5 Big5


Where to Find Additional Information Chapter 7 Languages, Countries, and Locales

config/EncodingMap.csv

You never modify the EncodingMap.csv file in the ariba/encoding directory.

If you specify an invalid character encoding format in your EncodingMap.csv file, Ariba Buyer will not start and you will see the following message in the main log file:

(util:warning:2811): Assert failed: UI encoding for locale locale is set to encoding which is invalid.

Where to Find Additional Information

Use the following table to locate multilingual and non-English configuration information in other documents in the Ariba Buyer documentation set.

For information on See this document

• DBMS encodings

• Global instance, Japanese-language, or Simplified Chinese-language configurations

• Localized online help

Ariba Buyer Installation Guide

• Reloading data from LoadDBLanguages.txt

• Tablespace sizes for UTF-8 encoding

Ariba Buyer Database Configuration Guide

Constructing localized logging messages in custom Java code

Ariba Buyer API Guide

Localizing text in approval requests Ariba Buyer Approval Rules Guide

• Catalog hierarchy in multilingual configurations

• Linguistic API for parsing search terms

Ariba Buyer Catalog Guide

Specifying language resource locations (non-English) for ERP integrations

Ariba Buyer TIBCO Configuration Guide

Chapter 7 Languages, Countries, and Locales Where to Find Additional Information


ERP-specific multilingual considerations Ariba Buyer Oracle Financials Integration Guide

Ariba Buyer PeopleSoft Integration Guide

Ariba Buyer SAP Integration Guide

Language changes in a particular Ariba Buyer release

Connect web site (http://connect.ariba.com)

For information on (Continued) See this document


Chapter 8

Non-English Configurations

This chapter summarizes the steps involved in setting up Ariba Buyer for configurations that do not use English as the primary language or that combine Asian and Western European languages (global instance). It includes the following sections:

• “Database Character Encodings” on page 113

• “Data File Encoding” on page 115

• “Parameters in config/Parameters.table” on page 115

• “Considerations for Asian Language Configurations” on page 117

• “Where to Find Additional Information” on page 119

Before you begin, check the Ariba Technical Support website at http://connect.ariba.com to make sure that your configuration is certified.

For information on known limitations with any configuration, check the Ariba Buyer Release Guide.

Database Character Encodings

With Version 8.2, Ariba Buyer provides global instance support. Out of the box, all defaults have been changed to Unicode and have been tested to ensure that Asian and European languages work together. You can have a global instance that supports Simplified Chinese, Japanese, and European users. See the Ariba Buyer Installation Guide for information on the software requirements for a global instance.

Note: For information on converting your databases and migrating existing instances to a global instance, see the information on Unicode database conversion on Connect (http://connect.ariba.com).

To use Ariba Buyer in a non-English configuration, your Ariba Buyer database and channel repository database must specify appropriate character encodings.You must verify all database character encodings with your database administrator.

Chapter 8 Non-English Configurations Database Character Encodings


s To specify character encodings:

1 In config/Parameters.table, set the System.Database.AribaDBCharset parameter.

For example, if you are using a global instance configuration on a Microsoft SQL Server database, you would set this parameter as follows:

AribaDBCharset = UCS2;

For a global instance configuration on an IBM DB2 UDB or Oracle database:

AribaDBCharset = UTF8;

For a European configuration, make sure that the charset you choose supports Unicode Euro characters.

2 For your Ariba Buyer database, set the charset for that database as follows:

3 If you are using TIBCO as your integration channel, for your channel repository database, set the charset for that database as follows:

4 If you are using TIBCO as your integration channel, set the parameter System.Messaging.Channels.Tibco.RVEncoding in config/Parameters.table to specify the encoding used on the TIBCO Rendezvous bus.

Database Type Charset

Oracle UTF-8

Microsoft SQL Server Use default setting (see the Ariba Buyer Database Configuration Guide for more information)

IBM DB2 UDB UTF-8

Database Type Charset

Oracle UTF-8

Microsoft SQL Server Use default setting (see the Ariba Buyer Database Configuration Guide and the Ariba Buyer TIBCO Configuration Guide for more information)

IBM DB2 UDB UTF-8


Data File Encoding Chapter 8 Non-English Configurations

For example:

RVEncoding = "UTF-8“

Note: For a global instance, you must set the Tibco.RVEncoding parameter to UTF-8.

Data File Encoding

You must modify the comma-separated value (CSV) files used to load data to indicate that the character set used in the data.

For a list of the valid character encoding formats, see the appendix on file formats in the Ariba Buyer Configuration Reference Guide.

s To specify character sets for data:

• Make sure that the first line of all CSV files specify the character encoding used in that file.

For example, CSV files used in Japanese configurations might specify Shift_JIS as the character encoding. EUC_JP is also a valid encoding for Japanese CSV files.

Parameters in config/Parameters.table

To configure Ariba Buyer for use in a multilingual configuration, you should verify and possibly change the following parameters:

s To set parameters:

1 Set Application.Base.Data.DefaultCurrency and System.Base.Data.BaseCurrency to the preferred or default currency for the partition.

For example:

DefaultCurrency= JPY; BaseCurrency=JPY;

The value you specify must be a valid currency name in your configuration, as defined by your CurrencyPull integration event.

2 Set Application.Base.Data.DefaultLanguage to specify the primary or most commonly accessed language for data display.

Chapter 8 Non-English Configurations Parameters in config/Parameters.table


For example:

DefaultLanguage= Japanese;

This specifies the language used as a fallback when no translated string that maps to the user’s locale is available. The empty string appears when no translated string is available for either locale language or default language. For example, if user locale = fr_FR (language French) and DefaultLanguage is German, the empty string appears if there is no German value and no French value. (If you set this parameter to something other than English, make sure you provide a value for every string in your translations directory for that language, even if the value is just the English value.)

This parameter can potentially affect performance: when multiple translations are loaded for data loaded through integration events (for example, English and French strings for the names of roles), the searching and sorting performance is better for the default language.

Changes to this parameter require database initialization (initdb -loaddb and initdb -loaddblanguage). The only way to change the default language for a partition after it has been created is to use initdb.

3 Set Application.Base.Data.DefaultOrganicUserLocale, System.Base.DefaultLocale, and Partition.partition_name.Application.Base.Data.DefaultLocale to an appropriate locale.

For example, in a Japanese configuration:

DefaultOrganicUserLocale = ja_JP;

The DefaultLocale parameter determines what resources are used if resources in a user’s preferred locale are not available.

4 Verify that System.Logging.Encoding is set to UTF-8. (This is the default value). This setting ensures that log files are generated in UTF-8.

5 Set Application.Reports.CSVReportsCharset to specify the character set for CSV reports. For example:

CSVReportsCharset= UTF-8;


Considerations for Asian Language Configurations Chapter 8 Non-English Configurations

Typical values are UTF-8 and UCS2 (both are appropriate for a global instance):

• UTF-8 is identical to US-ASCII for ASCII text. However, Excel cannot read the generated file if it has any non-ASCII text (accented or Asian).

• UCS2 is different from ASCII and Latin-1, but can be read by Excel. If you choose this character set, you must use Excel’s Text Import wizard to tell Excel to use comma delimiters.

6 If you are integrating with SAP, set the parameter Partitions.sap_partition.Application.Messaging.Channels.Tibco.GlobalProcesses.SAPAdapterLocale to pass an appropriate locale to SAP. The value is a nested table, listing the operating system where you run the SAP adapter and a valid encoding to be passed to SAP’s setlocale command.

For example:

SAPAdapterLocale = { HPUX = ibm-943 }

For complete details on the operating system codes and locale values you can specify for this parameter, see the Ariba Buyer Configuration Reference Guide.

Considerations for Asian Language Configurations

This section summarizes the configuration specific to Asian language configurations.

For non-ASCII language searches, the default catalog search algorithm in Ariba Buyer uses lexing that breaks words at spaces. For information on the language lexer, see the Ariba Buyer Catalog Guide.

Requirements for Asian Language Support

This section describes requirements for Asian language support. Japanese and Simplified Chinese are the currently supported languages that do not use the Latin-1 character set.

Chapter 8 Non-English Configurations Considerations for Asian Language Configurations


UNIX Account Requirements

For new installations on UNIX systems, Ariba Buyer requires that you specify UTF-8 locales to support the global instance. Native language environments are no longer required. The following table shows the appropriate Asian language character encoding for each platform:

Parameter Settings

In config/Parameters.table, you must set AribaDBCharset to the following values for the specified databases. Japanese language installations will encounter problems if these parameters are not specified correctly:

• Microsoft SQL Server: UCS2

• Oracle: UTF8

• IBM DB2: UTF8

The System.Integration.Channels.Tibco.RVEncoding parameter in config/Parameters.table must always be UTF-8 for any Japanese or global instance configuration of Ariba Buyer.

Platform Encoding

HP-UX ja_JP.utf8 (Japanese)zh_CN.utf8 (Simplified Chinese)

IBM AIX JA_JP.UTF-8 (Japanese)ZH_CN.UTF-8 (Simplified Chinese)

Solaris ja_JP.UTF-8 (Japanese)zh_CN.UTF-8 (Simplified Chinese)


Where to Find Additional Information Chapter 8 Non-English Configurations

Where to Find Additional Information

Use the following table to locate multilingual and non-English configuration information in other documents in the Ariba Buyer documentation set.

For information on See this document

• DBMS encodings

• Global instance, Japanese-language, or Simplified Chinese-language configurations

• Localized online help

Ariba Buyer Installation Guide

• Reloading data from LoadDBLanguages.txt

• Tablespace sizes for UTF-8 encoding

Ariba Buyer Database Configuration Guide

Localizing logging messages in custom Java code

Ariba Buyer API Guide

Catalog hierarchy in multilingual configurations

Ariba Buyer Catalog Guide

Specifying language resource locations (non-English) for ERP integrations

Ariba Buyer TIBCO Configuration Guide

ERP-specific multilingual considerations Ariba Buyer Oracle Financials Integration Guide

Ariba Buyer PeopleSoft Integration Guide

Ariba Buyer SAP Integration Guide

Language changes in any Ariba Buyer release Connect web site (http://connect.ariba.com)

Chapter 8 Non-English Configurations Where to Find Additional Information



Chapter 9

Currencies

This chapter describes how to set up the integration events and parameters for currency information. It includes the following sections:

• “Introduction to Currencies” on page 121

• “Currency Conversion” on page 124

• “Currency Considerations for ERP Systems” on page 129

• “Integration Events for Currency Information” on page 131

• “Choosing a Currency” on page 140

Before you read this chapter, you must be familiar with mapped data, and the use of a canonical set of data with different names in different partitions. For more information, see “Mapped Data” on page 25.

Introduction to Currencies

To set up your configuration for currencies, you define currency data and set parameters that control which currency is chosen. This section describes the currency-related concepts in Ariba Buyer.

Defining Currency Data

You use integration events to define the following data related to currency:

• Available currencies

• Currency groups

• Currency conversion rates

Chapter 9 Currencies Introduction to Currencies


Available Currencies

Every Ariba Buyer configuration has a set of available currencies, which are defined by an integration event. Every reference to a currency, such as from a line item or an approvable document, must refer to one of these available currencies.

Depending on the external systems with which you communicate, you must also ensure that outgoing currency values are valid on the destination system. For example, if you integrate with an ERP system, you must ensure that you push currency values that are valid on that ERP.

For information on setting up the available currencies in your configuration, see “CurrencyPull Integration Event” on page 131

Currency Groups

If a currency is from a European Monetary Union (EMU) country, Ariba Buyer shows a tooltip that shows the value both in the original EMU currency and in euros. The EMU currencies are in an Ariba Buyer currency group, which is a collection of related currencies.

You set up currency groups with the CurrencyGroupPull integration event. For more information, see “Currency Groups” on page 122.

Currency Conversion Rates

When a requisition is submitted, approved, and converted to a purchase order, the order is typically sent to an underlying Enterprise Resource Planning (ERP) system. Depending on your ERP configuration, Ariba Buyer might send the original currency to the ERP system, or perform the currency conversion and then send the converted amount to the ERP system.

Your configuration must define a set of currency conversion rates, for times when Ariba Buyer does the conversions. You set up these rates with the CurrencyConversionRatePull integration event.

For performance reasons, Ariba Buyer caches currency conversion rates in memory. The parameter System.Performance.CurrencyRateCacheSize specifies the number of currency conversion rates maintained in the cache. Most configurations must use the default value for this parameter, without modification.


Introduction to Currencies Chapter 9 Currencies

For more information, see “CurrencyConversionRatePull Integration Event” on page 135.

Choosing a Currency

Ariba Buyer uses the following concept when choosing a currency:

• Base and reporting currencies

• Preferred and default user currencies

• Transaction currency

Preferred and Default User Currencies

Every Ariba Buyer user has a preferred currency. Users specify their preferred currency through the User Preferences screens in the Ariba Buyer user interface.

When a user creates a request in Ariba Buyer, Ariba Buyer uses that user’s preferred currency as the default currency for the requisition (or other approvable document). If the user’s preferred currency is not set, Ariba Buyer uses the default currency for that partition, as specified by the parameter Application.Base.Data.DefaultCurrency. For more information, see “Choosing a Currency” on page 140.

Note: There is also a default currency associated with each country. This information is used only for calculating VAT information, and is not used elsewhere in Ariba Buyer. For more information on tax and VAT, see the Ariba Travel & Expense Guide.

Base and Reporting Currencies

When an administrator runs a report, Ariba Buyer converts the currency amounts on requisitions to a system-wide base currency. If your company does dual-currency reporting, you might also have reports in a secondary reporting currency.

You define the system-wide base currency with the parameter System.Base.Data.BaseCurrency. You can optionally define a reporting currency with the parameter System.Base.Data.ReportingCurrency.

When the reporting currency is an EMU currency, you can configure your system to show reports in both the base currency and the euro by setting the parameter Application.Reports.EnableEuroDualCurrencyDisplay to true.

Chapter 9 Currencies Currency Conversion


For complete information on currencies in reporting, see the Ariba Buyer Configuration Guide.

Transaction Currency

The transaction currency is the currency used for a specific transaction, such as a specific expense item. When users create expense reports in Ariba Buyer, they can enter a transaction currency that is different from their preferred user currency.

For example, a user who works in the United States would probably have a preferred currency of US dollars (USD), but might specify a different transaction currency when doing business with companies from the European Union (EU).

Currency Conversion

A conversion rate converts from one currency to another. In general, Ariba Buyer is structured so that currency conversion is handled on the ERP system whenever possible, but there are some situations where Ariba Buyer does the conversion itself. In those situations, Ariba Buyer is careful to maintain the highest possible precision in conversions.

This section describes other considerations and features related to currency conversion rates.


Currency Conversion Chapter 9 Currencies

Conversion Rates

When you set up your configuration, you must ensure that Ariba Buyer has a conversion rate available for converting any given two currencies. Ariba Buyer is able to perform three types of currency conversions as shown in the following table:

Euro Restrictions and Conversion Rates

The EU, which consists of 15 European countries with several new ones pending, adopted the euro as the currency for the EMU initiative. Currently, 12 EU countries have adopted the euro to replace their national (EMU) currencies.

Currency conversions involving the euro currency include legal restrictions. The legal restrictions for euro currencies were effective on January 1, 1999. For currency conversions before that date, there are no legal restrictions—any conversion rate from one currency to another is valid. As of January 1, 2002, only the euro can be used.

Ariba Buyer conforms to the following euro-conversion rules set by the EU:

• Fixed exchange rates are carried to six-significant-digits (obtained by counting from the left-most nonzero digit and ignoring the decimal place).

• Intermediate amounts are carried to at least three decimal points and the rounding error must be less than one cent.

• Triangulation is enforced.

Conversion Type Formula

Direct If there is a rate for converting from A to B, the formula for converting A to B is:

currencyA * rate = currencyB

Reciprocal If there is a rate for converting from B to A, the formula for converting A to B is:

currencyA * 1/rate = currencyB

Triangulation with the system base currency

If rate1 is the rate between currencyA and the base currency, and rate2 is the rate between the base currency and currrencyB, the formula is:

currencyA * rate1 * rate2 = currencyB



Each EMU currency has a fixed conversion rate set by the EU.

UpdateMoneyFields Trigger Action

Ariba Buyer uses the UpdateMoneyFields trigger action to maintain currency conversion rates on requisitions. When the total cost of a requisition changes, this trigger checks to see if the currency conversion rates on that requisition need to be updated.

In the default Ariba Buyer configuration, the UpdateMoneyFields trigger action does the following:

• Considers the LineItem.Amount, LineItem.Description.Price, and LineItem.Accountings.SplitAccountings.Amount fields on all requisitions, purchase orders, and PCR approvables whenever the TotalCost field changes.

• Reads the parameter System.Performance.MoneyUpdateHours from config/Parameters.table to determine which fields have been updated “recently enough.” If the conversion date of a field is within the time specified by MoneyUpdateHours from the current time, that field is not updated.

• Does not convert items that are already in the base currency (as specified by the parameter System.Base.Data.BaseCurrency), unless you have an explicit reporting currency (as defined by the parameter System.Base.Data.ReportingCurrency). For example, if all items on a requisition are in the base currency, and the reporting currency is null, the UpdateMoneyFields action does not update any of the fields. If the items are in the base currency, but there is a separate reporting currency, the UpdateMoneyFields action does update the fields.

The UpdateMoneyFields trigger action is not used on expense reports, because the items on an expense report have an associated date, and the conversion rate must be the one from that date.

This trigger action is also available for you to use in extensions. For example, if you have any company eForms that require this behavior, you can use the UpdateMoneyFields trigger action on those forms.

For more information on the UpdateMoneyFields trigger action, see the Ariba Buyer Customization Guide.


Currency Conversion Chapter 9 Currencies

ARFHintTotalCost Field Controller

Ariba Buyer determines the currency conversion rate for a particular requisition line item based on the most recent modified date for that requisition line item. It does not store currency conversion rates on each individual requisition line item. For example, consider the following scenario:

• A user creates a requisition with two line items, Item 1 and Item 2.

• The user creates Item 1 on the May 1, 2002. Item 1 uses the currency conversion rate for May 1, 2002.

• On May 2, 2002, the currency conversion rate in the system is changed.

• On the May 4, 2002, the user creates Item 2. Item 2 uses the most recent currency conversion rate, which is the rate as of May 2, 2002.

• Ariba Buyer computes the requisition total using the May 1, 2002 rate for Item 1 and the May 2, 2002 rate for Item 2.

• On May 6, 2002, the user clicks Toggle Currency to display all currencies in their default currency. Ariba Buyer uses the currency conversion rate for May 6, 2002, which again might have changed.

The result of this scenario is that the sum of the requisition line items differs from the total cost shown for the requisition.

If you would like to explain this behavior to users in the user interface, you can use the field controller ariba.htmlui.approvable.fields.ARFHintTotalCost to show a tooltip on the requisition Total Cost field. The ARFHintTotalCost field controller is not implemented in the default configuration.

s To use the ARFHintTotalCost field controller:

1 Define a metadata XML extension file that specifies the ARFHintTotalCost field controller on the TotalCost field. For example:

<inClass name=”ariba.procure.core.Requisition”><inField name=”TotalCost”>

<properties controller=”ariba.htmlui.approvable.fields.ARFHintTotalCost”/>

</inField></inClass>

2 In BuyerServerRoot/ariba/resource/locale/strings/ariba.html.alt.csv, search for ApprovableTotalCost and enter text for the tooltip. For example, the tooltip text might read as follows:



“Because line item amounts are converted based on the current system conversion rate, the Total Cost might differ from the sum of the requisition line items.”

For complete information on working with metadata XML, see the Ariba Buyer Customization Guide.

Historical Currency Conversion

Occasionally, Ariba Buyer must determine the conversion rate for a particular date in the past. For example, consider the following scenario:

• The currency conversion rate from JPY to USD changed on January 1, 2001.

• On January 2, 2001, a user with a currency of JPY submits an expense report that contains a USD line item with a transaction date of December 31, 2000.

To determine the conversion rate for the historical line item, Ariba Buyer does the following:

• First, Ariba Buyer looks for a direct historical rate. The direct historical rate is the direct conversion rate that was in use on or before the line item transaction date.

• If it cannot find a direct historical rate, Ariba Buyer looks for a reciprocal historical rate. The reciprocal historical rate is the reciprocal conversion rate that was in use on or before the line item transaction date.

• If it cannot find a reciprocal historical rate, Ariba Buyer looks for a triangulated historical rate. The triangulated historical rate is the triangulated conversion rate that was in use on or before the line item transaction date.

• If it cannot find a triangulated historical rate, Ariba Buyer looks for the most recent direct conversion rate.

• If a direct rate is not available, Ariba Buyer looks for the most recent reciprocal conversion rate.

• Finally, if a reciprocal conversion rate is not available, Ariba Buyer looks for the most recent triangulated conversion rate.


Currency Considerations for ERP Systems Chapter 9 Currencies

Currency Considerations for ERP Systems

This section describes currency considerations specific to Oracle, PeopleSoft, and SAP systems.

Oracle Currency Support

In Oracle configurations, the Oracle ERP system has a default currency associated with each operating unit. When you are integrating with an Oracle configuration, you must make sure that the currency information coming from Ariba Buyer is acceptable to that operating unit.

The currency information that Ariba Buyer pushes to Oracle Financials depends on whether there is a currency conversion involved, and whether that conversion is a legal conversion as defined by the rules for euro conversions.

Line Item Currency Matches Oracle Operating Unit Currency

If the line item currency is the same as the Oracle operating unit currency, Ariba Buyer pushes only the currency unit price for purchase orders.

Oracle Financials assumes that an incoming price with no associated currency information is in the operating unit currency.

Line Item Currency and Operating Unit Currency Are Different

If the line item currency and the Oracle operating unit currency are different, currency information depends on whether there is a legal direct conversion between the two, or the conversion involves euro conversions.

Legal Direct Conversion

If the line item currency and the operating unit currency are different, and there is a legal direct conversion between the two, Ariba Buyer pushes the currency unit price and an appropriate conversion rate for converting from the line item currency into the operating unit currency.

For purchase orders, Ariba Buyer pushes the unit price in the line item’s currency code and the conversion rate from the currency code to the operating unit currency.

Chapter 9 Currencies Currency Considerations for ERP Systems


Euro Conversion

If the Ariba Buyer line item currency and the operating unit currency are different, and the conversion from Ariba Buyer currency to operating unit currency involves euro conversions, Ariba Buyer does the currency conversion and pushes the converted value in the operating unit currency.

Ariba Buyer performs the currency conversion according to the fixed rates for EMU currency conversions. For more information, see the Ariba Buyer Euro Conversion Guide.

PeopleSoft Currency Support

For PeopleSoft configurations, multi-currency support depends on the kind of configuration you are using to integrate with PeopleSoft.

Message Agent

If you integrate through the Message Agent, you cannot push line items on purchase orders in a currency that differs from that of the supplier in PeopleSoft. The currencies of the related business unit, supplier location, general ledger, and purchase order must all be the same.

Important: It is your responsibility to ensure that your catalog items and ad hoc orders appear in the correct currency.

SAP Currency Support

In the case of SAP, SAP handles all currency conversions for Ariba Buyer purchase orders. Ariba Buyer pushes purchase orders in a given currency, and SAP sets the conversion rate, if any, between the line items and the currency of the company code and vendor purchasing organization.

Ariba Buyer pushes line items in the currency of the catalog item. It is your responsibility to maintain correct currencies for catalog line items within Ariba Buyer.


Integration Events for Currency Information Chapter 9 Currencies

Note: Because Ariba Buyer sets currency at the purchase order header level for SAP, all line items on a requisition must be in the same currency. If a given Ariba Buyer requisition contains more than one currency, Ariba Buyer splits the requisition into different purchase orders before pushing the purchase orders to SAP.

Integration Events for Currency Information

Ariba Buyer handles currencies as mapped data. You load your list of currencies with two integration events: one that defines a canonical set of currencies, shared among all partitions, and another that defines the names for those currencies in a partition.

This section describes those two integration events, as well as the CurrencyRatePull integration event and the CurrencyGroupPull integration event.

CurrencyPull Integration Event

You use the CurrencyPull integration event to define a set of standard currencies. Ariba Buyer supplies one sample implementation of this integration event, which reads from a CSV file called Currency.csv. In the default configuration, this file defines ISO 4217 currency codes.

Most configurations use this CSV implementation, and the data file in the default configuration, without modification.

Note: When Ariba Supplier Network (Ariba SN) processes a purchase order, it checks the currency code to ensure that it is a valid three-letter ISO 4217 currency code. If you integrate with Ariba SN, you must use ISO 4217 currency codes.

If you choose to change the set of canonical currencies, you must modify the MessageConfiguration.table file entry for this integration event so that it looks also in the config directory under BuyerServerRoot. For more information on specifying data sources, see “Multilingual Data” on page 21.

Chapter 9 Currencies Integration Events for Currency Information


Currency Fields

In the default Ariba Buyer configuration, the CurrencyPull integration event reads only from the following file:

ariba/variants/Plain/partitions/None/data/Currency.csv

The CurrencyPull integration event does not also read from the config directory.

The fields in Currency.csv are as follows:

Field Description

UniqueName An unique identifier for this currency.

Name A name for this currency, such as “US Dollars.” This is the name that users see.

PrecisionString The number of decimal places that will be used in displaying amounts in this currency. For example, for U.S. Dollars the precision will typically be 2, to show “$12.99.”

Prefix The prefix to identify this currency. For example, the prefix for U.S. Dollars is $. Some currencies have prefixes; others do not.

Suffix The suffix to identify this currency, such as FF. If the suffix is not specified, the default is to use the currency code as a suffix.

Group The name of a currency group. This name must match the UniqueName of a currency group defined in your CurrencyGroupPull integration event. For more information, see “Currency Groups” on page 122.



The following example shows a Currency.csv file entry:

ATS,Austrian Schilling,2,,ATS,EMU,Fri Jan 01 00:00:00 1999,Tue Jan 01 00:00:00 2002

Your configuration also has an associated CurrencyLanguagePull integration event. For more information, see “Multilingual Data” on page 21.

CurrencyMapPull Integration Event

You use the CurrencyMapPull integration event to define mappings between canonical currencies and the currency names in a partition.

The CurrencyMapPull integration event loads data into a partition. If you have several partitions, each loading data from a different ERP system, you probably need an instance of the CurrencyMapPull integration event in each partition.

GroupEntryDate The date your country entered the EMU, if applicable. Must be in the following format: EEE MMM d k:m:s yyyy. For example:

Fri Jan 01 00:00:00 1999

Set the date to an empty string if your country is not part of the EMU.

EndDate The date to expire the use of the currency, if applicable. Must be in the following format: EEE MMM d k:m:s yyyy. For example:

Tue Jan 01 00:00:00 2002

Set the date to an empty string if the currency will never expire.

Field (Continued) Description

UniqueName An unique identifier for this currency.



CurrencyMap Fields

Ariba Buyer supplies several instances of the CurrencyMapPull integration event, which read the mapping from a CSV file. In a typical configuration, you store the map in the following file:

config/variants/variant/partitions/partition/data/CurrencyMap.csv

The fields in CurrencyMap.csv are as follows:

Each (Key, Value) pairing represents a mapping from an ERP system-specific currency to an Ariba Buyer canonical currency.

The following example shows sample lines from a typical version of CurrencyMap.csv:

"Key","Value","Preferred","Comment"ADP,ADP,true,Andorrian PesetaANP,ADP,false,Andorrian PesetaAED,AED,,UAE DirhamAFA,AFA,,AfghaniALL,ALL,,Lek...

Field Description

Key The name of the ERP system-specific currency.

Value The canonical currency, which must match the UniqueName column in your CurrencyPull integration event (typically Currency.csv).

Preferred Defines the reverse mapping used when there are multiple ERP system names for one canonical currency. For example, when Ariba Buyer is pushing a purchase order to an ERP system, the canonical currency in Ariba Buyer must be mapped to an ERP system-specific currency. If your mapping has a canonical name that maps to multiple ERP system-specific codes, Ariba Buyer uses the Preferred column in the mapping file to choose which ERP system code to use.




CurrencyConversionRatePull Integration Event

The CurrencyConversionRatePull integration event defines the rates used for converting currencies. At a minimum, this integration event must include the following:

• A conversion rate between each currency in your system and the system base currency (for triangulation)

• A conversion rate from euro (EUR) to every EMU currency

Ariba Buyer uses a direct conversion rate or a reciprocal in preference to triangulation, when possible, but the minimum requirement is to be able to convert all possible currencies to the system base currency. For information on currency conversion rate issues and the legal requirements of EMU currencies and the euro, see the Ariba Buyer Euro Conversion Guide.

The CurrencyConversionRatePull integration event loads partitioned data.

Ariba Buyer supplies implementations of this integration event that read from ERP systems and from a CSV file. Most configurations read currency conversion rates from an ERP system.

CurrencyConversionRate Fields

In the default Ariba Buyer configuration, the CurrencyConversionRate integration event reads only from the following file:

ariba/variants/Plain/partitions/None/data/CurrencyConversionRate.csv

The fields in CurrencyConversionRate.csv are as follows:

Field Description

UniqueName An identifier for this currency rate.

FromCurrency The currency you are using as the starting point. This value must be the UniqueName of a currency, as defined by your CurrencyPull integration event.

ToCurrency The currency you are using as the destination. This value must be the UniqueName of a currency, as defined by your CurrencyPull integration event.



The following example shows a line from a typical version of CurrencyConversionRate.csv:

"CAD","CAD","USD","0.787526","Wed Jan 20 00:00:00 1993"

If you load a conversion rate for an illegal conversion, the rate will load successfully but will be ignored. For the rules of euro conversions, see the Ariba Buyer Euro Conversion Guide.

Considerations for Oracle Partitions

For Oracle Financials partitions, you can use the SelectionRange parameter to tailor the CurrencyConversionRatePull integration event to specify a range of conversion dates. Using this parameter, you can configure the integration event to pull only the most recent dates or you can configure it to pull rates in a specific time period.

You specify the SelectionRange parameter in the integration event table. This parameter can be set to either the constant MostRecent or to an integer. If set to MostRecent, only the most recent currency rates are pulled. If set to an integer, that integer represents the number of days for which currency conversion rates will be pulled. For example, if you set SelectionRange to 5, all the conversion rates for the past five days will be pulled.

Rate The currency rate, which must be a number such as “.632”.

Date The date on which this rate was entered.


UniqueName An identifier for this currency rate.



The following example shows a CurrencyConversionRatePull integration event entry that uses the SelectRange parameter:

CurrencyConversionRatePull = {Channel = {

Subject = "vorcl.CurrencyConversionRateEvent";TibcoSheet = CurrencyConversionRateEvent;Timeout = 1200000;

};LoggingName = CurrencyConversionRate_Oracle;MessageParameters = {


EventSource = "porcl:CCR:Oracle";ExternalConnection = "Oracle11_0Financial

};};SchemaName = ariba.integration.param.Database;

};Schedules = {

Schedule1 = { DayOfWeek = Weekday; Hour = 20; Minute = 30};SelectionRange = MostRecent;TopicName = CurrencyConversionRatePull;

};

EuroConversionRate Integration Event

In Oracle 11.0 the conversion rates from “EUR” to other European currencies that are part of the EMU are stored separately, apart from other currency exchange rates.

Oracle 11.0 configurations include an additional integration event, the EuroConversionRatePull integration event, which loads these conversion rates into Ariba Buyer.

The EuroConversionRatePull integration event loads partitioned data.

Considerations for SAP Partitions

SAP uses currency conversion rate types to keep track of the various ways you can convert from one currency to another. For example, there is a rate type for an average conversion rate across a period of time, and another rate type for a conversion rate effective on a particular day.



Ariba Buyer uses two SAP currency conversion types:

• Type B currency conversion rates are called bank selling rates, and they are the conversion rates at which lending institutions are willing to exchange currencies they are selling. Ariba Buyer uses the type B conversion rates for currency conversions and operations internal to your SAP partition.

• Type M currency conversion rates are the standard translation at an “average” rate. Type M is the default rate which SAP uses for purchase orders.

By default, SAP assumes that all Ariba Buyer line items use a conversion rate of M. Ariba Buyer always pushes purchase orders with a rate type of M, and you cannot change the rate in your configuration.

By default, Ariba Buyer pulls currency conversion rates of type B from SAP. You can configure Ariba Buyer to pull something other than a rate of type B by changing the implementation of the integration event. For example, if you are using TIBCO as your integration channel, you change the TIBCO worksheet. For more information on currency conversion rates in SAP, see the Ariba Buyer SAP Integration Guide.

For the currency rate pull, you can tailor the range of currency rates by setting a ZARIBTVARV parameter called Z_ARIBA_CURR_CONV_DAYS_PAST to determine how many days back in the past Ariba Buyer RFCs will look for historical conversion rates. The default setting is for 21 days.

For information on how to configure this and other Ariba Buyer RFC parameters, see the Ariba Buyer SAP Integration Guide.

Considerations for PeopleSoft Partitions

Ariba Buyer does not support historical currency conversion data from PeopleSoft. The currency rate integration event always pulls the most recent conversion rate.



CurrencyGroupPull Integration Event

You use the CurrencyGroupPull integration event to set up different lead currencies for different users or currencies. For example, you can use currency groups to set things up so that the euro is the lead currency for users who are in EMU countries.

The CurrencyGroupPull integration event loads global data, not associated with any partition. Ariba Buyer supplies one implementation of this integration event, which reads from a CSV file.

Note: If you choose to pull your canonical currency list from an ERP system instead of from a CSV file, you cannot use currency groups.

CurrencyGroup Fields

In the default configuration, the CurrencyGroupPull integration event reads from the following file:

ariba/variants/Plain/partitions/None/data/CurrencyGroup.csv

The fields in CurrencyGroup.csv are as follows:

The CurrencyGroup.csv file defines two groups. The EMU Candidate group has no lead currency defined.

The following examples shows the default version of CurrencyGroup.csv:

UniqueName,Name,LeadCurrencyEMU,European Monentary Union,EUREMUC,EMU Candidate,

Your configuration also includes an associated CurrencyGroupLanguagePull integration event. For more information, see “Multilingual Data” on page 21.

Field Description

UniqueName The unique name for this currency group.

Name The user-visible name for this currency group.

LeadCurrency The lead currency for this currency group, which must be the UniqueName of a currency defined by your CurrencyGroupPull integration event.

Chapter 9 Currencies Choosing a Currency


Choosing a Currency

When a user logs in to create a new requisition or expense report, Ariba Buyer must choose a default currency for that new approvable. The currency is chosen as follows:

• If the user has a default currency, then that currency is used. A typical configuration associates a default locale and currency with each shared user, with the SharedUserPull integration event. The user sees that default currency throughout Ariba Buyer, regardless of the partition.

• If the user does not have a default currency, Ariba Buyer determines the default currency by partition, using parameters in config/Parameters.table.

Application.Base.Data.DefaultCurrency

Application.Base.DefaultLocale

• If the partition-specific parameters are not set, then Ariba Buyer uses system-level defaults, also specified in config/Parameters.table:

• System.Base.Data.DefaultCurrency

• System.Base.DefaultLocale


Chapter 10

Product Classification Codes

This chapter describes how to set up and configure product classification codes. It includes the following sections:

• “Introduction to Classification Codes” on page 141

• “Commodity Codes in Ariba Buyer” on page 143

• “Integration Events for Commodity Codes” on page 146

• “Commodity Codes for PunchOut Items” on page 157

Introduction to Classification Codes

Classification codes are used to classify products and services. A classification system is a set of classification codes.

There are a variety of classification systems in use in the industry. An Ariba Buyer configuration can use just one classification system or it can use several different systems, with mapping files to translate between them.

Classification Code Standards

There are a variety of emerging global standards for classification systems. Many corporations also have proprietary systems associated with legacy data.

Examples of commonly used classification systems include the following:

• UNSPSC. (Universal Standard Products and Services Classification)

• NAICS (North American Industry Classification System)

• eClass Standardized Material and Service Classification

Chapter 10 Product Classification Codes Introduction to Classification Codes


The default Ariba Buyer configuration defines a sample set of codes, and also provides implementations of several standards that are available for you to use if you choose. These standards are defined in the config/standards directory, but are not enabled in the default configuration.

Classification Code Hierarchies

Many classification systems support wildcards or hierarchies. For example, UNSPSC classification codes are eight-digit numbers. Each code consists of four pairs of digits that create a hierarchy of increasingly specific categories. The finer the granularity of the product description, the more digits in the UNSPSC code. For example, the UNSPSC code for wooden pencils is

44121706

which breaks down into the following categories:

44 Office equipment, accessories, and supplies12 Office supplies

17 Writing instruments06 Wooden pencils

A value of 0 for any code is interpreted as a wildcard. For example, there is no code for “assorted cut flowers.” Instead, there are categories for specific types of cut flowers, such as lilies:

10161702

10 Live plant or animal material16 Floriculture products

17 Cut flowers02 Cut lilies

To describe a more generic category of any cut flowers, you can use 10161700, replacing the last digit pair with zeros.

When you are working with a classification system, you should be aware of whether that system supports hierarchical relationships.


Commodity Codes in Ariba Buyer Chapter 10 Product Classification Codes

Commodity Codes in Ariba Buyer

For classifying goods and services, Ariba Buyer configurations use commodity codes, which are a type of classification code.

Commodity Codes in the Object Model

In the object model, commodity codes are represented with the following classes:

• ariba.basic.core.CommodityCode (unpartitioned)

• ariba.common.core.PartitionedCommodityCode (partitioned)

Shared commodity codes, of type ariba.basic.core.CommodityCode, are global data, used by all Ariba Spend Management applications.

Partitioned commodity codes, of type, ariba.common.core.PartitionedCommodityCode, are used only in Ariba Buyer. If you have a partition that uses ERP-specific codes, you represent those ERP codes with partitioned commodity codes.

Most Ariba Buyer configurations use both commodity codes and partitioned commodity codes, with mapping files to translate between the different classification systems.

Commodity Code Domains

In Ariba Buyer configuration files, each classification code is defined with a {domain,value} pair. The domain is the classification system, such as UNSPSC. The value is the code within that domain.

Each configuration chooses one domain to be the system domain. For your system domain you can choose a proprietary set of codes or you can choose an external standard such as UNSPSC. If most of your suppliers use the same external standard, it is usually simplest to choose that as system domain.

Chapter 10 Product Classification Codes Commodity Codes in Ariba Buyer


Configuring the System Domain

To configure your system commodity code domain, use the following parameters in config/Parameters.table:

• To use a single value as your system domain, specify that value with the parameter Application.ClassificationCodes.SystemCommodityCodeDomainName.

• To use different system domains in different circumstances, specify a Java class as the value of Application.ClassificationCodes.CommodityCodeUIDomainImpl. The Java class you specify as the value of this parameter must return a domain, which implements the logic of your choice. (The default implementation of this parameter returns the domain specified as SystemCommodityCodeDomainName.)

For more information on these parameters, see the Ariba Buyer Configuration Reference Guide.

Commodity Code Domain Versions

For commodity code domains that support explicit version numbers, the domain version can be specified in several places:

• In the Domain field of the CSV file read by the CommodityCodePull integration event. In the default configuration, this file is CommodityCode.csv.

If you are loading a specific version of a commodity code standard, such as NAICS_v2002 or unspsc_v12.2, it is recommended that you explicitly specify the version in the Domain field of your commodity code CSV files. If the version is omitted, for example, if the domain is listed as NAICS or unspsc, Ariba Buyer assumes the domain has the version specified in the classification code domain meta. For more information on specifying the domain of a set of commodity codes you wish to load, see “CommodityCodePull Integration Event” on page 147.

• In the SystemVersion field of the CSV file read by the ClassificationCodeDomainMetaPull integration event. In the default configuration, this file is ClassificationCodeDomainMeta.csv. The classification code domain meta defines properties of domains in your configuration, whether or not commodity codes in those domains are actually loaded. When incoming commodity codes do not explicitly include a domain version number, Ariba Buyer assumes that the system version specified in the domain meta applies.


Commodity Codes in Ariba Buyer Chapter 10 Product Classification Codes

For example, if the domain meta defines NAICS_v2002 as the system version for the NAICS domain, incoming commodity codes whose domain is specified only as NAICS are assumed to be in the NAICS_2002 domain. For information on the classification code domain meta, see “ClassificationCodeDomainMetaPull Integration Event” on page 150.

• In the DomainFrom and DomainTo fields of the CSV file read by the ClassificationCodeMapPull integration event. In the default configuration, this file is ClassificationCodeMap.csv. This file specifies mappings between commodity codes in different domains, including different versions of the same domain. For example, commodity codes in the domain NAICS_v97 can be mapped to those in the domain NAICS_2002 and also to those in the domain unspsc_v12.2. For more information on commodity code domain mappings, see “Commodity Code Mappings” on page 145

Integration With Other Applications

To configure the exchange of commodity codes with other applications, use the following parameters in config/Parameters.table:

• To specify the domains sent to other applications, set the parameter Application.ClassificationCodes.ASMSharedDomainList. This parameter specifies which commodity code domains are included when sending values to other applications. In the default configuration, this parameter is set to ASMSharedDomainList =("unspsc"). To send additional domains, add the domain names to the comma-separated list of values.

• To facilitate integration with Ariba Category Management, set the parameter Application.ClassificationCodes.SystemAllNodeUniqueName. This parameter names a single parent node for your system commodity code domain. In the default configuration, this parameter is set to All. For more information on how to configure your commodity code domain so that this node is at the root of the hierarchy, see “CommodityCodePull Integration Event” on page 147.

For more information on these parameters, see the Ariba Buyer Configuration Reference Guide.

Commodity Code Mappings

To support multiple classification code systems, Ariba Buyer provides a flexible mapping mechanism that you can use to translate between naming conventions in different domains.

Chapter 10 Product Classification Codes Integration Events for Commodity Codes


Ariba Buyer translates between sets of codes as follows:

• When catalog items come in from suppliers, with the supplier’s product codes, Ariba Buyer maps the supplier’s codes into your default Ariba Buyer classification codes using a commodity code map. A commodity code map translates between commodity codes in different domains. The items then go into the product catalog, tagged with your default codes.

This mapping is done with the ClassificationCodeMapPull event, as described in “ClassificationCodeMapPull Integration Event” on page 152.

If your configuration uses different versions of the UNSPSC standard, you can use UNSPSC audit files to map between UNSPSC versions, instead of a commodity code map. An UNSPSC audit file contains information that maps less recent UNSPSC versions to a current version. You can find sample audit files in the directory config/standards. You specify the location of the audit file using the Application.ClassificationCodes.UnspscAuditFile parameter. For more information on this parameter, see the Ariba Buyer Configuration Reference Guide.

• When a user chooses an item to order, Ariba Buyer can potentially map the commodity code into a partitioned commodity code, before pushing to an ERP. This mapping is done with the CommodityExportMapPull integration event, as described on “CommodityExportMapPull Integration Event” on page 153.

Integration Events for Commodity Codes

This section describes the integration events used to create commodity code data:

• “CommodityCodePull Integration Event” on page 147

• “ClassificationCodeMapPull Integration Event” on page 152

• “PartitionedCommodityCodePull Integration Event” on page 150

• “CommodityExportMapPull Integration Event” on page 153


Integration Events for Commodity Codes Chapter 10 Product Classification Codes

CommodityCodePull Integration Event

The CommodityCodePull integration event defines a set of commodity codes.

Ariba Buyer supplies one implementation of this integration event, which reads from CSV. The fields in the data file are as follows:

In the default configuration, the CommodityCodePull integration event reads from the following file,

config/variants/Plain/partitions/None/data/CommodityCode.csv

The following are sample lines from this file:

Domain,UniqueName,Name,ParentUniqueName"ccc","Adhesives","Adhesives","ccc","Alkaline Batteries","Alkaline Batteries","Batteries" "ccc","Apparel","Apparel""ccc","Attaches","Attaches",

Field Description

Domain The domain of the code being used, such as ccc, eClass or NAICS_V2002. (Note that some classification codes support explicit version numbers, as in _V2002.) This domain is displayed in Domain pull-down menus in Ariba Buyer Administrator when you search for, create, or edit commodity codes and commodity code maps.

UniqueName The unique identifier for this code. The UniqueName fields for each commodity code must be distinct.

Name A name that corresponds to this UniqueName.

ParentUniqueName The UniqueName of another commodity code. This field defines hierarchical relationships between commodity codes, and is used by the CommodityCodeParentPull event.

Enabled Boolean that enables or disables a commodity code. This column is optional, and is true by default. You can use this field to hide or show branches (or individual codes).



Data Files For Commodity Code Standards

You can find definitions for several common commodity code standards in the directory config/standards. For example, this directory includes the following files:

config/standards/EClassCommodityCode.csv

config/standards/NAICSCommodityCode.csv

config/standards/UNSPSCCommodityCode.csv

The NAICS file provided includes domain names that show the version of the NAICS code being used. For example:

Domain,UniqueName,Name,ParentUniqueName"NAICS_V2002","493","Warehousing and Storage", "NAICS_V2002","4931","Warehousing and Storage", "NAICS_V2002","49311","General Warehousing and Storage", "NAICS_V2002","493110","General Warehousing and Storage", "NAICS_V2002","49312","Refrigerated Warehousing and Storage",

If you choose to use an external standard, add an integration event to your configuration that reads from the appropriate file in config/standards. Because these files represent external standards, you should not modify the data in these files.

s To use a modified version of an external standard:

1 Load the external commodity set from the sample configuration. For example, load all of UNSPSCCommodityCode.csv to define the initial set of UNSPSC codes.

2 Make any changes in CommodityCode.csv, such as overriding names or disabling certain sections of the tree.

Ariba Buyer provides a subset of the full UNSPSC hierarchy as default sample data for the system commodity code domain. In the sample data, the full UNSPSC hierarchy has been pruned by permanently deleting unused commodity codes.

If you intend to roll out gradually a large commodity code standard such as UNSPSC, the recommended procedure is to:

• Load the full standard, for example, the full UNSPSC hierarchy

• Prune the hierarchy by disabling (hiding) branches of the tree using Ariba Buyer Administrator



When you disable a commodity code, you can enable it again later if you choose. Disabling branches of the tree allows an easier expansion path than manually editing the CSV file as you roll out new commodity codes.

For more information on enabling and disabling commodity codes, see the Ariba Buyer Administrator online help.

For an example of how to use CommodityCode.csv to modify classification code standards, see the CommodityCode.csv file in the default configuration.

For information on how to map standard classification codes to other codes in your configuration, see “ClassificationCodeMapPull Integration Event” on page 152.

SystemAllNode Configuration

If you are integrating with Ariba Category Management, you must define one root node to act as the parent node for your system commodity code domain. Specify the UniqueName of that node as the parameter Application.ClassificationCodes.SystemAllNodeUniqueName and adjust the data in CommodityCode.csv so that this node is the parent for your top-level categories in the system domain. For example, to define the value All as your root node, you would have entries such as the following:

"Domain","UniqueName","Name","ParentUniqueName","Enabled" "unspsc","All","All commodities",, "unspsc","10","Live Plant/Animal Material","All",false

CommodityCodeParent Pull Integration Event

The CommodityCodeParentPull event reads the same data as the CommodityCodePull event, and uses that data to create hierarchical relationships between related codes.

This event applies only if the commodity code standard supports hierarchical relationships.



PartitionedCommodityCodePull Integration Event

The PartitionedCommodityCodePull integration event defines a list of partition-specific commodity code names. Typically you use this integration event if you integrate with an ERP system that defines its own set of commodity codes.

In the default configuration, the CSV implementation reads from the following file:

config/variants/var/partitions/partition/data/PartitionedCommodityCode.csv

The fields in PartitionedCommodityCode.csv are as follows:

The following example shows several lines from PartitionedCommodityCode.csv:

"UniqueName","Name","Description","CategoryId""MFG:CABINET","MFG:CABINET",,"5""MISC:MISC","MISC:MISC",,"6"

If you are pulling commodity codes from Oracle, note that some commodity codes might have a colon (:) at the end of the code. This occurs because Oracle has two levels (segments) of commodity codes, which are concatenated with a colon, so when the second segment is null, only a colon appears at the end of the first segment.

ClassificationCodeDomainMetaPull Integration Event

The ClassificationCodeDomainMetaPull integration event defines properties (meta information) about the commodity code domains in your configuration.

Field Description

UniqueName A unique identifier for a commodity code.

Name A name that corresponds to this UniqueName.

Description A textual description of the commodity code, used as a comment.

CategoryID This field applies only if you are pushing to an ERP system that requires category codes, such as Oracle. If your ERP system doesn’t require category IDs, you can omit this field.



In the default configuration, ClassificationCodeDomainMetaPull reads from the following file:

config/variants/Plain/partitions/None/data/ClassificationCodeDomainMeta.csv

The fields in ClassificationCodeDomainMeta.csv are as follows:

Field Description

Domain The unique name of a commodity code domain, as defined in CommodityCode.csv. This domain is displayed in Domain pull-down menus in Ariba Buyer Administrator when you create or edit commodity codes and commodity code maps.

Description A comment, describing this domain.

MapAdapterImplementation

The name of a Java class, specifying a mapping class that can implement additional functionality, such as wildcarding. The class must implement ariba.basic.map.valueInstanceMapAdapter.

JavaClass The Java class represented by this domain. Usually set to ariba.basic.core.CommodityCode.

LookupClass In Version 8.2, the value must always be ariba.basic.core.CCCCLlassificationLookupImpl. This class takes a {domain,value} pair and returns an object for that domain.

LogicalGroup Defines a logical grouping of domains, such as public commodity standards, system, etc. This field is currently used only for documentation and comments; no code reads this field.

SystemVersion String that specifies the version of this classification code system in use, if relevant. For example, unspsc_v12.2. This string is used only when a version is not specified for a domain that supports versioning.

FetchAllMappings Boolean that controls query behavior for mappings between domains. If set to true (the usual case) Ariba Buyer fetches all mappings between domains in a single query. If set to false, Ariba Buyer makes multiple database queries and caches the results. A setting of true uses more memory but provides faster response time.



ClassificationCodeMapPull Integration Event

The ClassificationCodeMapPull integration event maps product codes on incoming catalog data into commodity codes. Ariba Buyer supplies one implementation of this integration event, which reads from a CSV file.

In the default configuration, the ClassificationCodeMapPull integration event reads from the following file:

config/variants/Plain/partitions/None/data/ClassificationCodeMap.csv

The fields in ClassificationCodeMap.csv are as follows:

The following example shows several lines from the mapping file in the default configuration, which maps from UNSPSC codes to codes in the ccc domain:

DomainFrom,ValueFrom,DomainTo,ValueToUNSPSC,3120,"ccc",AdhesivesUNSPSC,26111702,"ccc",Alkaline Batteries

The mapping does not have to be one-to-one.

If you are using an external standard, from config/standards, you may also choose to use the mapping files defined in that directory, such as EgiiToEClassClassificationCodeMap.csv.

Field Description

DomainFrom The unique name of a commodity code domain, as defined in CommodityCode.csv. This domain is displayed in Domain pull-down menus in Ariba Buyer Administrator when you search for, create, or edit commodity code maps.

ValueFrom A unique identifier for a commodity code in the given domain.

DomainTo The unique name of a second commodity code domain, as defined in CommodityCode.csv. This domain is displayed in Domain pull-down menus in Ariba Buyer Administrator when you search for, create, or edit commodity code maps.

ValueTo A unique identifier for a commodity code in the second domain.



Using Wildcards

If the commodity domain supports wildcards, you can use them in the mapping file. For example, the following mapping entry means that any incoming SPSC code that starts with 3333 matches the Batteries code:

Batteries,SPSC,33330000

You can use this technique to set up a “catch-all” mapping for catalogs with codes that do not seem to match anything. For example, the following mapping entry maps all codes that do not match anything else to the code Misc:

Misc,SPSC,00000000

Though you can use wildcards in the mapping file if the commodity code domain supports them, you cannot use wildcards when searching for commodity codes in Ariba Buyer Administrator.

CommodityExportMapPull Integration Event

The CommodityExportMapPull integration event defines a mapping from commodity codes to partitioned commodity codes. This integration event also defines default accounting information based on commodity codes. When a user orders a catalog item, Ariba Buyer defaults any accounting fields listed in this file, so that the user does not have to supply those values.

This integration event loads partitioned data. You typically have one implementation of this integration event for each partition, which defaults accounting data appropriate for that partition.

In the default configuration, this integration event reads from the following file:

config/variants/variant/partitions/partition/data/CommodityExportMap.csv

The fields in CommodityExportMap.csv are as follows:

Field Description

CommonIdDomain The unique name of a commodity code domain, as defined in CommodityCode.csv.

CommonId The name of a commodity code within that domain.



The following is a simple example of CommodityExportMap.csv:

CommonIdDomain,CommonId,PartitionedCommodityCode,AccountType,Accountccc,Batteries,HC:ADMIS,Expense,HC:154000ccc,Binders,HC:ADMIS,Expense,HC:154000ccc,Boards,HC:ADMIS,Expense,HC:154000

The first line of this file maps the commodity code Batteries to the commodity code HC:ADMIS, and defaults the AccountType and Account fields for all items with the commodity code Batteries.

Defaulting Additional Accounting Data

You can default different accounting information by adding additional fields to the CommodityExportMap.csv file.

For example, consider the following CommodityExportMap.csv file, which shows accounting information for a SAP configuration:

CommonIdDomain,CommonId,MaterialGroup,AccountType,CompanyCode,GeneralLedger,Asset,WBSElement,InternalOrder,ItemCategory,AccountCategoryccc,Batteries,00706,CostCenter,3000,0000410000,,,,," ",Kccc,Batteries,00706,CostCenter,1000,0000400000,,,,," ",Kccc,Computer Server,01203,Asset,3000,,000000001005,,," ",Accc,Computer Server,01203,InternalOrder,3000,0000404000,,,000000100015," ",Fccc,Computer Server,01203,WBSElement,3000,0000404000,,3-1200/31,," ",P

This file maps commodity codes to material groups (an SAP-specific term), and specifies default accounting information for several additional accounting fields based on the commodity code and account type.

PartitionedCommodityCode

The unique name of a partitioned commodity code.

AccountType The account type associated with this commodity code. The AccountType is part of the primary key for database lookup of commodity code exports. Every mapping file must include the AccountType field.

... One or more fields of accounting information that are to be defaulted based on the commodity code.




This example does two kinds of defaulting:

• Default Accounting Information by Company Code. In an SAP configuration, each user has a company code, which is set in the user preferences. In this example, two sets of accounting information are defined for the commodity code Batteries:

ccc,Batteries,00706,CostCenter,3000,0000410000,,,,," ",Kccc,Batteries,00706,CostCenter,1000,0000400000,,,,," ",K

When a user orders batteries, Ariba Buyer selects the line that matches the user’s preferred company code. For example, if a user has the company code 3000, Ariba Buyer selects general ledger item 0000410000. However, if a user changes the default company code to 1000 in the Title field and selects a batteries item, Ariba Buyer selects general ledger item 0000400000.

• Default Accounting Information by Account Type and Account Assignment. The material group 01203 (commodity code Computer Server) has three different AccountType values:

ccc,Computer Server,01203,Asset,3000,,000000001005,,," ",Accc,Computer Server,01203,InternalOrder,3000,0000404000,,,000000100015," ",Fccc,Computer Server,01203,WBSElement,3000,0000404000,,3-1200/31,," ",P

In the Ariba Buyer user interface, the Account Assignment field corresponds to AccountCategory, and the Account Type field corresponds to AccountType. If a user chooses “A (Asset)” in the Account Assignment field and “Asset” in the Account Type field, Ariba Buyer chooses 000000001005 for the Asset number default value. Similarly, if a user selects “F (Order)” and “Internal Order,” Ariba Buyer chooses 000000100015 for the Internal Order number default value.

For the material group 00706 (commodity code Batteries), there is only a cost center assignment:

ccc,Batteries,00706,CostCenter,3000,0000410000,,,,," ",Kccc,Batteries,00706,CostCenter,1000,0000400000,,,,," ",K

In this case, if a user chooses “Asset” in the Account Assignment field, Ariba Buyer does not choose a default Asset value because one is not defined in the file.



Modifying the Integration Event

For each accounting field you add to the CommodityExportMap.csv file, you must also perform the following tasks:

• Make appropriate changes to the underlying integration event logic, so that it interprets the new fields. For information on writing or modifying integration events, see Chapter 3, “Integration Events.”

• Add the new field or fields to the ObjectDefaulting group. Ariba Buyer uses this group from the CopyFields action to decide which fields to copy when defaulting from the requisition onto line items. For example:

<group name="ObjectDefaulting"><groupClass name="ariba.common.core.CommodityExportMapEntry">

<groupField name="Asset"/></groupClass>

</group>

For more information on defaulting of accounting fields, see “Default Accounting Information” on page 213.

Note: For ad hoc items, the default configuration defaults accounting information with the trigger action ariba.procure.core.action.SetAccountingFromCommodityCode. This trigger sets accounting information on an ad hoc ReqLineItem from the PartitionedCommodityCode integration event by reading the CommodityExportMap.csv file and using an entry that corresponds to that commodity code.

Detecting Mapping Errors

The commodity map export event creates a mapping from commodity codes to partitioned commodity codes. Administrative users can also create mappings from the Ariba Buyer Administrator user interface, which can potentially lead to ambiguous mappings. For example, if a commodity code is mapped to multiple partitioned commodity codes, Ariba Buyer cannot determine which partitioned code to use when creating an ERP order.

Ariba Buyer includes a scheduled task that administrators can use to detect ambiguous mappings. For more information, see the discussion of the CommodityCodeReport scheduled task in the Ariba Buyer Configuration Reference Guide.


Commodity Codes for PunchOut Items Chapter 10 Product Classification Codes

Export Events and Language Pull Events

In addition to the pull events for commodity codes, Ariba Buyer also defines corresponding export events and language pull events. The export events write your data to CSV files, using the Ariba File Channel to export the data.

For more information on export events, see “Export Events” on page 70.

For more information on language pulls, see Chapter 7, “Languages, Countries, and Locales.”

Commodity Codes for PunchOut Items

An Ariba Buyer catalog can include PunchOut items, where the catalog information is set up at the supplier site and is outside the control of Ariba Buyer administrators. When commodity code information is defined at the supplier, the commodity code is not necessarily valid in your Ariba Buyer configuration.

When the user chooses a PunchOut item, Ariba Buyer checks the commodity code:

• If a PunchOut item has a valid commodity code, Ariba Buyer maps that incoming commodity code to a commodity code.

• If you are using a wildcard mapping and have a mapping for 00000000, the wildcard takes effect.

• If the code has not yet been mapped, it is not a valid Ariba Buyer commodity code. Ariba Buyer allows the user to select that item anyway, and maps the invalid code to the special commodity code NONMAPPEDCOMMODITY.

In the default configuration, Ariba Buyer handles this special commodity code value in the following ways:

• With the condition ariba.procure.core.condition.NonMappedCommonCommodityCode, which reports whether a given line item has the special commodity code NONMAPPEDCOMMODITY.

• With the base Commodity approval rule, which inserts an appropriate approver at the beginning of the approval flow and maps the invalid commodity code for error notification. This approver cannot edit the commodity code within the Ariba Buyer user interface, but you can customize Ariba Buyer to add a condition that will allow editing based on the user’s role.

Chapter 10 Product Classification Codes Commodity Codes for PunchOut Items


• With Notification 49 (Notification of Import Mapping Failure). When the MappingLog log listener detects error messages pertaining to PunchOut items with commodity codes that are not mapped correctly, it sends this notification message to users who have the CatalogManager permission.

To enable the notification, you turn on the MappingLog log listener in the System.Logging section of the config/Parameters.table file. You can set parameters in this log listener’s definition to customize the subject of the notification message as well as the permission of the users to whom this notification is sent. By default, the notification is sent to users with the CatalogManager permission.

The Catalog Manager can use Ariba Buyer Administrator to change the commodity code to something appropriate for your configuration, and add it to the mapping so that the error does not occur again.


Chapter 11

Users

This chapter describes how to load and maintain lists of users and associated profile information. It includes the following sections:

• “Introduction to Users” on page 159

• “Integration Events For User Data” on page 161

• “How to Maintain User Profile Information” on page 167

• “User Profile Validation” on page 169

• “Organic User Growth” on page 170

Introduction to Users

Users are shared across Ariba Spend Management applications. Each user has some shared user information (such as the user’s name), which is shared by all Ariba Spend Management applications, and can also have additional application-specific data.

In the object model, user data is represented by the following objects:

• A shared user, which represents the data shared across all Ariba Spend Management applications. A shared user is an object of type ariba.user.core.User.

• An Ariba Buyer user, which stores user data specific to Ariba Buyer. This object is of type ariba.common.core.User.

Shared user data is not partitioned, and is shared among all Ariba Spend Management applications. Ariba Buyer user data is specific to one Ariba Buyer partition, and can include information such as partition-specific accounting information.

This chapter describes how to load and manage shared users and partitioned users.

Chapter 11 Users Introduction to Users


Creating Users

To set up an Ariba Buyer configuration with user data, you run two integration events:

• The SharedUserPull integration event, which defines a set of shared users.

• The UserPull integration event, which defines the Ariba Buyer profile data for each user in a partition. This integration event always associates user profile data with an existing shared user. It does not create new users.

For information on these integration events, see “Integration Events For User Data” on page 161.

Using Organizations

An organization is a field of a shared user that indicates whether that user is a supplier or a user from the buying organization. Organizations serve as a way to separate users, to indicate who the user is and what that user can do. For example, in Ariba SN, an organization can represent a supplier, a customer, or both.

The default configuration of Ariba Buyer defines an initial organization for Ariba Buyer users, specified in config/Parameters.table. In the default configuration, all Ariba Buyer users belong to that organization, which has the ID of [Buyer]. In a typical Ariba Spend Management configuration, all applications use this same value for the organization ID of Ariba Buyer users. If you change this value in your Ariba Buyer, you must change it in all other Ariba Spend Management applications as well.

Users representing suppliers, who access Ariba Buyer by punching in through the PunchIn site, are typically not members of the Ariba Buyer organization. For more information on how users from other applications can punch in to access specific Ariba Buyer functionality, see the Ariba Spend Management Configuration Guide.

Maintaining User Profile Data

Ariba Buyer allows users to make changes to their user profiles, using the User Preferences screens. The user can use these screens to create a User Profile Update request (an approvable document), and then submit that request for approval. For example, a user could create a User Profile Update request to change his default currency or locale.


Integration Events For User Data Chapter 11 Users

When you define your configuration, you specify the fields for which users are allowed to submit updates. For example, you might not want to allow users to submit changes for management level or supervisor information.

For information on the choices available for maintaining user profile information, see “Integration Events For User Data” on page 161.

Using Ariba Buyer Administrator

From Ariba Buyer Administrator, an administrator who has appropriate privileges can edit the fields of a shared user or an Ariba Buyer user. For more information on how to use Ariba Buyer Administrator to administer user data, see the Ariba Buyer Administrator online help.

Adding New Users

When you set up your configuration, you must define user accounts for your users. You can do so in either of the following ways:

• With integration events, adding new users and profile data to your data source for users

• With organic user growth, which allows users to create user profile information dynamically, from the user interface

For information on organic growth, see “Organic User Growth” on page 170.

Integration Events For User Data

Loading user data into Ariba Buyer involves the following integration events:

• OrganizationPull

• SharedUserPull

• SharedUserSupervisorPull

• UserPull

• SharedUserShipToAddressMapPull

This section describes those integration events and associated export events.

Chapter 11 Users Integration Events For User Data


OrganizationPull Integration Event

You use the OrganizationPull integration event to define the organizations for your Ariba Buyer users. In the default configuration, this integration pull defines just one default organization. Organizations can also be created in other ways:

• Supplier pulls can create organizations for those suppliers (as described in “Supplier Data” on page 217).

• Administrators can create organizations dynamically, from Ariba Buyer Administrator.

The OrganizationPull integration event pulls organization data from a CSV file. In the default configuration, the OrganizationPull integration event reads data from the following file:

config/variants/Plain/partitions/None/data/Organization.csv

The fields in Organization.csv are as follows:

After setting up your organization data, verify that System.Base.Data.DefaultOrganization in config/Parameters.table is set to a valid SystemID. This parameter defines set the default organization for Ariba Buyer users. In the default configuration, the this parameter is set to [Buyer].

Note: Organizations that represent suppliers have additional data, such as supplier contact information, tax ID, and indicators of whether the supplier is minority-owned.

OrganizationExport Integration Event

You use the OrganizationExport integration event to export organization data from your configuration to a CSV file. In the default configuration, the OrganizationExport integration event writes to the following file:

config/variants/Plain/partitions/None/data/Organization_Export.csv

For general information on export events, see “Export Events” on page 70.

Field Description

SystemID The unique identifier for this organization.

Name A text string describing the organization.



SharedUserPull Integration Event

You use the SharedUserPull integration event to define user data that is shared across Ariba Spend Management applications.

Ariba Buyer provides an implementation of the SharedUserPull integration event that reads shared user data from a CSV file, and alternative implementations that pull the same information from either PeopleSoft HRMS or PeopleSoft Financials.

This section describes the CSV implementation. For information on the PeopleSoft implementations, see the Ariba Buyer PeopleSoft Integration Guide.

In the default configuration, the SharedUserPull integration event reads data from the following file:

config/variants/Plain/partitions/None/data/SharedUser.csv

The fields in SharedUser.csv are as follows:

Field Description

UniqueName A unique name to identify this user.

PasswordAdapter The name of a password adapter, such as PasswordAdapter1, which must match a value defined in System.PasswordAdapters.

The PasswordAdapter field is used to disambiguate users in migrated configurations. If your configuration has users with the same UniqueName in different partitions, the PasswordAdapter field allows you to differentiate between them. The combination of UniqueName and PasswordAdapter must be unique.

If you do not have any duplicate unique names in your user data, you can leave this field blank.

Name The user’s full name, used for display purposes.

EmailAddress The user’s email address, which is used for sending notification messages. The value should be the simple email address (such as jbenning), without domain or qualifiers.



The following example shows lines from a typical SharedUser.csv file:

UniqueName,PasswordAdapter,Name,EmailAddress,Supervisor,SupervisorPasswordAdapter,DefaultCurrency,LocaleID,OrganizationIDdanderson,PasswordAdapter1,Dave Anderson,danderson,ekinsey,PasswordAdapter1,USD,en_US,,jbenning,PasswordAdapter1,Janice Benning,jbenning,danderson,PasswordAdapter1,USD,en_US,,

Supervisor The UniqueName of the user’s direct supervisor. The supervisor is uniquely identified by the combination of name and password adapter.

Most users are required to have supervisors. (Users representing suppliers are not required to have a supervisor.) For exception cases, such as for the CEO, you can use the NoSupervisor permission to specify that the user does not have a supervisor.

SupervisorPasswordAdapter The password adapter associated with Supervisor. Each supervisor is also a user, and is uniquely identified by the combination of Supervisor and SupervisorPasswordAdapter.

DefaultCurrency A default currency for the user. If this field is null, it defaults to the value specified as Application.Base.Data.DefaultCurrency. For information on currencies, see “CurrencyPull Integration Event” on page 131.

LocaleID A default locale for the user, which must be a valid LocaleID. For information on defining locales, see “LocaleIDPull Integration Event” on page 100.

OrganizationID The user’s organization, which must match the organization ID defined by your OrganizationPull integration event.




SharedUserSupervisorPull Integration Event

The SharedUserSupervisorPull integration event reads the SharedUser.csv file and loads only the Supervisor and SupervisorPasswordAdapter fields. It does not load the other fields.

The supervisor data is done with a separate integration event because there is a dependency: a supervisor is always a user object. To make sure that the user and the supervisor both exist, you must first run the SharedUserPull integration event, to define all users, and then the SharedUserSupervisor event, to set the supervisor.

The default configuration supplies two implementations of this integration event, one that reads from CSV and one that reads from PeopleSoft HRMS. For information on how to use the SharedUserSupervisorPShrPull integration event to update user supervisor information from PeopleSoft HRMS, see the Ariba Buyer PeopleSoft Integration Guide.

UserPull Integration Event

You use the UserPull integration event to read a data source that defines Ariba Buyer profile data for users. For each Ariba Buyer user in the data source, the integration event links the Ariba Buyer user to an existing shared user, and then stores the Buyer-specific data for that user.

Ariba Buyer provides an implementation of the UserPull integration event that pulls profile data from a CSV file, and alternative implementations that pull the same information from either PeopleSoft HRMS or PeopleSoft Financials.

This section describes the CSV implementation. For information on the PeopleSoft implementation, see the Ariba Buyer PeopleSoft Integration Guide.

In the default configuration, the UserPull integration event reads data from the following file:



config/variants/variant/partitions/partition/data/User.csv

The fields in User.csv are as follows:

The following example shows lines from a typical User.csv file:

UniqueName,ManagementLevel,Accounting,VanillaDeliverTo,sbougon,,8,,,”Steven Bougon”

This example omits accounting information. The fields of accounting information, and even the number of columns, are typically different for each partition. For example, an Oracle partition would include Oracle-specific information, such as a cost center, and a PeopleSoft partition might include a Business Unit.

Field Description

UniqueName The unique identifier. This field is used to link the user to a shared user. The value must match uniqueName of a shared user, as defined by your SharedUserPull integration event.

PasswordAdapter Password adapter field, used to uniquely identify this user.

ManagementLevel A number, representing the user’s management level. Lower numbers are higher in the organization; for example, the CEO is typically at Level 1. This field is not required. It is used only in the default approval rules. For more information, see the Ariba Buyer Approval Rules Guide.

VanillaDeliverTo The user’s preferred Deliver-To information, which is typically a string such as “Second floor”.

Accounting The data source can include any number of columns of accounting information, depending on the accounting entities used in this partition. For example, an Oracle partition might have columns for Cost Center and Project.

For information on setting up accounting entities, and typical entries for Oracle, PeopleSoft, or SAP configurations, see “AccountPull Integration Event” on page 204.


How to Maintain User Profile Information Chapter 11 Users

Note: In the default configuration, the UserPull integration event runs a trigger action after each successful integration pull. This trigger action assigns a set of default permissions, such as CreateRequisition, to all Ariba Buyer users. (The CreateRequisition permission specifies which users are authorized to create requisitions. In the default configuration, this permission is assigned to all Ariba Buyer users, but not to supplier users who punch in to Ariba Buyer.)

SharedUserShipToAddressMap Integration Event

The SharedUserShipToAddressMap integration event associates one or more ship-to addresses with a shared user. Each shared user has a vector of ship-to addresses, which can be different for different partitions.

This integration event must run after your SharedUserPull integration event and after your AddressPull integration event. This event is described in “SharedUserShipToAddressMap Integration Event” on page 199.

How to Maintain User Profile Information

To maintain your configuration, you have several choices for how to update the data in a user profile:

• You can update the data source (CSV file or ERP system), and run the integration event to pull the revised data.

• You can allow users to update their own information, through user preferences. In this case, the user follows the User Preferences link in the user interface to create a set of suggested changes, which are then represented by a User Profile Update approvable document. When the approvable document has been fully approved, the profile changes take effect.

Most configurations pull some data from integration events, and allow users to update other information (such as default currency and locale) interactively, from the Ariba Buyer user interface.

This section describes how to configure Ariba Buyer to specify which information users can update from the user interface. For complete information on how users can use User Preferences to change profile information, see the online help.

Chapter 11 Users How to Maintain User Profile Information


sourceOfTruth Field Property

To set up fields that you plan to maintain in Ariba Buyer, you set the field property sourceOfTruth, in metadata XML. When you define a field whose sourceOfTruth is Ariba Buyer, that field will not be updated by data integrations.

The following metadata XML example shows how you would set the sourceOfTruth field property on the default currency and locale fields:

<inClass name="ariba.user.core.User"><inClassVariant name="vcsv">

<inField name="DefaultCurrency"><properties sourceOfTruth="ORMS"/>

</inField><inField name="LocaleID">

<properties sourceOfTruth="ORMS"/></inField>

</inClassVariant></inClass>

In this case, the currency and locale information will be created the first time you run the SharedUserPull integration event, but will not be updated on later pulls. Changes that the user makes, through the user interface, take precedence over information read from the data source.

For more information, see “Sources of Field Values” on page 29.

User Profile Changes on Initial Login

If you are expecting users to supply some information dynamically, you can choose whether to require new users to specify any missing or incomplete information before they can perform other tasks.

To require new users to specify missing information, set the parameter Application.Authentication.ModifyUserProfileonInitialLogin in config/Parameters.table to true. When this parameter is set to true, Ariba Buyer requires each new user to have a complete user profile before he or she can access the full functionality of the application.


User Profile Validation Chapter 11 Users

User Profile Validation

As with any approvable document, a User Profile Update request is validated when the document is submitted for approval. However, a user’s profile can become invalid at any time, even if the profile information itself has not changed. For example, if one user leaves the company, the user profiles for that user’s direct reports become invalid, because the supervisor field is no longer valid.

To help ensure that profiles remain valid, Ariba Buyer provides an option to require user profile validation each time a user logs on. User profile validation involves the following checks:

• Does this user have a current User Profile?

• Is this user’s Supervisor valid?

• Is this user’s ShipTo address valid?

• Is this user’s email address set?

To determine whether the ShipTo and email addresses are valid, the user profile validation tests the validity conditions defined for each field, within the UserValidation group. For more information on validity conditions, see the Ariba Buyer Customization Guide.

s To enable and configure user profile validation:

1 Set the parameter Application.Authentication.ValidateUser to either Notify or Force. (The default is Off.)

• If you choose Notify, the user sees a dialog box listing the error, but can continue on normally.

• If you choose Force, the user can still log in, but must submit a profile update before continuing with other tasks.

2 Check the validity conditions associated with EmailAddress and ShipTo fields, in the group UserValidation. To change the logic for validation, you change the validity condition for that field in the context of the UserValidation group. (For information on how the ShipTo field is populated, see “Addresses” on page 195.)

Chapter 11 Users Organic User Growth


Organic User Growth

Organic user growth allows you to add new users dynamically, without requiring a data source. With organic growth, you do not need to define the profile information for a user in User.csv. Instead, you define the user name, and then ask the user to set up the initial profile information from the user interface.

You can use organic growth for all users, or just to add new users after loading your original users from a data source.

s To configure Ariba Buyer to use organic user growth:

1 Set the parameter Application.Authentication.OrganicGrowth to true.

2 Set the parameter Application.Authentication.ModifyUserProfileOnInitialLogon to true. (See “User Profile Changes on Initial Login” on page 168.)

3 Set the parameter Application.Base.Data.DefaultOrganicUserLocale to name the locale for new users.

s To add a new user with organic user growth:

1 Add the new user to your authentication source, such as passwd.txt.

2 Reload the password information, if necessary. (If you are using a real-time password adapter, such as the NT Domain Login adapter, you do not need to explicitly reload the password information. If you are using passwd.txt and the Crypt Password Adapter, you do have to reload.)

3 Invite the user to log in. If you have a configuration with multiple password adapters, the user must log in using a URL that specifies the password adapter to use for authentication. For example:

https://myserver:444/Buyer/Main/ad/webjumper?passwordAdapter=PwordAdapter1

For complete information about arguments to the login URL, see the Ariba Buyer Configuration Guide.

4 Ariba Buyer uses the user name to look up an associated shared user. Each newly “grown” user is always linked to an existing shared user. If the shared user does not already exist, it will be created as part of the organic growth process.

At this point, the user can log in, but does not yet have user profile information set. When the user first logs in, Ariba Buyer guides the user through the user preferences to create an updated profile and submit it for approval.

Users added with organic user growth cannot log in and use the full functionality of Ariba Buyer until they have created a profile and had it approved.


Chapter 12

Permissions, Roles, and Groups

This chapter describes how to configure roles, groups, and permissions. It includes the following sections:

• “Introduction to Permissions, Roles, and Groups” on page 171

• “Integration Events for Permissions” on page 175

• “Integration Events for Roles” on page 177

• “Integration Events for Groups” on page 179

• “Integration Events for Mappings” on page 181

• “Load Order for Integration Events” on page 186

Introduction to Permissions, Roles, and Groups

To determine which users are authorized to perform administrative tasks, Ariba Buyer uses permissions, groups, and roles:

• A permission authorizes a user to perform certain tasks. For example, only users with appropriate permissions are authorized to run integration events that pull data into Ariba Buyer.

• A role contains permissions and can also contain other roles (subroles). For example, you can define the role Buyer Administrator, and assign a collection of appropriate administrative permissions to that role. Roles can be assigned to groups, to individuals, or to other roles.

• A group is a collection of users. For example, you can use groups to represent departments or cross-functional teams.

The only way for a user to be authorized for administrative tasks is for that user to have appropriate permissions. For example, only users who have the CreateContract permission are able to create contracts. Ariba Buyer defines a set of required permissions, which are built into the logic of Ariba Buyer. Ariba Buyer checks for

Chapter 12 Permissions, Roles, and Groups Introduction to Permissions, Roles, and Groups


those named permissions when deciding whether a user is authorized to perform various tasks. When you set up a configuration, you must use the required permissions, which are in the Java code of the application.

Permissions are usually grouped into roles. Roles are primarily an administrative convenience, so that you easily assign related permissions. For example, in the default Ariba Invoice configuration, the role Invoice Administrator is assigned the following permissions:

• ForcePayInvoiceReconciliation• ForceRejectInvoiceReconciliation• InvoiceAdministrator• InvoiceLoaderEmail• InvoicePaymentEmail• InvoiceRejectionEmail

The default configuration defines a typical set of roles, but you are free to reassign permissions or rename roles to suit your configuration. None of the roles are required.

You can assign roles either to individual users or to groups of users. For example, you might choose to define a group to represent your Purchasing Department, and assign administrative roles to every user in that group.

For reference lists of the roles, permissions, and groups defined in the default configuration, see the Ariba Buyer Configuration Reference Guide.

Integration Events to Define Data

To set up your configuration, you define the names of permission, roles, and groups you choose to have in your configuration, and then set up mappings that specify which permissions are associated with each role, and which users are in each group.

In the default configuration, the association is as follows:

User -> Group -> Role -> Permission


Introduction to Permissions, Roles, and Groups Chapter 12 Permissions, Roles, and Groups

The default configuration supplies integration events for each kind of data (SharedUserPull, GroupPull, RolePull, and PermissionPull), and also integration events that define mappings. The integration events that define mappings are as follows:

The sample configuration illustrates different ways to map between users, roles, groups, and permissions. In a typical configuration, you use groups to describe organizational groupings of your users, and use roles to describe collections of permissions. The specific mappings you create depend on the business needs of your organization, and you do not have to use the full set of mappings if they are not appropriate.

Note: For configurations migrated from previous versions of Ariba Buyer, the migration process creates one group for each role, and maps between them. For example, if your configuration defines the role “CFO,” then it also has a group with the same name, and the two are linked together.

Regardless of how you choose to set up your configuration, keep in mind that you must eventually associate appropriate permissions with users. Permissions grant users the ability to perform administrative functions. Groups and roles are only organizational tools to simplify administration and implementation.

Configuration Design: Inheriting Permissions

Permissions determine what users can do. In particular, permissions control the following aspects of Ariba Buyer:

• Which users receive notification messages

• Which users are authorized to perform certain tasks

This event Maps this data

GroupUserMapPull Adds users to groups

GroupRoleMapPull Associates a role with each group

GroupPermissionMapPull Associates permissions with groups

RolePermissionMapPull Assigns permissions to roles

SharedUserRoleMapPull Assigns roles to shared users

SharedUserPermissionMapPull Assigns permissions to shared users

Chapter 12 Permissions, Roles, and Groups Introduction to Permissions, Roles, and Groups


When you set up your configuration, you can assign permissions directly to users, or through groups and roles. The table below summarizes the ways you can assign permissions to users:

This action Has this result

Assigning a permission directly to a user

The user has the designated permission.

Assigning a permission to Role A and assigning Role A to the user

The user has all permissions associated with Role A.

A role can contain other roles, which are increasingly restrictive. The user receives only permissions directly associated with Role A. For example:

In your technical publications group, the director (Queen Victoria) has the role Kingpin, which consists of two subroles: “CreateDocs” and “DeleteDocs.” Some writers have the role CreateDocs and others have the role DeleteDocs. Writers who have DeleteDocs (or CreateDocs) do not inherit the Kingpin role.

Assigning a permission to Group A and adding the user to Group A

The user has all permissions associated with Group A.

A group can contain other groups. The user receives any permissions directly associated with Group A, and also any permissions associated with groups of which A is a member. For example:

The members of your technical publications team are members of the group DocTeam. Members of the DocTeam group have permissions to FileDefects and CauseTrouble. There are subgroups for Editors and Writers, each of which has its own set of permissions. Anyone in the group of Editors has permissions specific to the editors, as well as the overall group permissions to FileDefects and CauseTrouble.


Integration Events for Permissions Chapter 12 Permissions, Roles, and Groups

Integration Events for Permissions

Every configuration defines a set of permissions. Permissions are not partitioned and are shared across all Ariba products.

You read permissions into your configuration with the PermissionPull integration event and export them with the PermissionExport integration event.

In a multilingual configuration, you also have related integration events to define and export the permission names in other languages. For more information, see “Multilingual Data” on page 21.

PermissionPull Integration Event

You use the PermissionPull integration event to define a list of permissions that are available for authorizing users.

Ariba Buyer provides one implementation of this integration event, which reads a list of permissions from a CSV file. In the default Ariba Buyer configuration, the PermissionPull integration event reads permissions from the following files:

ariba/variants/Plain/partitions/None/data/Permission.csvconfig/variants/Plain/partitions/None/data/Permission.csv

The fields in Permission.csv are as follows:

Field Description

UniqueName A unique identifier for this permission. No two permissions can have the same UniqueName.

Name The user-visible name for this permission. In the standard configuration, the Name is always the same as the UniqueName, but you can change the Name.

Description A descriptive string, explaining how or where the permission is used.

Chapter 12 Permissions, Roles, and Groups Integration Events for Permissions


The following example shows the format of a typical Permission.csv file:

UniqueName,Name"SearchManager","SearchManager","Users who have this permission can save system searches in the Ariba Buyer user interface.""ServerMonitor","ServerMonitor","Users who have this permission are able to perform the system administration functions, such as running scheduled tasks and integration events.""SourcingAuthorized","SourcingAuthorized","Users who have this permission..."

Ariba Buyer defines a set of required built-in permissions, which must exist in every configuration. Ariba Buyer uses these built-in permissions to restrict access to certain functionality in the system. These built-in permissions must be defined in every configuration, and there must be at least one user who has each such permission.

For a list of permissions in the default configuration, and information on which permissions are required, see the Ariba Buyer Configuration Reference Guide.

PermissionExport Integration Event

You use the PermissionExport integration event to export permission data to a CSV file. In the default configuration, PermissionExport writes to the following file:

config/variants/Plain/partitions/None/data/Permission_Export.csv

For more information, see “Export Events” on page 70.

EditPermissionPull Integration Event

You can use the EditPermissionPull integration event to allow access to specific configuration files, log files, or rule set (.rul) files in Ariba Buyer Administrator. The EditPermissionPull integration event is optional.

For information on using this integration event, see the Ariba Buyer Administrator Customization Guide.


Integration Events for Roles Chapter 12 Permissions, Roles, and Groups

ExecutePermissionPull Integration Event

You use the ExecutePermissionPull integration event to restrict access to specific integration events and scheduled tasks in Ariba Buyer Administrator. The ExecutePermissionPull integration event is optional.

For information on using this integration event, see the Ariba Buyer Administrator Customization Guide.

Integration Events for Roles

Every configuration defines a set of roles, which are managed through Common Data Server. Roles are not partitioned, and are shared across Ariba Spend Management products.

You read roles into your configuration with the RolePull integration event and export them with the RoleExport integration event.

In a multilingual configuration, you also have a related integration event, RoleLanguagePull, to define the role names in other languages. For more information on integration events to pull translated values, see “Multilingual Data” on page 21.

RolePull Integration Event

You use the RolePull integration event to define a set of roles for your corporation. Ariba Buyer supplies two implementation of the RolePull integration event: one that reads from CSV and one that reads from PeopleSoft HR. This section describes the implementation that reads from CSV files. For information on the implementation that reads from PeopleSoft, see the Ariba Buyer PeopleSoft Integration Guide.

In the default Ariba Buyer configuration, the RolePull integration event reads role information from the following file:

config/variants/Plain/partitions/None/data/Role.csv

There is no data in the ariba directory, because there are no predefined or required roles. The default configuration defines sample roles only.

Chapter 12 Permissions, Roles, and Groups Integration Events for Roles


The fields in Role.csv are as follows:

The following example shows the format of a typical Role.csv file:

id,NamePurchasing Manager,Purchasing ManagerAdministrator,AdministratorSenior Analyst,Senior Analyst

RoleChildRoleMapPull Integration Event

You use the RoleChildRoleMapPull integration event to define subroles (roles within roles). This integration event is optional. If you do not use subroles in your configuration, you do not need to use this event. Ariba Buyer supplies one implementation of the RoleChildRoleMapPull integration event, which reads from a CSV file.

In the default configuration, the RoleChildRoleMapPull integration event reads from the following file:

config/variants/Plain/partitions/None/data/RoleChildRoleMap.csv

The fields in RoleChildRoleMap.csv are as follows:

The following examples shows lines from a typical RoleChildRoleMap.csv file:

Parent.UniqueName,UniqueNameExpense Manager,AnalystReceiving Manager,AnalystCategory Manager,Workforce Manager

Field Description

id The unique identifier for a role. No two roles can have the same id.

Name The user-visible name for this role.

Field Description

Parent.UniqueName The unique identifier for the parent role.

UniqueName The unique identifier of the new subrole being defined.


Integration Events for Groups Chapter 12 Permissions, Roles, and Groups

In the example, Analyst is a subrole of Expense Manager and Receiving Manager, while Workforce Manager is a subrole of Category Manager.

RoleExport Integration Event

You use the RoleExport integration event to export role definitions to a CSV file. The RoleExport integration event uses the Ariba File Channel to export data.

In the default configuration, RoleExport writes to the following file:

config/variants/Plain/partitions/None/data/Role_Export.csv


Integration Events for Groups

Every configuration defines a set of groups, which are managed through Common Data Server.

You read groups into your configuration with the GroupPull integration event.

In a multilingual configuration, you also have a related integration event, GroupLanguagePull, to define the group names in other languages. For more information, see “Multilingual Data” on page 21.

GroupPull Integration Event

You use the GroupPull integration event to define a set of groups for your corporation. Ariba Buyer supplies one implementation of the GroupPull integration event, which reads group information from a CSV file.

In the default configuration, the GroupPull integration event reads group information from the following file:

config/variants/Plain/partitions/None/data/Group.csv

Chapter 12 Permissions, Roles, and Groups Integration Events for Groups


The fields in Group.csv are as follows:

GroupChildGroupMapPull Integration Event

You use the GroupChildGroupMapPull integration event to define subgroups (groups of groups). This integration event is required only if you choose to define subgroups. Ariba Buyer supplies one implementation of the GroupChildGroupMapPull integration event, which reads from a CSV file.

In the default configuration, the GroupChildGroupMapPull integration event reads from the following file:

config/variants/Plain/partitions/None/data/GroupChildGroupMap.csv

The fields in GroupChildGroupMap.csv are as follows:

GroupExport Integration Event

You use the GroupExport integration event to export group data to a CSV file. In the default configuration, GroupExport writes to the following file:

config/variants/Plain/partitions/None/data/Group_Export.csv


Field Description

id The unique identifier for a group. No two groups can have the same id.

Name The user-visible name for this group.

Field Description

Parent.UniqueName The unique identifier for the parent group.

UniqueName The unique identifier of the subgroup.


Integration Events for Mappings Chapter 12 Permissions, Roles, and Groups

Integration Events for Mappings

This section defines the mapping events that are available for making associations between groups, roles, users, and permissions.

The set of mapping files you choose to use depends on your business requirements. However, you must ensure that your configuration associates all required permissions with at least one user.

The default configuration includes export events for each of the integration events listed in this section.

Mapping Events for Groups

This section describes mapping events that assign users to groups, and that associate roles or permissions with groups.

Assigning Users to Groups

To assign users to groups, you use the GroupSharedUserMapPull integration event.

The default configuration supplies two implementations of the GroupSharedUserMapPull integration event: one that reads from CSV and one that reads from PeopleSoft HRMS. For information on the PeopleSoft implementation, see the Ariba Buyer PeopleSoft Integration Guide.

The GroupSharedUserMapPull integration event is a header-details integration event that reads the following files:

config/variants/Plain/partitions/None/data/Group.csv config/variants/Plain/partitions/None/data/GroupSharedUserMap.csv

Chapter 12 Permissions, Roles, and Groups Integration Events for Mappings


The header file is Group.csv. The details file (GroupSharedUserMap.csv) is a CSV file that defines a mapping between shared users and groups. The fields in GroupSharedUserMap.csv are as follows:

The following example shows several lines from a typical GroupSharedUserMap.csv file:

Parent.UniqueName,UniqueName,PasswordAdapterCFO,ekinsey,PasswordAdapter1CSV Editor,aribasystem,PasswordAdapter1CSV Editor,bcarlstrom,PasswordAdapter1

Assigning Roles to Groups

You use the GroupRoleMapPull integration event to specify the roles associated with a group.

Ariba Buyer supplies one implementation of this integration event, which reads from a CSV file. In the default Ariba Buyer configuration, the GroupRoleMapPull integration event reads data from the following file:

config/variants/Plain/partitions/None/data/GroupRoleMap.csv

The fields in GroupRoleMap.csv are as follows:

Field Description

Parent.UniqueName The name of a group, which must match a UniqueName defined by your GroupPull integration event.

UniqueName A username, which must match the UniqueName of a user as defined by your SharedUserPull integration event.

PasswordAdapter The name of a PasswordAdapter, which is part of the unique lookup key for a user.

Field Description

Parent.UniqueName The unique name of a group. You are assigning roles to this group.

UniqueName The unique name of a role to be assigned to this group.



For example:

Parent.UniqueName,UniqueNameBuyer Administrator,Buyer Administrator

Assigning Permissions to Groups

You use the GroupPermissionMapPull integration event to specify the permissions associated with a group.

Ariba Buyer supplies one implementation of this integration event, which reads from a CSV file. In the default Ariba Buyer configuration, the GroupPermissionMapPull integration event reads data from the following file:

config/variants/Plain/partitions/None/data/GroupPermissionMap.csv

The fields in GroupPermissionMap.csv are as follows:

For example:

Parent.UniqueName,UniqueNameBuyer Administrator,ServerMonitor

Mapping Events for Roles

To associate permissions with roles, you use a role permission map. You read the permission map data from an integration event, the RolePermissionMapPull integration event.

RolePermissionMapPull Integration Event

You use the RolePermissionMapPull integration event to specify the permissions associated with a role. This integration event must be run after the RolePull and PermissionPull integration events because it depends on the data they define.

Field Description

Parent.UniqueName The unique name of a group. You are assigning permissions to this group.

UniqueName The unique name of a permission to be assigned to this group.

Chapter 12 Permissions, Roles, and Groups Integration Events for Mappings


Ariba Buyer supplies one implementation of this integration event, which reads from a CSV file. In the default Ariba Buyer configuration, the RolePermissionMapPull integration event reads data from the following file:

config/variants/Plain/partitions/None/data/RolePermissionMap.csv

The fields in RolePermissionMap.csv are as follows:

You can associate multiple permissions with any role. For example, the following excerpt from PermissionsMap.csv assigns several different administrative permissions to the role Administrator:

"Role","Permission""Expense Receipt Manager","ExpenseReceiptManager"Buyer Admin","NoPasswordExpiration"Buyer Admin","ConfigurationFiles""PCard Manager","OverdueChargesNotifierEmail""PCard Manager","PCardManager""Purchasing Admin","OrderConfirmationErrorNotification""Purchasing Admin","OrderFailureImmediateEmail""Purchasing Admin","PurchaseOrderRejectionEmail"

Mapping Events for Shared Users

This section describes mapping events that you can use to assign roles or permissions directly to shared users.

Assigning Roles to Users

You use the SharedUserRoleMapPull integration event to assign roles to shared users.

Ariba Buyer supplies one implementation of this integration event, which reads from a CSV file. In the default Ariba Buyer configuration, the SharedUserRoleMap integration event reads data from the following file:

Field Description

Role The UniqueName of a role, which must be defined in your configuration.

Permission The UniqueName of a permission, which must be defined in your configuration.



config/variants/Plain/partitions/None/data/SharedUserRoleMap.csv

The fields in SharedUserRoleMap.csv are as follows:

For example:

"Parent.UniqueName","Parent.PasswordAdapter","UniqueName"ghalas,PasswordAdapter1,CFOfgifford,PasswordAdapter1,Expense Managerfgifford,PasswordAdapter1,Expense Receipt Managerfgifford,PasswordAdapter1,EditApprovable

Assigning Permissions to Users

You use the SharedUserPermissionMapPull integration event to assign permissions to shared users.

Ariba Buyer supplies one implementation of this integration event, which reads from a CSV file. In the default Ariba Buyer configuration, the SharedUserPermissionMap integration event reads data from the following file:

config/variants/Plain/partitions/None/data/SharedUserPermissionMap.csv

The fields in SharedUserPermissionMap.csv are as follows:

Field Description

Parent.UniqueName The unique name of a shared user. The UniqueName and PasswordAdapter fields, together, identify the user.

Parent.PasswordAdapterThe password adapter for the shared user.

UniqueName The unique name of the role being assigned to this user.

Field Description

Parent.UniqueName The unique name of a shared user. The UniqueName and PasswordAdapter fields, together, identify the user.

Parent.PasswordAdapterThe password adapter for the shared user.

UniqueName The unique name of the role being assigned to this user.

Chapter 12 Permissions, Roles, and Groups Load Order for Integration Events


For example:

"Parent.UniqueName","Parent.PasswordAdapter","UniqueName"prozelle,PasswordAdapter1,NoSupervisoradavis,PasswordAdapter1,QueryAll

Load Order for Integration Events

Role, permission, group, and user data is interrelated, so the order in which you load the associated integration events is important.

If you reload the integration events manually, from Ariba Buyer Administrator, make sure that you load the mapping integration events after the integration events that define the permissions, roles, and groups. That is, you must:

• Run PermissionPull and RolePull before RolePermissionMapPull.

• Run RolePull and SharedUserPull before GroupRoleMapPull.

• Run GroupPull and SharedUserPull before GroupMapPull.


Chapter 13

Units of Measure

This chapter describes how to set up and configure units of measure (UOM) in Ariba Buyer to accommodate the terminology in use at your company. It includes the following sections:

• “Introduction to Units of Measure” on page 187

• “Units of Measure in Catalog Files” on page 188

• “Canonical Units of Measure” on page 189

• “Unit of Measure Mappings in Partitions” on page 191

• “ERP-Specific Considerations” on page 194

• “PunchOut Considerations” on page 194

• “Parameter for Default Unit of Measure” on page 194

Before you read this chapter, become familiar with mapped data, and the use of a canonical set of data with different names in different partitions. For more information, see “Mapped Data” on page 25.

Introduction to Units of Measure

Units of measure (UOM) are terms that describe how items are packaged, such as by the box, by the unit, by the case, by the dozen, or by the pound.

When you set up your Ariba Buyer configuration, you must ensure that you and your suppliers agree on the terminology for units of measure, so that, for example, a user who orders a box of pencils receives a box and not a bushel.

Chapter 13 Units of Measure Units of Measure in Catalog Files


The United Nations organization has developed a set of terminology that is gradually being accepted as the recommended standard. For information on this standard, known as UNCEFACT, go to the following website:

www.unece.org/cefact/rec/add2_f.htm

Ariba recommends the use of the UNCEFACT standard when possible, but provides an architecture that allows other sets of terminology as well, for situations where your company is in transition or has not yet adopted UNCEFACT.

Units of measure are mapped data—you define a set of canonical units of measure and a set of mappings that translates those names into the names you use in each partition.

For example, if you have an external ERP system that uses BK for boxes, but your canonical term is BX, you use a mapping to translate between BK and BX so that Ariba Buyer knows the mappings are one and the same.

Units of Measure in Catalog Files

When you load catalogs into Ariba Buyer, you must ensure that Ariba Buyer interprets the units of measure in those catalogs correctly.

If the catalog file uses your canonical set of units of measure, then interpreting the terms is not required. If the catalog file uses a different set of terminology, you must define a mapping file to make sure that the incoming terminology is interpreted correctly.

There are two mapping files for units of measure. For catalogs, these files reside in the SupplierDirect partition:

• UnitsOfMeasureMap.csv, which defines mappings for UNCEFACT (also called UNUOM) units of measure.

• UnitsOfMeasureCIFMap.csv, which defines mappings for ANSI units of measure.

Typically, catalogs in CIF 3.0 format use UNUOM, so Ariba Buyer uses UnitsOfMeasureMap.csv to translate the units of measure in these catalogs. Catalogs sent through Ariba Buyer in cXML must use UNUOM and will not accept ANSI. Catalogs in CIF 2.1 format use ANSI, so UnitsOfMeasureCIFMap.csv is used for these catalogs.

www.unece.org/cefact/rec/add2_f.htm


Canonical Units of Measure Chapter 13 Units of Measure

The header of a CIF 3.0 file can specify whether the file uses UNUOM. By default, all CIF 3.0 files have the header value UNUOM: TRUE, but if a CIF 3.0 file has UNUOM: FALSE, then that file is assumed to use ANSI and UnitsOfMeasureCIFMap.csv is used.

For more information on the CIF 3.0 header, see the Ariba Catalog Format Reference.

Canonical Units of Measure

You define your canonical set of units of measure with the UnitOfMeasurePull integration event. This integration event loads unpartitioned data, shared across all partitions.

In the default configuration, Ariba Buyer reads the canonical set of units of measure from a CSV file and supplies a default CSV file that uses the UNCEFACT standard units of measure as the canonical units of measure. Most configurations should use this implementation, without modification.

The only reason not to use the standard set of units of measure is if you have only one external ERP system in your configuration and want to use the terminology from that system as your default terminology. In any other configuration, you must use the UNCEFACT standard as your canonical units of measure.

Chapter 13 Units of Measure Canonical Units of Measure


UnitOfMeasure Fields

In the default Ariba Buyer configuration, the data for the UNCEFACT implementation is in the following file:

ariba/variants/Plain/partitions/None/data/UnitsOfMeasure.csv

The fields in UnitsOfMeasure.csv are as follows:

The following example shows sample lines from UnitsOfMeasure.csv:

06,small spray,small spray,false,005,lift,lift,false,008,heat lot,heat lot,false,0

UnitOfMeasureLanguagePull Integration Event

Your configuration includes an associated UnitOfMeasureLanguagePull integration event to define the UOM names in other languages. For more information, see “Multilingual Data” on page 21.

Field Description

UniqueName A unique identifier for a unit of measure. The UniqueName fields for each unit of measure must be distinct from one another.

Name A name that corresponds to the UniqueName. The name is the part that users see in the application, such as “Package.”

Description More details on the term, used as comments and documentation.

AllowNonWhole A Boolean that indicates whether this UnitOfMeasurePull integration event is one that supports non-whole quantities. For example, a centimeter supports non-whole quantities, while a micron or an atom does not. If this field is missing, the default is false.

Category Indicates whether the unit of measure is time related. A value of 1 means the unit of measure is time related. A value of 0 means the unit of measure is not time related.


Unit of Measure Mappings in Partitions Chapter 13 Units of Measure

Unit of Measure Mappings in Partitions

Each partition provides a set of units of measure to users. For example, if a user creates a non-catalog item and chooses a unit of measure for that item, the Ariba Buyer chooser shows the list of units of measure available in that partition, not the canonical ones.

You define the units of measure for a partition by defining a mapping from the canonical units of measure. The mapping file serves two purposes:

• It allows you to define the names you want to use for units of measure within a partition.

• It acts as a filter, so you can present only a subset of your canonical units of measure.

For example, you can use a mapping file to specify that only metric terms are visible in your partition. Every partition must use filtering. Because the UNCEFACT configuration file contains about 16,000 entries, it makes sense to reduce that number for each partition.

UnitOfMeasureMapPull Integration Event

The UnitOfMeasureMapPull integration event defines mappings for UNCEFACT (also called UNUOM) units of measure. It translates between canonical units of measure and the units of measure in a partition.

Typically, catalogs in CIF 3.0 or cXML format use UNUOM, so Ariba Buyer uses UnitsOfMeasureMap.csv to translate the units of measure in these catalogs.

UnitOfMeasureMap Fields

The UnitOfMeasureMapPull integration event uses a mapping file in the simple map format, which is typically stored in the file UnitOfMeasureMap.csv.

Chapter 13 Units of Measure Unit of Measure Mappings in Partitions


The fields in UnitOfMeasureMap.csv are as follows:

UnitOfMeasureCIFMapPull Integration Event

The UnitOfMeasureCIFMapPull integration event defines mappings for ANSI units of measure. Catalogs in CIF 2.1 format use ANSI, so this integration is used for these catalogs. It is defined only in the SupplierDirect partition.

Note: The header of a CIF 3.0 file can specify whether the file uses UNUOM. By default, all CIF 3.0 files have the header value UNUOM: TRUE, but if a CIF 3.0 file has UNUOM: FALSE, then that file is assumed to use ANSI and UnitsOfMeasureCIFMap.csv is used.

UnitOfMeasureCIFMap Fields

The UnitOfMeasureCIFMapPull integration event uses a mapping file in the simple map format, which is typically stored in the file UnitOfMeasureCIFMap.csv.

Field Description

Key The external ERP system-specific unit of measure name.

Value The canonical unit of measure name. The Value must match a UniqueName in your canonical UnitsOfMeasure.csv file.

Preferred A Boolean that indicates your preferred mapping. For each Value in your mapping file, you can have as many mappings as you want, but only one should have the Preferred value of true.



Unit of Measure Mappings in Partitions Chapter 13 Units of Measure

The fields in UnitOfMeasureCIFMap.csv are as follows:

Considerations for Unit of Measure Mappings

This section describes considerations to be aware of when setting up unit of measure mappings:

• Each external ERP system-specific code (Key) can appear only once in the file—you cannot define multiple mappings for the same ERP system-specific code. If the same Key appears more than once, Ariba Buyer keeps only the last entry and ignores the earlier ones.

• You can have several external ERP system-specific unit of measure names that map to the same canonical unit of measure name. For example, the following UnitOfMeasureMap.csv file maps the external ERP system-specific unit of measure names 01B and 02B to the internal canonical unit of measure name BX:

"Key","Value","Preferred","Comment"01B,BX,false,Box02B,BX,true,Box01D,DZN,,DozenA,ACR,,AcreB1H,HBX,,Box of 100

• When multiple external ERP system-specific unit of measure names are mapped to the same canonical unit of measure name, Ariba Buyer uses the Preferred field to determine which mapping to use when an administrator exports data from Ariba Buyer to some external source for that partition. The unit of measure mapping in the SupplierDirect partition does not require the Preferred field.

• You can map one canonical unit of measure to an empty external ERP system-specific value. If an incoming catalog has no unit of measure defined, it defaults to the canonical unit of measure that is mapped to the empty value.

Field Description

Key The external ERP system-specific unit of measure name.

Value The canonical unit of measure name. The Value must match a UniqueName in your canonical UnitsOfMeasure.csv file.

Preferred A Boolean that indicates your preferred mapping. For each Value in your mapping file, you can have as many mappings as you want, but only one must have the Preferred value of true.

Comment An optional field for documentation within the data file.

Chapter 13 Units of Measure ERP-Specific Considerations


ERP-Specific Considerations

Oracle 11.0 maintains two different unit of measure fields in the database:

• UOM_CODE

• UNIT_OF_MEASURE.

The UOMInfoPull integration event defines a mapping between UOM_CODE and UNIT_OF_MEASURE. The UOM_CODE is used for requisitions and purchase orders. Receipt pushes into Oracle 11.0 require the UNIT_OF_MEASURE field.

PunchOut Considerations

PunchOut refers to the process of ordering an item from a remote supplier’s catalog. When a user selects a PunchOut item, Ariba Buyer launches the supplier’s website. The user can then order the item, check out, and return to Ariba Buyer, where the item appears in the requisition.

If the PunchOut order message received from the supplier site during the PunchOut session contains a null or invalid unit of measure, Ariba Buyer creates the requisition with a null unit of measure. The user cannot submit the requisition until the unit of measure is corrected, for example, by “punching out” to supplier site again and editing the line item. The user can also save the requisition in the Composing state.

Parameter for Default Unit of Measure

For catalog items, the unit of measure is associated with the catalog. For non-catalog items, or items where the unit of measure is missing, Ariba Buyer uses a default unit of measure for that partition.

You specify the default unit of measure for a partition in the config/Parameters.table file with the parameter Application.Procure.DefaultUnitofMeasure. The value you specify for this parameter must match the UniqueName of a canonical unit of measure, as defined by your UnitOfMeasurePull integration event.


Chapter 14

Addresses

This chapter describes how to define your address data, used for shipping and billing addresses. It includes the following sections:

• “Introduction to Addresses” on page 195

• “AddressPull Integration Event” on page 196

• “SharedUserShipToAddressMap Integration Event” on page 199

• “AddressExport Integration Event” on page 200

• “Billing Addresses” on page 200

Introduction to Addresses

Every Ariba Buyer configuration defines a standard set of addresses, used both for shipping addresses and billing addresses.

Addresses are shared by all Ariba Spend Management applications: when you create an address in Ariba Buyer, that address is also available to other Ariba Spend Management applications. The basic address data (the postal address) is shared across Ariba Spend Management applications, but each application can also store additional address data that is not shared by other applications.

In the object model, these two locations for user data are represented by the following objects:

• A shared address, which defines data that is shared across Ariba Spend Management applications. A shared address is of type ariba.basic.core.Address.

• An Ariba Buyer address, which extends a shared address with additional application-specific data. An Ariba Buyer address is of type ariba.common.core.Address.

Chapter 14 Addresses AddressPull Integration Event


The ariba.common.core.Address class is a subclass of ariba.basic.core.Address. The fields in the shared address (the superclass) are nonpartitioned, and are available to all Ariba Spend Management applications. The fields in the Ariba Buyer address (the subclass) are partitioned and are available only within a specific Ariba Buyer partition.

You typically read Ariba Buyer addresses from an ERP system, and use those addresses to generate orders sent back to that ERP system. For example, if your ERP system requires a MailStop field, that field is read from the original data source, stored on the (partitioned) Ariba Buyer address, and included on any orders sent to that ERP system.

You load address data with the following integration events:

• The AddressPull integration event, which loads Ariba Buyer addresses. This integration event also creates a shared address for each Ariba Buyer, if necessary. You do not run a separate event to create the shared addresses.

• The SharedUserAddressMap integration event, which associates a default shipping address with each Ariba Buyer user in your configuration.

The rest of this chapter describes those integration events.

AddressPull Integration Event

You use the AddressPull integration event to define the set of standard addresses for your corporation. The AddressPull integration event loads partitioned addresses, of type ariba.common.core.Address, and associates each with an existing shared address. If the shared address does not exist, the AddressPull integration event creates the shared address as well.

Ariba Buyer supplies implementations of this integration event that read from ERP and from CSV. Most configurations read address data from an ERP system.


AddressPull Integration Event Chapter 14 Addresses

Address Fields

A shared address includes the following fields:

A PostalAddress includes the following fields:

The AddressPull integration event reads a data source that includes the fields of a shared address, as well as any additional data to be included in the Ariba Buyer address.

In the default configuration, the AddressPull integration event reads from the following file:

config/variants/variant/partitions/partition/data/Address.csv

Field Description

UniqueName The unique identifier for this address.

Name The name of this site (typically a building number or name).

PostalAddress Shared fields of an address, such as City and State. See the next table for a complete list.

Field Description

Lines The street address for this site. To have multiline street addresses, include embedded carriage returns directly in the data source.

City The city name for this site.

State The state name for this site, typically a 2-letter abbreviation.

PostalCode The street address and contact information for this site.

Country The unique name of the country where this address is located. The value must be defined by your CountryPull integration event.

Chapter 14 Addresses AddressPull Integration Event


The fields in Address.csv are as follows:

If the shared address (as identified by the UniqueName field) already exists, this integration event associates data with that address. If it does not yet exist, the shared address is created.

The following lines are from a typical Address.csv file:

"UniqueName","Name","Lines","City","State","PostalCode","Country","Phone","Fax","Email","URL""1","AUSMFG","3450 Industrial Park Road","Austin","TX","78701","US","214-401-5555","+1 (214) 401-5575","","""2","PARSALES","Immeuble ""Monte Carlo"" 13 rue Mayer","Paris","","58982","FR","+33 47-62-20-14","+33 (47) 62-13-11","","""1000507","Gilroy","727 Christopher Ranch Road

Field Description

UniqueName The unique identifier of a shared address.

Name The descriptive name, part of the shared address.

Lines Field of a PostalAddress, part of the shared address.

City Field of a PostalAddress, part of the shared address.

State Field of a PostalAddress, part of the shared address.

PostalCode Field of a PostalAddress, part of the shared address.

Country Field of a PostalAddress, part of the shared address.

Phone The phone number, which is treated as a string. It can appear with or without punctuation. The string is not parsed in any way.

Fax The fax number. The format can be either of the following:

+1 (408) 543-4180

+1 408 543-4180

Email An email address, used when contacting this address with email.

URL A URL, used when contacting this address over the World Wide Web.


SharedUserShipToAddressMap Integration Event Chapter 14 Addresses

Garlic Capital of the World","Gilroy","CA","95020","US","408/847-8000","408/847-8888","",""

Notice that the last entry has a multiline address. For information on how to include special characters, such as line returns, in a CSV file, see the Ariba Buyer Configuration Reference Guide.

SharedUserShipToAddressMap Integration Event

You use an integration event, the SharedUserShipToAddressMap integration event, to associate shipping addresses with users. This integration event must run after your SharedUserPull integration event and after your AddressPull integration event.

The SharedUserShipToAddressMapPull integration event is a header-details integration event that reads the following files:

config/variants/Plain/partitions/None/data/SharedUser.csv config/variants/Plain/partitions/None/data/SharedUserShipToAddressMap.csv

The details file (SharedUserShipToAddressMap.csv) is a CSV file that defines a mapping between shared users and shipping addresses. The fields in SharedUserShipToAddressMap.csv are as follows:

Field Description

UniqueName A username, which must match a UniqueName defined by your SharedUserPull integration event.

PasswordAdapter Password adapter field, part of the unique key for the user.

Oracle107ShipTo Used in Oracle configurations. The value must match a UniqueName defined by your AddressPull integration event.

PeoplesoftShipTo Used in PeopleSoft configurations. The value must match a UniqueName defined by your AddressPull integration event.

SAPShipTo Used in SAP configurations. The value must match a UniqueName defined by your AddressPull integration event.

Chapter 14 Addresses AddressExport Integration Event


In a typical configuration, your data source has just one shipping address value, for the appropriate ERP system. For example:

UniqueName,PasswordAdapter,Oracle107ShipTo,PeoplesoftShipTo,SAPShipToacarstens,PasswordAdapter1,,SHARE:US003,achu,PasswordAdapter1,,SHARE:US003,

AddressExport Integration Event

You use an AddressExport integration event to export addresses from your configuration to a CSV file. The AddressExport integration event uses the Ariba File Channel to export data from a partition.

In the default configuration, the AddressExport integration event writes to the following file:

config/variants/variant/partitions/partition/data/Address_Export.csv


Billing Addresses

When a user creates a purchase requisition, that requisition has an associated billing address. Because users rarely change the billing address, Ariba Buyer defines a default billing address for each user, as part of that user’s User Profile data. Whenever a user creates a requisition, Ariba Buyer uses a trigger to copy that billing address onto each line item on the requisition.

If a user wants to change the billing address for a line item, he or she can override the default by choosing another billing address from the address chooser.

If a user does not have a valid billing address defined, Ariba Buyer uses the default billing address for that user’s partition, as defined by the parameter Application.Base.Data.DefaultBillToAddress. This parameter names the unique name of a billing address, from the AddressPull integration event.

In the following example, the default billing address is the one that has the UniqueName of 15, in the AddressPull integration event:

DefaultBillToAddress = 15;


Chapter 15

Accounting Information

This chapter describes how to define accounting information, associate it with users, and enable the optional features for split line item accounting or account combinations. It also describes the defaulting mechanism for copying accounting information from users onto line items.


• “Introduction to Accounting Information” on page 201

• “AccountPull Integration Event” on page 204

• “Parameters for Line Item Split Accounting” on page 207

• “SplitAccountingTypePull Integration Event” on page 207

• “AccountTypePull Integration Event” on page 209

• “Account Validation” on page 210

• “AccountingCombinationPull Integration Event” on page 211

• “Metadata XML for Accounting Combinations” on page 212

• “Default Accounting Information” on page 213

Introduction to Accounting Information

Items on purchase requisitions and expense reports typically require accounting information, so that your company’s accounting department can classify the charges appropriately.

The specific accounting information required varies from one company to the next and from one partition to the next, usually based on the accounting structures used by the underlying ERP system.

Chapter 15 Accounting Information Introduction to Accounting Information


Accounting Entities

Ariba Buyer defines a generic accounting entity, which is a piece of accounting information. Examples of accounting entities include Project, Cost Center, Account, and SubAccount.

In a typical configuration, each partition defines its own set of accounting entities. The accounting fields are not extrinsics—they are just specific instances of the generic “accounting entity.”

For information on setting up accounting entities, see “AccountPull Integration Event” on page 204.

Default Accounting Information

Most accounting information is defaulted, so that users rarely have to set accounting information from the user interface. For example, when a user creates a purchase requisition and chooses items to order, the accounting information comes from the following sources:

• The user’s default accounting information, which is set up in the User Profile. Ariba Buyer uses the user’s default accounting information to set the defaults for the requisition.

• The accounting information associated with the product, if any, which is based on the commodity code. When a user chooses such an item from the catalog, the accounting information is set by default.

You define default values for each user as part of the UserPull integration event. For example, if you are using Project and Cost Center, each user has an associated default Project and Cost Center code. For information on the UserPull integration event, see “Integration Events For User Data” on page 161.


Introduction to Accounting Information Chapter 15 Accounting Information

Line Item Split Accounting

As part of your Ariba Buyer configuration, you can choose whether to allow split accounting for line items. For example, you might choose to allow two departments to cooperatively buy a large piece of equipment, sharing both its cost and its use. Ariba Buyer supports three types of split accounting:

• By percent

• By amount

• By quantity

As part of your configuration, you can specify which of those three you support for each partition. In general, the decision about which split types to support depends on the underlying ERP system—you must configure Ariba Buyer to support only the accounting split types that are valid in your ERP system.

For example, to allow users to split the cost of a particular line item and have one cost center pay for 60 percent and another cost center pay for 40 percent, then you must define an accounting split type that allows users to split items by percent.

To configure line item split accounting, you must do the following:

• Configure the split accounting parameters. For more information, see “Parameters for Line Item Split Accounting” on page 207.

• Set up the SplitAccountingTypePull integration event. For more information, see “SplitAccountingTypePull Integration Event” on page 207.

Line item split accounting is an optional feature.

Accounting Combinations

In configurations that use an Oracle ERP system, you can set up accounting combinations. Accounting combinations are a way for an organization to enforce restrictions on combinations of accounting information. For example, your company might have restrictions that specify which project codes are valid in various cost centers.

The default Ariba Buyer configuration includes an example of accounting combinations, which is most often used in Oracle configurations.

Chapter 15 Accounting Information AccountPull Integration Event


To configure accounting combinations, you must do the following:

• Configure the accounting combination parameters. For more information, see “AccountingCombinationPull Integration Event” on page 211.

• Set up the AccountingCombinationPull integration event. For more information, see “AccountingCombinationPull Integration Event” on page 211

• Include a metadata XML property on the fields you want to have validated. For more information, see “Metadata XML for Accounting Combinations” on page 212.

Accounting combinations are an optional component of your Ariba Buyer configuration.

AccountPull Integration Event

Ariba Buyer represents accounting information with a generic accounting object, which is used in every partition. An accounting object is a collection of individual accounting entities, and each partition usually has a different collection of accounting entities.

For each partition in your configuration, you define one or more accounting entities. You use the same integration event, the AccountPull integration event, to populate the data for each accounting entity. The AccountPull integration event loads data into a partition.

Ariba Buyer supplies implementations of this integration event that read from ERP systems and from a CSV file. Most configurations read accounting information from an ERP system.


AccountPull Integration Event Chapter 15 Accounting Information

Accounting Entity Fields

In the default Ariba Buyer configuration, the AccountPull integration event from a data file in the config directory under your Ariba Buyer Server installation directory. For example, if one of your accounting entities is Department, and you are reading accounting information from a CSV file, you would put your data in a file such as the following:

config/variants/variant/partitions/partition/data/Account.csv

Each accounting entity has the following fields:

The following example shows lines from a typical Account.csv file:

"UniqueName","Name","Description""01","US- Global Computers","US- Global Computers""02","US- Global Designs","US- Global Designs"

Accounting Entities in the Default Configuration

The default Ariba Buyer configuration defines ERP system-specific accounting information for each supported ERP system. You can either use these default values directly in your configuration, or make customizations to suit your own accounting structures.

By default, CSV configurations use Oracle accounting structures, but read the data from a CSV file instead of from Oracle. The default CSV configuration includes files such as Company.csv and Product.csv, which provide a default set of accounting data, read from a CSV file. Most corporations modify this default accounting information to use their own preferred accounting entities.

Field Description

UniqueName A unique identifier for an accounting entity. The UniqueName fields for each accounting entity must be distinct from one another.

Name A name that corresponds to this UniqueName, such as “Project” or “Department.”

Description Descriptive help text about this accounting entity. The Description appears in the user interface when the user asks to see more details on a selected accounting entity.

Chapter 15 Accounting Information AccountPull Integration Event


Oracle Configurations

The following accounting entities are provided for Oracle configurations:

PeopleSoft Configurations

The following accounting entities are provided for PeopleSoft configurations:

SAP Configurations

The following accounting entities are provided for SAP configurations:

Oracle-10.7-ShipTo (corresponds to the user’s inventory organization)Oracle-10.7-CostCenter

Oracle-10.7-Company

Oracle-10.7-Region

Oracle-10.7-SubAccount

Oracle-10.7-Product

Oracle-10.7-InventoryOrg

Peoplesoft-BusinessUnit

Peoplesoft-GLBusinessUnit

Peoplesoft-DeliverToSetId

Peoplesoft-DeliverTo

Peoplesoft-ShipToSetId

Peoplesoft-ShipTo

Peoplesoft-DeptSetId

Peoplesoft-Dept

SAP-ShipTo

SAP-CostCenter

SAP-PurchaseOrg

SAP-CompanyCode

SAP-PurchaseGroup

SAP-Plant


Parameters for Line Item Split Accounting Chapter 15 Accounting Information

Parameters for Line Item Split Accounting

To configure line item split accounting, you must set up the following parameters in the config/Parameters.table file:

Because the split accounting parameters are partition-specific, you must make these changes for each partition in your configuration.

SplitAccountingTypePull Integration Event

You use the SplitAccountingTypePull integration event to configure Ariba Buyer to specify the details of your split accounting support. The SplitAccountingTypePull integration event reads partitioned data.

SplitAccountingType Fields

Ariba Buyer supplies one implementation of this integration event, which reads from a CSV file. A typical configuration always reads split accounting data from a CSV file.

Parameter Description

Application.Approvable.AllowSplitAccounting

This parameter is a Boolean that enables or disables split accounting.

Application.Approvable.MaxAccountingSplits

This is a performance tuning parameter that specifies the maximum number of splits allowed for a given line item. In the default configuration, this parameter is set to 99. When you set this parameter, keep in mind that:

• SAP has a limit of 99 splits. If you are integrating with SAP, you must choose a value less than 99.

• Electronic Data Interchange (EDI) has a limit of 25 splits. If you are sending orders to a supplier with EDI, you must choose a value less than 25.

Chapter 15 Accounting Information SplitAccountingTypePull Integration Event


In the default configuration, this integration event reads data from the following file:

config/variants/variant/partitions/partition/data/SplitAccountingType.csv

The fields in SplitAccountingType.csv are as follows:

Ariba Buyer requires that you define these three standard split types: _Amount, _Percentage, and _Quantity. You can adjust the properties for any of these split types, but you must make sure that all three are defined.

The following example shows lines from a typical version of SplitAccountingType.csv:

"UniqueName","Name","PrecisionString","IsDefaultType","IsPickable""_Amount","Amount","5",false,true"_Percentage","Percentage","5",true,true"_Quantity","Quantity","5",false,true

Field Description

UniqueName A unique identifier for an entry. The UniqueName must be _Amount, _Percentage, or _Quantity. The leading underscore indicates that these are reserved words and must appear exactly as shown here. Any other UniqueName causes an error.

Name A name that corresponds to this UniqueName, such as “Percentage”. The name is the name that users see, in the user interface. You can define any Name you like.

Precision An integer that specifies how many digits of precision to retain when making splits.

IsDefaultType A Boolean that indicates which kind of split should be the default, in the user interface. There must be only one entry with IsDefaultType set to true.

IsPickable A Boolean that indicates whether this split type is visible to the user. You set this field to false to define an accounting split type (so that the precision information is available to the underlying ERP) but not make it available to users as a choice.


AccountTypePull Integration Event Chapter 15 Accounting Information

AccountTypePull Integration Event

An account type (sometimes called an account category) is a way of grouping accounts. Common examples of account types are Expense, Revenues, and Capital.

You define the set of account types for your configuration with the AccountTypePull integration event.

The AccountTypePull integration event reads global data, shared among all partitions.

The default configuration supplies one version of this integration event, which reads from a CSV file.

AccountType Fields

In the default configuration, the AccountTypePull integration event reads from the following file:

config/variants/Plain/partitions/None/data/AccountType.csv

The fields in AccountType.csv are as follows:

Field Description

UniqueName The unique identifier for an Account Type.

Name The user-visible name for this UniqueName.

Description A comment or descriptive text.

Chapter 15 Accounting Information Account Validation


The following example shows lines from a typical AccountType.csv file:

"UniqueName","Name","Description""Expense","Expense","""Lease","Lease","""Capital","Capital",""

Account Types for Catalog Items

Account types are associated with catalog items, and are part of the required information for a catalog item. The account types for catalog items are defaulted from the commodity code. For example, you can specify that all items with the commodity code “EQUIP” have the account type Capital.

Some catalog items can potentially have multiple account types (for example, Expense or Capital), and the user must choose which is appropriate.

Account Validation

To disable account validation, set the validity condition on your accounting fields to ariba.common.core.condition.ActiveClusterRoot and the name table to ariba.common.core.nametable.NamedObjectNameTable. For example:

<!DOCTYPE extension SYSTEM "../../../../ariba/base/meta/core/extensions.dtd"><extension name="config.variants.voracle.extensions.NoAccountingValidation">

<import extension="ariba.variants.Plain.extensions.CoreExt"/><import extension="ariba.variants.Plain.extensions.ClassDecl"/><import extension="ariba.variants.voracle.extensions.OracleVariants"/><import extension="ariba.variants.voracle.extensions.OracleCoreExt"/><inModule name="ariba.common.meta.Core">

<inClass name="ariba.common.core.Accounting"><inClassVariant name="voracle">

<inField name="CostCenter"><validity

clusterType="ariba.approvable.core.LineItemCollection<condition

implementation="ariba.common.core.condition.ActiveClusterRoot"/></validity>

<properties nameTableClass="ariba.common.core.nametable.NamedObjectNameTable"/>

</inField>....

</inClassVariant>


AccountingCombinationPull Integration Event Chapter 15 Accounting Information

</inClass></inModule>

</extension>

AccountingCombinationPull Integration Event

The AccountingCombinationPull integration event lists every valid combination of accounting entities, for your corporation’s accounting entities. The AccountingCombinationPull integration event loads data into a partition.

Ariba Buyer supplies implementations that read from ERP systems and from a CSV file. Typically, you use this integration event only to support existing account combination validation in an ERP system. It’s unusual to create a standalone version that reads from a CSV file. A typical configuration either turns off accounting combination altogether, or reads the underlying data from an ERP system.

The accounting combination data must specify every valid pair of accounting entities.

The following example illustrates a configuration with two regions, EastCoast and WestCoast and four cost centers. There are only two cost centers (2311 and 2312) that are valid in the EastCoast and two (4000 and 4100) that are valid in the WestCoast.

EastCoast,2311EastCoast,2312WestCoast,4000WestCoast,4100

Chapter 15 Accounting Information Metadata XML for Accounting Combinations


Metadata XML for Accounting Combinations

When you enable accounting combination validation, Ariba Buyer checks the accounting combinations in the user interface, as the user sets up accounting information.

For example, if a user chooses EastCoast as the region, Ariba Buyer offers only the cost centers that are valid in that region. If the user creates a combination that’s invalid, Ariba Buyer reports the error in the user interface, and asks the user to make corrections.

You define which fields trigger the validation by adding the accountingCombination property to the metadata XML for that field. The value of this property is an accounting entity in the AccountingCombinationPull integration event. For example:

<field name="SubAccount"respectable="true"nullAllowed="true"><type class="ariba.core.SubAccount"/><propertieslabel="@aml.csv.OracleCoreExt/UserProfileDetailsSubAccountLabel"rank="100"nameTableClass="ariba.csv.common.OracleAccountingNameTable"accountingCombination="SubAccount"titleField="SubAccountDescription"chooserField="SubAccountDescription"allowNullValue="true"metaDataIntegration="Reference"/>

</field>

In the default Ariba Buyer configuration, Ariba Buyer provides an implementation of accounting combinations for Oracle that provides account combination validation on Oracle accounting fields. For the metadata XML configuration associated with this implementation, see the file OracleCoreExt.aml.


Default Accounting Information Chapter 15 Accounting Information

Default Accounting Information

When a user copies a line item, or an approvable document, Ariba Buyer uses trigger events to copy appropriate default information onto the new line items.

This section describes how Ariba Buyer uses these triggers to default accounting information. It assumes you are familiar with how to use triggers, as described in the Ariba Buyer Customization Guide.

Defaulting Shipping Address

The trigger action PropagateDefaultShipping copies default shipping information from the header of a purchase requisition onto each line item of the requisition. If the user makes changes to the shipping information, this trigger propagates those changes to the individual line items. It uses a group to decide which fields are copied, In the default configuration, that group is the ShippingFields group.

The following example shows the PropagateDefaultShippingOnChange trigger, as it is defined in the default configuration:

<trigger name="PropagateDefaultShippingOnChange"event="DefaultShippingChanged"respectUserData="false">

<action implementation="ariba.procure.core.action.PropagateDefaultShipping">

<parameter name="TargetGroup" value="ShippingFields"/></action>

</trigger>

If you add extrinsics to the header of a purchase requisition, and want changes to those extrinsics to be copied onto individual line items, do the following:

• Add the extrinsics to the ShippingFields group.

• Set respectable=true on the fields you want to have copied. This attribute tells Ariba Buyer to keep track of when a field has changed. For more information, see the Ariba Buyer Customization Guide.

Chapter 15 Accounting Information Default Accounting Information


Defaulting from the Requester

In the default configuration, Ariba Buyer associates two triggers with ProcureLineItem:

• DefaultProcureLineItemFromApprovable, which copies accounting information from the requisition header onto individual line items

• DefaultProcureLineItemFromRequester, which copies the user’s default accounting information onto individual line items

These triggers copy default accounting information from the Requester’s default profile onto the individual line items of a requisition. If a user changes the Requester field on a purchase requisition, the default accounting information for the new user is copied onto each line item of the requisition. This change is done with two trigger actions:

• The first copies data from User onto the defaultLineItem field of the LineItemCollection.

• Then, for each line item added to the collection, the DefaultFromApprovable trigger event is fired to initiate defaulting from the approvable onto the line item.

The fields that are copied in this situation are defined by the ObjectDefaulting group. In the default Ariba Buyer configuration, the ObjectDefaulting group includes the following fields:

• User.ShipTo

• User

• DeliverTo

• ProcureLineItem.ShipTo

• ProcureLineItem.DeliverTo

• ProcureLineItem.NeedBy

It also includes all the variant-specific fields for each Accounting object.

If there is additional accounting information that you would like to have copied onto the line item, add extrinsics to the ObjectDefaulting group. If there are fields in the default configuration that you prefer not have copied, remove those fields from the ObjectDefaulting group.


Default Accounting Information Chapter 15 Accounting Information

The following example shows an excerpt of the metadata XML file in the default configuration that defines the defaulting behavior for requisitions:

<class name="ariba.procure.core.ProcureLineItem"prefix="pli"super="ariba.approvable.core.LineItem">

.....<trigger name="DefaultProcureLineItemFromApprovable"event="DefaultFromApprovable"respectUserData="true">

<action implementation="ariba.common.core.action.CopyFields"><parameter name="SourcePath" value="DefaultLineItem"/><parameter name="SourceGroup" value="ObjectDefaulting"/><parameter name="Defaulting" value="true"/>

</action>

<action implementation="ariba.common.core.action.CopyFields"><parameter name="SourcePath"

value="DefaultProcureLineItem.Accountings.SplitAccountings"/><parameter name="SourceGroup" value="ObjectDefaulting"/><parameter name="Target" fieldPath="Accountings.SplitAccountings"/><parameter name="Defaulting"value="true"/>

</action></trigger>

<trigger name="DefaultProcureLineItemFromRequester"event="DefaultFromRequester"respectUserData="true">

<action implementation="ariba.common.core.action.CopyFields"><parameter name="SourceGroup" value="ObjectDefaulting"/><parameter name="Defaulting" value="true"/>

</action>

<action implementation="ariba.common.core.action.CopyFields"><parameter name="SourcePath" value="Accounting"/><parameter name="SourceGroup" value="ObjectDefaulting"/><parameter name="Target" fieldPath="Accountings.SplitAccountings"/><parameter name="Defaulting" value="true"/>

</action>

</trigger>

Chapter 15 Accounting Information Default Accounting Information



Chapter 16

Supplier Data

This chapter describes how to load supplier data into Ariba Buyer, and also how to extend supplier data with extrinsics. It includes the following sections:

• “Introduction to Supplier Data” on page 217

• “How Supplier Data Is Created” on page 221

• “Suppliers and Common Suppliers” on page 232

• “Supplier Location Verification” on page 239

Introduction to Supplier Data

A supplier is an organization that provides goods or services.

Supplier data is essential to the process of creating requisitions and sending orders. You can load your initial supplier data either form a data source such as an ERP, or by pulling from Ariba Supplier Network (Ariba SN).

Ariba Buyer uses supplier data in the following ways:

• Every item in the catalog must have an associated supplier. The supplier object must exist in Ariba Buyer.

• Every order that is sent from Ariba Buyer must be sent to a specific supplier. To send an order, Ariba Buyer must have contact information for that supplier.

• If the user chooses a non-catalog item, a purchasing manager or other administrator must designated a suggested supplier for that item, by choosing from the list of available suppliers.

Each supplier has associated profile information that includes information such as the supplier’s preferred method for receiving orders, preferred payment method, and preferred billing address.

Chapter 16 Supplier Data Introduction to Supplier Data


Suppliers and Supplier Locations

A supplier is a company that provides goods or services, and a given supplier might have more than one physical location. When Ariba Buyer sends an order to a supplier, that order goes to one specific location. For example, if your corporation is based in Germany, and your supplier has branch offices in France and in Japan, you probably send your orders to France, not Japan.

Ariba Buyer represents suppliers with two related objects:

• A supplier is a company, such as Acme Corporation.

• A supplier location is a physical location for a company.

When you define your supplier data, you create a list of suppliers and also a list of supplier locations for each of those suppliers. Each supplier location has its own contact information, which defines where orders are sent.

Common Suppliers

In Ariba Buyer, suppliers are partitioned objects. Each partition has its own set of suppliers. Sometimes the suppliers in different partitions should logically be linked together. For example, you might have a supplier with a European branch and an American branch. Although you represent those suppliers in both partitions, you typically want to treat the supplier as a single entity when negotiating pricing and bulk agreements.

Ariba Buyer defines a CommonSupplier object to act as an umbrella to link together suppliers in different partitions that represent the same real-world supplier. Common suppliers are not partitioned. Every partitioned supplier must be grouped under exactly one common supplier. Common suppliers do not have to have any associated partitioned suppliers, however. For example, a common supplier might represent supplier users from Ariba Enterprise Sourcing.


Introduction to Supplier Data Chapter 16 Supplier Data

The following diagram shows the relationship between a common supplier, a partitioned supplier, and a supplier location:

In this diagram, the supplier “Acme” exists in two partitions: European HQ and North American HQ. The two partitioned suppliers are linked together under a single common supplier.

IDs for Suppliers

Each supplier has an organization ID that uniquely identifies that supplier. Different partitions can use different numbering systems for supplier IDs, but each common supplier must be uniquely identified by one unique organization ID.

Supplier LocationName: Acme, Inc.Location: Vermont

(North American HQ)

Supplier LocationName: Acme, Inc.Location: Maine

(North American HQ)

Partitioned SupplierName: Acme, Inc.

Partition = North American HQ


Partition = European HQ

Common SupplierName: Acme, Inc.

(unpartitioned)

Chapter 16 Supplier Data Introduction to Supplier Data


To accommodate different schemes for generating IDs, Ariba Buyer represents an organization ID as a domain and value pair, where the domain is the naming system and the value is the organization’s ID in that system. For example, the following examples might both represent valid organization IDs:

Suppliers who have accounts on Ariba Supplier Network also have Ariba Network IDs, which are stored as part of the supplier profile information. When sending an order to Ariba SN, Ariba Buyer sends the D-U-N-S ID (if there is one) and otherwise the Ariba Network ID.

Ariba Buyer uses the supplier’s organization ID to determine which partitioned suppliers to group together under a given common supplier. The diagram below illustrates a configuration with two partitions: A and B. The suppliers in partition A use D-U-N-S IDs, and the suppliers in partition B use internal IDs. The common supplier includes both IDs.

Example Description

{DUNS, 12-345-6789} An ID that uses Dun and Bradstreet’s D-U-N-S® naming system.

{partition-psoft, MFG:0000000001} An ID for a PeopleSoft partition, which creates the ID from the PeopleSoft SETID and Vendor ID.


Partition = BInternal Supplier ID: ZYX


Partition = ADUNS ID: 123

Common SupplierName: Acme, Inc.

Internal Supplier ID: ZYXDUNS ID: 123(unpartitioned)


How Supplier Data Is Created Chapter 16 Supplier Data

The IDs determine which partitioned suppliers are grouped under the common supplier. If you want to change the association between partitioned supplier and common supplier, you can change the IDs using Ariba Buyer Administrator. For more information, see “Relinking a Partitioned Supplier from Another Common Supplier” on page 235.

Supplier IDs are created by the integration event that loads supplier data. For example, for suppliers read in from an ERP system, the supplier ID is created by the integration event that loads the supplier, using the supplier’s ERP ID. For more information on how supplier IDs are assigned, see “Assigning IDs to New Suppliers” on page 232.

How Supplier Data Is Created

In a typical configuration, each partition has a set of suppliers, read from an ERP system, or comma-separated value (CSV) file, through an integration event. Suppliers used for Ariba SN are defined in Supplier Direct partition.

To create supplier data in Ariba Buyer, you can use the following methods:

• Loading data through integration events. You typically use this technique for data read into a partition, either from an ERP system or from a CSV file.

• Loading data from Ariba SN. If a catalog on Ariba SN references a supplier that is not yet defined in Ariba Buyer, you must load the supplier profile for that supplier before you can complete the catalog load.

• Entering data manually, from Ariba Buyer Administrator. You typically do this only temporarily, or for error recovery.

If you integrated Ariba Buyer with Ariba Enterprise Sourcing, you might occasionally need to add new suppliers to your Ariba Buyer configuration as the result of sourcing events. Suppliers that exist in Ariba Enterprise Sourcing, but do not exist in Ariba Buyer, are referred to as unknown suppliers. For information on loading unknown suppliers, see the Ariba Contract Compliance Guide.

This section describes how you can load and update supplier data in Ariba Buyer.

Chapter 16 Supplier Data How Supplier Data Is Created


Loading Suppliers through Integration Events

In a typical configuration, you read basic supplier data from an ERP system, and then supplement that data with additional Ariba Buyer-specific information, such as data about the supplier’s preferred ordering methods and rules for purchasing card use.

In the default configuration, Ariba Buyer loads supplier information with two integration events, one that reads data typically found in an ERP and the other that reads data typically used only in Ariba Buyer.

The integration events used in the default configuration are as follows:

• The SupplierPull integration event, which loads a list of supplier names and supplier location names, either from an ERP system or from a file.

• The SupplierLocationSupplementPull integration event, which loads Ariba Buyer-specific information, such as data about the supplier’s preferred order methods.

There are also corresponding export events:

• SupplierExport

• SupplierLocationExport

• SupplierLocationSupplementExport

Export events allow you to export data to CSV files, through the Ariba File Channel.

This section describes the integration events for loading and exporting supplier data.

SupplierPull Integration Event

The SupplierPull integration event reads from two data sources: one that defines a list of suppliers, and one that defines supplier location information for each of those suppliers.

Ariba Buyer provides two implementations of the SupplierPull integration event: one that uses the TIBCO integration channel, and one that uses the Ariba File Channel. Most configurations use the TIBCO implementation.



Supplier Data Source

In the default configuration, the SupplierPull integration event for the Ariba File Channel reads supplier data from the following file:

config/variants/variant/partitions/partition/data/Supplier.csv

The fields in the Supplier.csv file are as follows:

The following lines are from a typical Supplier.csv file:

"UniqueName","Name","CorporateURL",”PaymentTerms”"1","Acme, Inc","http://www.acme.com",PT1"2","Premium Manufacturing, Inc.",PT1"3","Dysarts Trucking","http://www.dysarts.com",PT1

In this example, the UniqueName values are integers.

In a configuration where the suppliers originate from an ERP system, the UniqueName values are typically derived from data in the ERP. For example, in PeopleSoft, vendors are not necessarily unique across SETIDs. Therefore, in PeopleSoft configurations, Ariba Buyer concatenates the SETID with the Vendor ID to create a unique identifier for each supplier, such as the following:

MFG:0000000001HC:0000000001

Field Description

UniqueName A unique identifier for this supplier, which must be unique within the partition.

Name The name of this supplier as it appears when presented to the user.

CorporateURL A URL associated with this supplier, such as http://www.acme.com. The CorporateURL field is optional.

PaymentTerms Specifies the unique name of a payment term defined in the PaymentTerms.csv file. For more information on payment terms, see the Ariba Settlement Guide.



Supplier Location Data Source

The supplier location data source provides a list of supplier locations for each supplier. For every supplier in your list of suppliers, you must have one or more entries in the supplier locations list. Each entry includes an address and the name of a contact person at that location. To have entries for several different contacts, you include multiple lines for each location.

Each supplier location has a unique name, a Customer ID (which links the location to a supplier), and a Contact ID. The contact ID identifies a specific individual within the supplier location. Usually you have one line in the supplier locations list for each supplier location, each with the same Customer ID and different unique names. If you also have different contacts within the same location, you can use the contact ID to differentiate between the locations.

In the default configuration, the SupplierPull integration event for the Ariba File Channel reads supplier location data from the following file:

config/variants/variant/partitions/partition/data/SupplierLocation.csv

The fields in the SupplierLocation.csv file are as follows:

Field Description

UniqueName A unique identifier for this supplier location.

Name The name for this supplier location, as it appears in the user interface.

CustomerID The UniqueName of a supplier, which ties this location to a relevant supplier. Must match the UniqueName of a supplier, as defined by your SupplierPull integration event.

ContactID An ID for a contact person at this supplier location.

If a given supplier location has two distinct contacts, you have two entries for that supplier location with the same UniqueName, but different ContactIDs. For example:

UniqueName,Name,CustomerID,ContactID,Contact, ..."5","Ariba--Salt Lake","4","7","Amanda Dufur",..."5","Ariba--Salt Lake","4","6","Larry Johnstone",...

Contact The contact name to match a ContactID, used for display purposes.

Lines Street address for this location.



The following lines are from a typical SupplierLocation.csv file:

"UniqueName","Name","CustomerID","ContactID","Contact","Lines","City","State","PostalCode","Country","Phone","Fax","EmailAddress""1","Victoria Zenger : SACRAMENTO","1","1","Victoria Zenger","111 Main Street","Sacramento","CA","99999","SU","(916)555-1234","+1 (408) 333-4321","""2","James Thomas : RENO","2","2","James Thomas","123 Hudson Street","Reno","NE","60000-9999","US","(312)333-9876","+1 (408)344-4567",""

City Standard address information for this location.

State Standard address information for this location.

PostalCode ZIP code or postal code for this location.

Country The unique name of the country where this address is located. The value must match the unique name of a country defined by your CountryPull integration event. The Country field determines the locale for this supplier location, and uses the locale to choose the language for communicating with the supplier location.

For more information on languages, countries, and locales, see Chapter 7, “Languages, Countries, and Locales.”

Phone The phone number, which is treated as a string. You can enter the phone number with or without punctuation such as “-”.

Fax The fax number, which must be in the format +1 (408) 543-4180 or +1 408 543-4180. For backward compatibility, in the United States and Canada only, you can omit the prefix +1area code in local numbers (for example, 5551212) and add the prefix 011 in international numbers (for example, 0116505551212).

EmailAddress An email address for this supplier, using the format acceptable to your mailer.




If more than one supplier location exists for a given supplier, Ariba Buyer uses the trigger SetSupplierLocationOnSupplierChange to choose a supplier location for each requisition. In the default configuration, this trigger calls the action implementation SetSupplierLocation.java, which implements the following logic:

• Look through the supplier locations, in order. If any supplier location has a preferred order method defined, then use that location and stop looking.

• If no location has a preferred order method defined, then look at the ZIP codes of the supplier locations and the requester and pick the supplier location that appears to be closest, based on ZIP codes.

You can customize this logic by subclassing the trigger implementation with a custom Java class. For more information on triggers, see the Ariba Buyer Customization Guide.

Ariba Buyer provides several ways to validate supplier location information, to ensure that Ariba Buyer does not try to send orders to invalid locations. For information on validating supplier locations, see “Validation at Submission” on page 241.

Supplier Export Events

The default configuration supplies two export events, SupplierExport and SupplierLocationExport, which write supplier data to CSV files. In the default configuration, these export integration event write to the following files:

config/variants/Plain/partitions/None/data/Supplier_Export.csv config/variants/Plain/partitions/None/data/SupplierLocation_Export.csv

For more information on export events, see Chapter 4, “Ariba File Channel.”

SupplierLocationSupplementPull Integration Event

The SupplierLocationSupplementPull integration event loads information about each supplier location, including its preferences for ordering methods and purchasing card usage. This information supplements the supplier location information defined by the SupplierPull integration event.

Ariba Buyer provides two implementations of the SupplierLocationSupplementPull integration event: one that uses the TIBCO integration channel, and one that uses the Ariba File Channel. Most configurations read this data from a CSV file, as this data is not typically available from an ERP system.



In the default configuration, the SupplierLocationSupplementPull integration event reads supplemental supplier location data from the following file:

config/variants/variant/partitions/partition/data/SupplierLocationSupplement.csv

The fields in SupplierLocationSupplement.csv are as follows:

Field Description

UniqueName Used to link this information to a supplier location. the value must match a UniqueName defined by your SupplierPull integration event.

ContactID The ContactID of a supplier location, which must match a ContactID for the specified supplier in the SupplierLocation list. The combination of UniqueName and ContactID identifies a supplier location.

PreferredOrderingMethod The preferred method for sending orders to this supplier. The value must be one of the following:

• Print• Fax• Email• Silent

• URL (for Ariba SN orders)

These values are case-sensitive and must be capitalized exactly as shown. For more information, see the Ariba Buyer Procurement Guide.

PCardAcceptanceLevel An integer that indicates whether this supplier accepts purchasing cards as a payment vehicle. The possible values for this field are as follows:

0 This supplier does not accept purchasing cards.

1 This supplier accepts purchasing cards, but does not include the Ariba DO number on statements.

2 This supplier accepts purchasing cards and includes the Ariba DO number on the packing slip.

For more information on setting up purchasing cards, see the Ariba Buyer Procurement Guide.



The following lines are from a typical SupplierLocationSupplement.csv file:

1,1,Email,1,,,,,PT136,34,Fax,1,1234567890222222,,,,PT181,75,Print,0,,,,,PT1

These lines define one supplier location with a ghost purchasing card.

GhostPCardNumber Defines a purchasing card (PCard) used for orders to this supplier location. The PCard number must match one defined by your PCardPull integration event.

ChangeOrderRestrictions An integer that indicates whether this supplier location accepts change orders. The value must be one of the following:

0 This supplier accepts change orders.

1 This supplier does not accept change orders.

For more information on change orders, see the Ariba Buyer Procurement Guide.

AribaNetworkID The Ariba SN ID for this supplier location. If you plan to send orders to this supplier through Ariba SN, you must make sure that the Ariba SN ID is defined correctly. Ariba Buyer uses this field as a unique ID to identify the supplier when contacting Ariba SN.

SplitOrderOnShipTo A Boolean that indicates whether this supplier can handle line items aggregated onto an order if those line items have different ship-to addresses. The default is false, which indicates that the supplier can accept multiple ship-to addresses on an order. If you set this field to true, Ariba Buyer creates separate orders for each ship-to address.

For more information on how requisitions are split into orders, see the Ariba Buyer Procurement Guide.

PaymentTerms Specifies the unique name of a payment term defined in the PaymentTerms.csv file. For more information, see the Ariba Settlement Guide.




SupplierLocationSupplementExport Event

The default configuration supplies a corresponding export event, SupplierLocationSupplementExport, which writes supplier location supplement information to a CSV file. In the default configuration, this export event writes to the following file:

config/variants/Plain/partitions/None/data/SupplierLocationSupplement_Export.csv


Loading Suppliers from Ariba SN

Many suppliers maintain supplier profile information on Ariba SN. Ariba Buyer includes scheduled tasks that you can use to load initial profile information from Ariba SN, and to update supplier information if the supplier changes a profile.

To download supplier profile information from Ariba SN, Ariba Buyer provides the following scheduled tasks:

• AribaNetworkOrganizationSync, which checks your Ariba Buyer configuration for suppliers that have Ariba Network IDs or D-U-N-S IDs, and asks Ariba SN to send current profile information for those suppliers.

• CommonSupplierSyncUsingSupplierLocationID, which is similar to AribaNetworkOrganizationSync, but designed for situations where a supplier has different Ariba SN IDS for different supplier locations.

• GetPendingAribaNetworkOrganizationSync, which polls Ariba SN for changes that have been made since the last sync (with either AribaNetworkOrganizationSync or CommonSupplierSyncUsingSupplierLocationID), and downloads those updates.

In the default configuration, none of these tasks is scheduled to run on a regular basis. Typically an administrator runs these tasks on demand, as appropriate, to download profile information for all Ariba SN suppliers.



The “sync” tasks recognize two parameters:

• A performance-tuning parameter, which determines the batch size of updates. You can adjust this parameter to adjust the balance between network traffic (smaller batch size).

• A Boolean parameter that specifies which suppliers are updated. By default, the tasks update supplier profile information for any supplier who has either an Ariba SN ID or a D-U-N-S number. If you maintain some supplier information from ERPs, and want to update only the information for suppliers who have Ariba Network IDs, you can set this parameter.

For complete information on the available parameters, see the Ariba Buyer Configuration Reference Guide.

Creating Suppliers During Catalog Load

When you synchronize with Ariba SN to download new catalogs, Ariba Buyer checks each incoming catalog to make sure the suppliers in the catalog are defined in Ariba Buyer. If a catalog includes a supplier not yet defined in Ariba Buyer, the catalog load process requests a copy of the supplier profile for that supplier from Ariba SN.

Your catalog administrator must ensure that the supplier is defined in Ariba Buyer before the catalog load process can continue. The process is as follows:

1 The AribaNetworkFullSubscriptionSync scheduled task runs, either manually or on a schedule, to receive catalog updates from Ariba SN. For more information on this scheduled task, see the Ariba Buyer Catalog Guide.

2 If a catalog on Ariba SN references a supplier that is not defined in your Ariba Buyer configuration, Ariba Buyer requests the supplier profile for that supplier from Ariba SN.

3 Ariba Buyer sends Notification 59, “Notification of Unknown Supplier,” to users who have the permission to users who have the permission SupplierManager.

4 If Ariba SN included a profile for the new supplier, the notification message includes that supplier profile as an attachment.

5 The Supplier Manager reviews the suggested supplier profile.



6 The Supplier Manager performs the following tasks in Ariba Buyer Administrator:

a The Supplier Manager chooses Server Manager > Config Files and uploads the attached supplier profile into the following file:

config/variants/Plain/partitions/supplierdirect/data/NewSupplier.xml

Suppliers for catalog items from Ariba SN are loaded into the Supplier Direct partition. Using Supplier Direct means that the supplier profile is not overwritten by an integration event, as might be the case in other partitions.

b The Supplier Manager chooses Server Manager > Integration Events and runs the integration event SupplierXMLPull from the Supplier Direct partition.

This integration event reads the XML file NewSupplier.xml, and adds the new supplier to the Supplier Direct partition.

7 The scheduled task UpdateSupplierPendingItems runs. This scheduled task checks all pending unknown suppliers. If the supplier now exists in Ariba Buyer, the scheduled task updates the pending catalog tracker item, so that the catalog update can continue successfully.

If the Supplier Manager does not add the supplier within the time limit specified by System.Procure.PendingUnknownSupplierOverdueLimitInDays, the UpdateSupplierPendingItems task sends Notification 60, “Notification of Overdue Unknown Supplier Resolution,” as a reminder.

For more information, see the description of the UpdateSupplierPendingItems scheduled task in the Ariba Buyer Configuration Reference Guide.

In the default configuration, catalog items are restricted by partition. Users can see only catalog items for suppliers defined in the partition where they are logged in. Suppliers in the Supplier Direct partition are visible to users in all partitions.

To set up your configuration so that catalog items from suppliers in the Supplier Direct partition are not visible to users in other partitions, set the System.Procure.ExcludeSupplierDirectCatalogItems parameter to true. For more information on the visibility of catalog items by partition, see the Ariba Buyer Catalog Guide.

Chapter 16 Supplier Data Suppliers and Common Suppliers


Suppliers and Common Suppliers

This section describes how you can adjust your configuration if the partitioned suppliers and common suppliers are not linked together correctly. For example, you might want to link two partitioned suppliers under one common supplier to set up the correct supplier relationship.

In general, you administer supplier information from the Supplier Manager in Ariba Buyer Administrator.

Assigning IDs to New Suppliers

Whenever a supplier is loaded into Ariba Buyer, the supplier load process assigns a unique identifier (a supplier organization ID) for that supplier. The process for choosing the ID depends on how the supplier is created:

• When you load suppliers from an integration event, the suppliers are created within a partition. The partition determines the naming convention for the unique ID. For example, in a PeopleSoft partition, suppliers might have IDs of the form {partition-psoft, 543231}. The domain portion of the name (partition-psoft) is defined in the integration event that loads the suppliers (for example, the TIBCO worksheet, if you are using TIBCO as your integration channel).

• When you load suppliers from Ariba SN, the IDs are defined by Ariba SN and are included in the cXML document that is downloaded.

• When you add suppliers manually from Ariba Buyer Administrator, the supplier is created in the partition in which you are currently logged in, and you must define an ID that is acceptable for that partition.


Suppliers and Common Suppliers Chapter 16 Supplier Data

The following diagram illustrates supplier data read from different data sources, with different ID domains in each partition. The common supplier shares the IDs from the different partitions.

Linking Suppliers and Common Suppliers

Whenever you add a new supplier, Ariba Buyer checks the organization ID of that supplier, to see if it matches an existing common supplier. If the common supplier already exists, Ariba Buyer links the new supplier to the existing common supplier. If the common supplier does not yet exist, Ariba Buyer creates one as follows:

• If you are loading supplier data from an integration event, Ariba Buyer always creates a new common supplier and links the new supplier to the new common supplier.

• If you are creating a supplier manually from Ariba Buyer Administrator, you create both a common supplier and a partitioned supplier.

Supplier

part-psoft 709

ID list

Supplier Location

psoft partition

Supplier

partition-sap: 102

ID list

Supplier Location

sap partition

Common Supplier

DUNS: 123456InternalSupplierId: 5partion-sap: 102partition-psoft: 709

SupplierDUNS: 123456

InternalSupplierId; 5

ID list

Supplier Location

supplierdirect

ERP Partition Suppliers SupplierDirect Suppliers



Bulk Loading

If you are making a configuration change that involves a large number of additions to suppliers and common suppliers, you can use the SupplierOrganizationPull or the CommonSupplierIDMapPull integration event. This integration event allows you to add supplier IDs to existing common suppliers or create a list of new common suppliers from an integration event, without requiring an administrator to make all changes in the user interface.

For more information, see “Creating Common Suppliers in Bulk” on page 236.

Catalog Index Rebuilds

To improve search performance and reduce the size of queries, Ariba Buyer indexes the partitions where a supplier is available and requests those partitions each time the user does a catalog search.

If you add a new supplier to an existing common supplier, you must rebuild the catalog index, either with the Index Builder task in Ariba Buyer Administrator or the ReindexSearchIndex task.

For more information, see the Ariba Buyer Catalog Guide.

Using the Supplier Manager

You use the Supplier Manager in Ariba Buyer Administrator to manage your supplier configuration. You can use the Supplier Manager to link and unlink suppliers, and adjust other supplier profile data.

You can also use the Supplier Manager to load and edit the information for a supplier. If you edit values for a supplier that originated from an integration event, Ariba Buyer Administrator warns you that your changes will be overwritten the next time you run that integration event. To make changes to a supplier that originated from an integration event, you must make your changes in original data source (ERP or CSV file), and then rerun the integration event.

This section summarizes some of the common tasks you can perform from Ariba Buyer Administrator. For complete information, see the Ariba Buyer Administrator online help.



Creating a Common Supplier

Although common suppliers are usually created indirectly, as part of creating a supplier, you can also use Ariba Buyer Administrator to create a new common supplier.

s To add a common supplier:

1 In Ariba Buyer Administrator, choose Supplier Manager > Suppliers.

2 On the Suppliers screen, click Create New.

3 Choose an adapter source and enter a unique name and name. You can also optionally enter a corporate URL or catalog URL.

Note: If you support PunchOut with this supplier, make sure to enter the PunchOut URL in the catalog URL field.

4 In the Organization IDs section, click Create New.

5 Choose a domain, and then type the organization ID for that domain in the Value text box.

6 In the Partitioned Suppliers section, click Create New to create a new partitioned supplier, or choose Relink from another Common Supplier to associate an existing partitioned supplier with this new common supplier.

You must add at least one partition-specific supplier to each common supplier. If there are no linked partitioned suppliers, catalog items for that supplier cannot be displayed to users.

For more information on adding suppliers through Ariba Buyer Administrator, see the Ariba Buyer Administrator online help.

Relinking a Partitioned Supplier from Another Common Supplier

You can merge two common suppliers by moving the partitioned suppliers from one common supplier to another common supplier. Before you do this, you must make sure that the IDs for the partitioned suppliers are in different domains. For example, if you have a partitioned supplier with a D-U-N-S ID and try to link it to a common supplier that already has a D-U-N-S ID, Ariba Buyer Administrator reports an error and prevents the merge.



s To link a partitioned supplier to another common supplier:

1 In Ariba Buyer Administrator, choose Supplier Manager > Suppliers.

2 On the Suppliers page, search for the common supplier to which you want to move the partitioned supplier, choose that common supplier, and then click Edit.

3 On the Suppliers - Edit Common Supplier page, click Relink from another Common Supplier.

4 On the Suppliers- Choose Partitioned Supplier to Relink page, search for the partitioned supplier you want to move to the common supplier, and then click Select.

5 On the Confirm Partitioned Supplier to Relink page, click OK.

The Supplier Manager checks for any “siblings” with the same ID. If it finds a sibling, the move automatically includes all suppliers with matching IDs.

6 On the Suppliers - Edit Common Supplier screen, click Save.

After a relink, you typically have a common supplier with no associated suppliers. In this case, Ariba Buyer Administrator removes the “empty” common supplier from the common supplier list.

For more information, see the Ariba Buyer Administrator online help.

Creating Common Suppliers in Bulk

If you manage your suppliers entirely within Ariba Buyer, you use the Supplier Manager as your primary tool for adjusting supplier/common supplier mappings.

If you manage your suppliers outside of Ariba Buyer, and load them into Ariba Buyer with integration events, you can use an integration event called the CommonSupplierIDMapPull integration event to help manage the mapping between suppliers and common suppliers.

CommonSupplierIDMapPull Integration Event

The CommonSupplierIDMapPull integration event defines a mapping between partitioned suppliers and common suppliers. You use this integration event to “bulk load” the supplier matching process across partitions by specifying a set of supplier organization IDs that must be joined together under a single common supplier. For



example, you might choose to use this integration event if you load suppliers from different ERP systems, and need to make sure those suppliers are linked together under the same common supplier.

The CommonSupplierIDMapPull integration event is appropriate only for situations where you are loading a large number of new suppliers and want to make sure the links between those suppliers and their common suppliers are set up properly. For situations where you just want to adjust a few existing links, use the Supplier Manager instead.

The CommonSupplierIDMapPull integration event reads two CSV files: one that defines a set of common suppliers and another that defines which suppliers must be mapped to those common suppliers. It uses a join token to indicate which suppliers must be linked together under a given common supplier. The join token is used only temporarily, by this integration event, and isn’t used anywhere else in your configuration. You can use any join tokens you like, as long as they are distinct from one another.

Ariba Buyer supplies one implementation of the CommonSupplierIDMapPull integration event, which reads from the following CSV files:

config/variants/Plain/partitions/None/data/CommonSupplierIDMap.csvconfig/variants/Plain/partitions/None/data/CommonSupplierIDMapHeader.csv

s To set up and run the CommonSupplierIDMapPull integration event:

1 Create a CSV file called CommonSupplierIDMapHeader.csv.

This file lists a set of common suppliers you want to define. Typically, these are the suppliers who have multiple IDs in different ERP systems. For example:

JoinToken,Name1,John Woodman2,Schafer Office3,Computer Electronics Supply4,JCN Technologies5,Mantell Office Maintenance (MOM)

2 Set up a CSV file called CommonSupplierIDMap.csv.

This file specifies which IDs match the join tokens in the header file. It includes one line for each ID you want to map. For example, if you want common suppliers to have a DUNS number, and a PeopleSoft vendor number, you can create a file with this format:

JoinToken,Domain,Value1,DUNS,0000001000



1,partition-psoft,MFG:00001111112,DUNS,00000000012,partition-psoft,MFG:00002222223,partition-psoft,MFG:00003333333,DUNS,00000000024,partition-psoft,MFG:00004444444,DUNS,00000001005,DUNS,00000003005,partition-psoft,MFG:0000555555

3 In Ariba Buyer Administrator, run the CommonSupplierIDMap integration event.

This integration event reads the mapping files and creates the necessary common suppliers using the IDs defined in your mapping file. Ariba Buyer creates one common supplier for each JoinToken in the header file.

4 In Ariba Buyer Administrator, run the SupplierPull integration event and the SupplierLocationSupplementPull integration event to read the list of suppliers.

The SupplierPull integration event checks the IDs to see which IDs match the common suppliers you just defined.

Reactivating Deleted Common Suppliers

If you delete common suppliers in Ariba Buyer Administrator, you can reactivate them by rerunning this integration event, but you must first modify the data source.

s To reactivate deleted common suppliers:

1 Create a CSV file that is like CommonSupplierIDMapHeader.csv, but add the SystemID column to it.

2 Insert the SystemID for each common supplier you want to reactivate.

3 Edit the Message Configuration file to have Operation=Update.

4 Run the pull using your new CSV file as input.

Common Supplier ID Map Export Events

The default configuration also includes integration events that use Ariba File Channel to export the data in your common supplier map into CSV files. The export events associated with the common supplier ID map are as follows:

• CommonSupplierIDMapHeaderExport, which exports the header file

• CommonSupplierIDMapExport, which exports the detail file


Supplier Location Verification Chapter 16 Supplier Data


Adjusting Organization IDs During Catalog PunchOut

Catalog item PunchOut is the process of allowing users to order items from a Web-based catalog. When a user chooses an item from a PunchOut catalog, Ariba Buyer exchanges cXML messages with the supplier website, obtains information about the desired item, and adds a new line item to the purchase requisition.

When the user chooses a PunchOut item, Ariba Buyer uses the organization ID to match the catalog’s supplier to an appropriate common supplier and partitioned supplier in your configuration. In some cases, Ariba Buyer might not be able to locate a correct partitioned supplier with the given ID. If this occurs:

1 The PunchOut line item is added to the requisition, but without a supplier. The line item is marked as invalid (red).

2 Ariba Buyer sends Notification 59, “Notification of Unknown Supplier,” to users who have the permission SupplierManager.

3 The Supplier Manager resolves the issue, typically by adding a D-U-N-S ID to the appropriate partitioned supplier.

4 The requisition line item remains marked as invalid until the scheduled task UpdateSupplierPendingItems runs. This task looks for unknown suppliers. If it finds the missing supplier, it updates all pending requisition line items with the correct supplier information.

5 The user can successfully submit the requisition.

Supplier Location Verification

If there are mistakes in the data for a supplier location, such as faulty contact information, those mistakes typically lead to errors when Ariba Buyer tries to send an order to that location. In general, it is preferable to detect such errors early in the process, instead of waiting until the order is sent. Ariba Buyer provides a validity check that tests supplier location information to make sure that:

• The email address is not empty.

• The fax number is not empty and parses correctly.

• The preferred ordering method is not empty and parses correctly.

Chapter 16 Supplier Data Supplier Location Verification


The validity check tests only the syntax of the entries, without actually testing to see if the data is valid. For example, if the specified email address looks fine, but is in fact no longer valid, the validity check will not report an error.

In the default configuration, Ariba Buyer calls the validity check in two places: from a scheduled task that runs periodically to make sure that all supplier locations in your configuration are complete, and from a condition that tests each supplier location on a requisition when the user first submits that requisition.

The rest of this section describes how the check is enabled in those two places. In the default configuration, which is the recommended configuration, the check is enabled in both places.

SupplierLocationCheck Scheduled Task

The SupplierLocationCheck scheduled task checks all supplier location information in your configuration on a regular basis, making sure every supplier location has appropriate contact information.

Although supplier configuration information is partitioned, the SupplierLocationCheck scheduled task is not. Each time it runs, the SupplierLocationCheck scheduled task checks the supplier profile information for every partition in your configuration. If there are errors, it sends Notification 16, “Notification of Invalid Supplier Locations,” to users who have the permission SupplierLocationCheckEmail.

You set the schedule for the SupplierLocationCheck task in the global scheduled task configuration file:

config/variants/Plain/partitions/None/CommonScheduledTasks.table

The SupplierLocationCheck scheduled task takes no parameters, so the configuration file entry typically just sets a schedule. For example:

SupplierLocationCheck = {ScheduledTaskClassName = "ariba.procure.server.SupplierLocationCheck";Schedules = {

Schedule1 = {DayOfWeek = Weekday;Hour = 4;

};};

};


Supplier Location Verification Chapter 16 Supplier Data

Validation at Submission

In the default configuration, Ariba Buyer attaches a validity condition to the supplier location. The condition is evaluated whenever a requisition is submitted. Therefore, when the user submits a requisition, Ariba Buyer validates the supplier location before submitting the requisition.

You can use the parameter Application.Procure.SubmitSupplierLocationCondition to disable or modify this validity check. This parameter names a Java class that implements the condition. If this parameter is missing, or set to the empty string, no validation occurs.

Chapter 16 Supplier Data Supplier Location Verification



Appendix A

Integration File Formats Reference

This appendix provides a complete list of the parameters that can appear in integration event files. It includes the following sections:

• “Message Definition Files” on page 243

• “Message Configuration Files” on page 244

• “Integration Mapping Files” on page 261

The message definition file is in table file format, as described in the Ariba Buyer Configuration Reference Guide.

Message Definition Files

The message definition file (MessageDefinition.table) defines the integration events used in a variant. For example:

AddressPull = {Signature = {

Error = {};Pull = { Schema = ( "ariba.common.core.Address:AddressPull" );};Reply = {};Request = {};

};TopicName = AddressPull;Type = Request-Reply;

The name is a unique identifier for an event. The names must be distinct from one another and contain only letters, numbers, and underscore characters. Do not include spaces or other punctuation characters. Names should be no more than 50 characters long.

The parameters are keywords and must appear exactly as described in the following sections. Capitalization is important, and keywords must appear exactly as capitalized here. Any parameters that do not match the keywords exactly are passed to the underlying integration event, and not reported as errors.

Appendix A Integration File Formats Reference Message Configuration Files


The order of integration events in the file is not relevant.

The following table describes the parameters in the message definition file.

Message Configuration Files

The message configuration file (MessageConfiguration.table) specifies configuration settings for one specific instance of a given integration event. You have separate copies of this file for each partition, and for each channel within a partition.

Each entry in the message configuration file must match the name of an event defined in the message definition file. The order of integration events in the file is not relevant.

The parameters are keywords and must appear exactly as capitalized here. Any parameters that do not match the keywords exactly are passed to the underlying integration event, and not reported as errors.


Signature Specifies the schema to use for each type of message sent or received by this integration event. In the previous example, the data that is pulled will contain the fields defined in the ariba.common.core.Address:AddressPull object.

TopicName Specifies a name that uniquely identifies the message sent by this integration event. The message configuration file uses this same parameter and value for the corresponding integration event configuration entry.

Type Specifies the type of message created by this integration event. Must be one of the following values:

• Request-Reply• Publish• Subscribe• Service


Message Configuration Files Appendix A Integration File Formats Reference

Message Configuration Parameters

The following is an example of an integration event entry in a message configuration file:

AddressPull = {Channel = { };ExecutionNode = “Node2”;LoggingName = Address_CSV;MessageParameters = {


EventSource = "yyy:Address.csv";Filename = "config/variants/xxx/partitions/yyy/data/Address.csv";Operation = "Load And Delete";


};Schedules = { Schedule1 = { DayOfWeek = Weekday; Hour = 2};};TopicName = AddressPull;

};

The following table describes the parameters that can appear in a message configuration file entry:


Channel Specifies any parameters required by the channel. For more information, see “Channel Parameters” on page 255.

Disable Specifies whether this event is processed by this channel. The value is a Boolean. To temporarily disable an event without actually deleting the entry for it, set Disable=true.

ExecutionNode Specifies the logical node on which this event runs. The value can be a specific node name (such as Node2), or the keywords PrimaryNode, or AllNodes. If this parameter is not specified, the event runs on the primary node (PrimaryNode).



IncrementalPull Specifies whether to use just date or the date and time when comparing dates for incremental loading. In incremental loading, Ariba Buyer compares the timestamp of the last database change with the timestamp of the last integration pull, and pulls only data that has changed in that window. The valid values for this parameter are DateOnly and DateAndTime. For example,

IncrementalPull=DateOnly;

For most integration events, DateOnly is sufficient. For integration events that have secondary actions (like sending mail) or for which the exact time is crucial (such as checking data errors), use DateAndTime.

The implementation of an integration event (such as a TIBCO worksheet) specifies whether the event uses full or incremental loading. For information on how to configure incremental loading in TIBCO worksheets, see the Ariba Buyer TIBCO Configuration Guide.

LoggingName Specifies the name used to identify this configuration of the integration event in the database log. The name is prepended by the partition name to uniquely identify it.

MessageParameters Specifies parameters that are specific to the message that’s sent in response to this integration event. For information on the keys that can appear in MessageParameters, see “Request-Specific Parameters” on page 248.

Schedules Specifies one or more scheduled times for running this integration event. For complete information on specifying schedule information, see the “Scheduled Tasks” chapter in the Ariba Buyer Configuration Guide.

Parameter (Continued) Description



TopicName Specifies the topic that this message uses to identify itself. Other integration events can listen for this topic and act when a message with this topic is processed.

Visible Indicates whether this integration event can be run manually from Ariba Buyer Administrator. This parameter is true by default except for Publish events, which are false by default. For most events, omit this parameter and use the default. If you specify Visible=false, the integration event is listed in Ariba Buyer Administrator but is marked as PushOnly, so it runs only in the background as a result of some other process.




Request-Specific Parameters

The parameters that can appear in the MessageParameters key are as follows:


MergedSchemaName Configures push events, by naming the schema for outgoing data. For push events, Ariba Buyer reads through the message definition and configuration files, creates a merged schema, and publishes that merged schema to the channel repository.

You can use the optional MergedSchemaName parameter to specify a name for the merged schema. If not specified, the default is to use the naming convention TopicName_SchemaName.

For more information on merged schema, see “Merged Schema” on page 48

Request > Parameters Specifies the details of how to connect to this data source. The request parameters typically include event source and operation. For example:


Parameters = {EventSource = "ppsoft75:Address:PSAdapter";ExternalConnection = PSoftEP75Oracle;

};

SchemaName Specifies the name of the schema to use for the outgoing message. The Ariba File Channel recognizes the following schema:

• ResourceFileSchema

• SimpleFileSchema

• VectorFileSchema

• HeaderDetailSchema

For more information on schema, see “Integration Schema” on page 46.



The Parameters section defines values that configure the event. The parameters can name a data source, or a connection, or provide any other information that the integration event implementation uses to connect to the data source. For example, in the default configuration, the entry for the Oracle Financials address integration event includes this parameter:

Parameters = { DefaultChartOfAccountsId = 50317;};

The AddressEvent TIBCO worksheet for this integration event uses this data to construct a query of the form SELECT ... WHERE chart_of_accounts_id = 50317.

Data Source Parameters

Request-specific parameters include information that identifies the data source, such as a file name or database. In some cases, there are multiple data sources. For example, for integration events that read several filenames, you can create different parameters for each of those filenames:

Parameters = {Filename = "config/variants/voracle/partitions/poracle107/data/User.csv";PCardMapFilename =

"config/variants/voracle/partitions/poracle107/data/PCardMap.csv";

The parameter(s) you use to specify the data source depends on the schema specified for this event. The following are the data source parameters supported by schema in the default configuration.


ResourceFilename This parameter is appropriate when the integration event uses a language-specific resources for input. For example:

ResourceFilename = "config/variants/variant/partitions/partition/data/translations/*/MyStuff.csv";

You can specify multiple file names, separated by semicolons.

Details Specifies information about detail data. This parameter is used when header data and detail data are located in separate CSV files, and the data cannot be loaded separately.



ParentField Specifies the field in the header object to which you want to map the details data.

DetailFileName Specifies the name of the CSV file (or vector of names) that contains the detail data. For more information, see Chapter 4, “Ariba File Channel.”

JoinFields Specifies the join relationship between a field in the detail data and a field in the header data.

Filename Specifies one or more filenames, either in config or in ariba. If there are multiple filenames, separate them with a semicolon.

Filename = "config/variants/variant/partitions/partition/data/SupplierLocationSupplement.csv";

HeaderFileName Specifies the name of a CSV file that contains header data. This parameter is used when header data and detail data are located in separate CSV files, and the data cannot be loaded separately. For more information, see “Header-Detail Pull Events” on page 62.

VectorFilename Synonymous with Filename, but valid only when the value has more than one filename. Separate filenames with a semicolon. For example:

VectorFilename = "ariba/variants/voracle/partitions/poracle107/data/SplitAccountingType.csv;config/variants/voracle/partitions/poracle107/data/SplitAccountingType.csv";




Event Source Parameter

Every integration event has an EventSource parameter, a unique label that is used to mark objects in the database that originated from this integration event. For example:

EventSource = "poracle110:Address:Oracle";

If you mark two integration events with the same EventSource, you are indicating that those two events modify the same objects in the database. In general, every integration event should have a different EventSource. However, it might occasionally be appropriate for two integration events to share the same data source, such as when you are loading multilingual data for the same objects.

The EventSource label can be any string that is no more than 50 characters in length. The label must be unique across partitions, and it must remain the same each time the integration event runs. The EventSource label is not visible to users. It is used only for marking objects in the database.

ExternalConnection Specifies that this integration event uses database connection information specified in ConnectionInfo.table. This parameter is shorthand for reading a set of values from a specified definition in ConnectionInfo.table. If any of the following parameters appear in an integration event configuration file, they override the values read from the external connection: DBType, Driver, Password, URL, User.

The value must correspond to the name of an entry in ConnectionInfo.table. For example, this entry:

ExternalConnection = Oracle_DB;

corresponds to the following entry in ConnectionInfo.table:

Oracle_DB = {DBType = Oracle;Driver = oracle.jdbc.driver.OracleDriver;

...};

For more information on the external connection file, see the Ariba Buyer TIBCO Configuration Guide.




Operation Parameter

The Operation parameter specifies whether this integration event creates, updates, or deletes objects and fields in Ariba Buyer. The operation applies only to records that have the same EventSource label as the integration event. Other records are ignored.

Note: TIBCO message configuration entries do not include the Operation parameter because operation values for TIBCO events are specified in the TIBCO worksheets. For more information, see the Ariba Buyer TIBCO Configuration Guide.

The Operation parameter can have the following values:

Value Description

Create This option creates new elements in the Ariba Buyer database using data values from the data source. If the element already exists in the Ariba Buyer database, no new item is created.

Delete This option deletes the objects published by the event. Each element in the data source is deleted from the Ariba Buyer database.

Update This option modifies the values in the Ariba Buyer database based on the values in the data source.

Load This option is a combination of Create and Update:

• If an item in the data source does not already exist in the Ariba Buyer database, the item is created.

• If the item does already exist, it is updated.

Update And Delete Like Update, in that it updates the database based on the value source. This option also does the following:

• Deletes elements from the Ariba Buyer database that have the same EventSource label as the integration event and are not in the data source

• Does not create new elements, even if they exist in the data source



Load And Delete Like Load, in that it updates or creates, as appropriate. In addition, this option deletes elements from the Ariba Buyer database that have the same EventSource label as the integration event and are not in the data source.

Update Elements Only This option is the same as the Load operation, but for fields that contain other fields, such as vector fields. If you use the Load operation on a vector field, the integration event replaces the entire vector. If you use Update Elements Only, the event updates elements without deleting existing elements,

For example, suppose you have a vector field with three elements, and the data source has a vector with new values for two of those three elements. Both Load and Update Elements Only update the two elements that have changed. However, with the Load operation, the third element is deleted. With Update Elements Only, the third element is left alone.

Value (Continued) Description



Other MessageParameters Entries

The parameters in the table below can also appear in MessageParameters but are not used in every event. These parameters are less commonly-used parameters not related to the data source or operation.


DataQueueSize (Optional) Specifies a queue length for data exchanged during a pull event. When the queue is filled to the specified size, Ariba Buyer empties the queue before pulling more data.

This value overrides the data queue length specified by System.Messaging.Channels.File.DataQueueSize.

EmptyVectorOnNoData (Optional) Specifies whether the details vector field is emptied if the new data contains no details data.

Set this parameter to true if you want to remove all the data in a vector field. Set this parameter to false if you want data that is already in the details vector field to remain intact.

If not specified, the value is assumed to be false.

IgnoreSourceOfTruth (Optional) Specifies whether objects that are manually maintained will be updated by the integration event. This parameter is used for data that is sent to Ariba Buyer from other Ariba applications, and not from external systems.

If this parameter is set to true, objects loaded by the integration event are updated, even when their adapter source is ManuallyMaintained. If this parameter is false, objects loaded by the integration are not updated when their adapter source is ManuallyMaintained.

If not specified, the default value is false.

For more information, see “Sources of Field Values” on page 29.



Channel Parameters

Each message configuration file contains default parameters for communicating with the channel. For example:

Default = {Channel = {

Initialization = Automatic;Name = Tibco;RepositoryInstance = voracle;Threads = 3;Timeout = 240000;

};

IncludeLocationRef Indicates whether errors include a line number or column number reference. This parameter is used for events that import from Excel, and in that case provides information about the column with errors. The value is a Boolean that is set to false by default.

IncludeSubclasses (Optional) If there is a ClusterRoot to be looked up for binding, and if the integration event does not find it in the base class, this parameter specifies whether the integration event performs a lookup on subclasses to find the object.

When this parameter is set to true, the integration event performs a lookup on subclasses to find the object.

When this parameter is set to false, the integration event does not perform a lookup on subclasses to find the object.

If not specified, the default is false.

InternalVectorFields Used only by the integration events that use Excel as the data source.

LogNonFatalErrors Specifies whether to include non-fatal errors in the event log. This parameter is a Boolean that is set to false by default. To include non-fatal errors (such as lookup errors due to invalid data) in the log files, set this value to true.

RowDelimiter Used only by the integration events that use Excel as the data source.




Individual integration events inherit these defaults and can either add additional parameters or override the defaults. For example:

AccountPull = {Channel = {

Subject = voracle.AccountAccountingEvent;TibcoSheet = AccountAccountingEvent;

};

The channel parameters you specify depend on the channel you are using. The following sections describe the parameters that are specific to the Ariba File Channel. For information on IBM WebSphere parameters, see the IBM documentation. For information on TIBCO parameters, see the Ariba Buyer TIBCO Configuration Guide.

Ariba File Channel Parameters

The following example shows how to set the default values for channel-specific parameters for the Ariba File Channel.

Default = {Channel = {

Encoding = UTF-8;FileReaderParams = {

EmptyValue = TreatAsEmptyString;OnEmptyLines = SkipLine;OnInvalidData = "WarnUser”;Separator = ",";

};Decoder = {

Name = FileChannelDecoder;Parameters = {};

};Encoder = {

Name = FileChannelEncoder;Parameters = {};

};FileType = CSV;Name = File;

};Visible = true;

};

For specific integration events, you can override these default settings in the Channel section. The following example shows two Ariba File Channel message configurations in the default configuration. Parameters or values that are specific to the Ariba File Channel are highlighted in bold text.



AccountLanguagePull = {Channel = {

ChannelContextMapFields = { Language = {

FieldName = Language;};

};};LoggingName = AccountLanguage_CSV;


Parameters = {EventSource = "pcsv:Account.csv";ResourceFilename =

"config/variants/vcsv/partitions/pcsv/data/translations/*/Account.csv";Operation = "Update";

};SchemaName = ariba.integration.ResourceFileSchema;};

};TopicName = AccountLanguagePull;

};};

This section describes the parameters that can appear in the Channels section for events using the Ariba File Channel.


Encoding Specifies the encoding of data to be expected in the incoming CSV files. You can omit this parameter if the CSV files themselves include encoding information. (For information on specifying encoding in CSV files, see the Ariba Buyer Configuration Reference Guide.)

Locale Specifies a locale to be used for the header row, when importing or exporting from Excel. For more information, see “Localized Header Columns in Spreadsheets” on page 66.



FileReaderParams Specifies how the incoming data is parsed. The possible parameters are listed below.

EmptyValue Specifies how to handle empty values in the data source. By default, empty values are handled as nulls. To change that behavior, set EmptyValue to the following:

• TreatAsEmptyString

OnEmptyLines Specifies how to handle empty lines in the CSV file. Valid values are as follows:

• SkipLine, which skips data

• WarnUser, which logs a warning message to the log file

• TreatAsException, which logs an error to the log file

If the event is executed during initdb, the log file is dbinit.txt. If the event is executed from Ariba Buyer Administrator or servermonitor, the log file is AribaBuyernodenameLog.txt.

OnEmptyFile Specifies how the file reader should handle empty CSV files. Valid values are as follows:


• AbortPull, which aborts the integration event and throws an exception

If the event is executed during initdb, the log file is dbinit.txt. If the event is executed from Ariba Buyer Administrator or servermonitor, the log file is AribaBuyernodenameLog.txt




FileReaderParams (continued)

OnInvalidData

Specifies how the file reader should handle invalid data in CSV files. Valid values are as follows:

• SkipLine, which skips data


• TreatAsException, which logs an error to the log file

If the event is executed during initdb, the log file is dbinit.txt. If the event is executed from Ariba Buyer Administrator or servermonitor, the log file is AribaBuyernodenameLog.txt.

Separator Specifies the character that can be used as a separator in CSV files. Any printable character is a valid separator.

useExplicitNulls A Boolean. If set to true, then a “null” string in the CSV file is treated as explicit null and the field is updated with the new (null) value. By default this parameter is false.

Fields such as ClusterRoots that are indirect fields (pointers to other existing objects) cannot be explicitly set to null.

Decoder The parameters in this key describe the Ariba File Channel decoder, FileChannelDecoder. You should leave these parameters set to their default values.

Encoder The parameters in this key describe the Ariba File Channel encoder, FileChannelEncoder.

The parameters in this key are as follows:

InnerJoin A Boolean that specifies whether an inner join is used. When this parameter is set to true, an inner join is used. When this parameter is not set or is set to false, a left outer join is used.




FileType Specifies the file type.

• CSV specifies CSV files.

• XLS specifies Excel (.xls) files.

• SUPPLIER is a special file type that is used only by the SupplierXMLPull integration event. Do not modify the file type for SupplierXMLPull, and do not specify the SUPPLIER file type in any other event.

Name Specifies the channel to use. The value for the Ariba File Channel is File.

ChannelContextMapFields The parameters in this key specify how to map context fields, such as Language. The parameters in this key are as follows:

defaultValue Specifies the default value for the context field. For simple pull events, you use this parameter to specify the default language to be used when multilingual strings are created from the data.

FieldName Specifies a field in the CSV file to map to the context field. For a language pull event, you use this parameter to map the Language column in each resource file to the language field on the event context.

For more information, see “Language Pull Events” on page 60.

Threads An integer that specifies the number of database connections the integration event uses. If this parameter is set to 0 (the default), Ariba Buyer loads the entire data source into memory before processing any of the items. If this parameter is set to 1 or more, Ariba Buyer uses one thread to read the data on demand and the specified number of additional threads to process the data. If you increase the value of the Threads parameter, check the value of System.Performance.DatabaseConnections in config/Parameters.table to make sure you have allocated a large enough pool of database connections.



Integration Mapping Files Appendix A Integration File Formats Reference

Integration Mapping Files

This section describes the integration mapping file, which is in metadata XML format.

The Integration Field Property

You use the integration field property to specify data mappings and transformations for groups in your integration mappings extension file. You can also use this field property to set up filter conditions to restrict a query for an export event.

The integration field property defines a table of key/value pairs. For example:



</property>

This section describes the values you can specify for key.

Appendix A Integration File Formats Reference Integration Mapping Files


Key Values for Data Mappings and Transformations

The following table describes key values for data mappings and transformations.

Key Value Description

mapField Use this key to map the name of a field to the name of a column when the field name and the column name in the CSV file are different. The value parameter specifies the name of the column in the CSV file.

The following example uses the mapField key to map the field UniqueName to the column named Group:

<groupField name="Group.UniqueName"><properties>




</groupField>

defaultValue Use this key to map a field to a hard-coded value. The value parameter specifies the hard-coded value.

The following example uses the defaultValue key to map the field MapType to the value MyMap:

<groupField name="Type.MapType"><properties>


<entry key="defaultValue" value="MyMap"/>

</table></property>




metadataIntegrationTypeOverride

Use this key to narrow the field type to a subtype, if the incoming data is a subclass of the destination field.

The following example narrows from Principal to Group:

<groupField name="SuperType"><properties>


<entry key="metadataIntegrationTypeOverride" value="Subtype"/>

</table></property>


formatterType Use this key to specify a custom formatter for a field. The value parameter specifies the formatter name, which must match a key defined in System.Messaging.Channels.File.Formatters.

The following example uses the formatterType key to specify a custom formatter named Foo:

<groupField name="PersonalLiability"><properties>


<entry key="formatterType" value="Foo"/>

</table></property>


In config/Parameters.table, the name Foo must be bound to a Java class, which implements ariba.util.formatter.Formatter. For more information on custom formatters, see the Ariba Buyer API Guide.

Key Value (Continued) Description



Key Values for Export Event Filter Conditions

The following table describes key values for export event filter conditions.

Key Value Description

equals Use this key to restrict the query to export only those objects that are equal to the specified value.

notEquals Use this key to restrict the query to export only those objects that are not equal to the specified value.

exclude Use this key with another filter condition when you want to include a field in the query, but you want to exclude the field from the export. The value can be true (to exclude the field from the export) or false (to include the field in the export).

The following example excludes State fields that have the value CA:

<groupField name="State"<properties>


<entry key="equals" value="CA"/><entry key="exclude" value="true"/>

</table></property>

<properties></groupField>

lessThan Use this key to restrict the query to export only those objects that are less than a specified value, which must be an integer.

lessThanEquals Use this key to restrict the query to export only those objects that are less than or equal to the specified value, which must be an integer.

greaterThan Use this key to restrict the query to export only those objects that are greater than the specified value, which must be an integer.



greaterThanEquals Use this key to restrict the query to export only those objects that are greater than or equal to the specified value, which must be an integer. For example:

<groupField name="PostalCode"><properties>


<entry key="greatThanEquals" value="940"/>

<entry key="lessThan" value="990"/></table>


</groupField>

in Use this key to restrict the query to export only those objects that are in the vector specified in value. For example:



<entry key="in" value="9041,94086,94046"/>

</table></property>


notIn Use this key to restrict the query to export only those objects that are not in the vector specified in value. For example:



<entry key="notIn" value="94086,94046"/>

</table></property>





isNull Use this key to restrict the query to include or exclude objects whose value is null from the export. The value can be true (to include objects whose value is null) or false (to exclude objects whose value is null).

The following example excludes objects that do not have a null fax number:

<groupFieldName="Fax"><properties>

<property name="integration"”><table>

<entry key="isNull" value="false"/></table>


</groupField>



Symbols$ (dollar sign) symbol and syntax 87| (vertical bar) character 88

Aaccessibility, setting for fields 50account category 209account type 209account validation 210Account.csv file

example 205field descriptions 205

accounting combinationsabout 203configuring 204metadata XML 212

accounting entitiesabout 202integration events 205Oracle configurations 206PeopleSoft configurations 206SAP configurations 206

accounting informationabout 201default settings 202defaulting from requester 213line item split accounting 203max accounting splits 207

accounting integration eventsAccountingCombinationPull 211AccountPull 204AccountType 210AccountTypePull 209

accounting object 204

accounting parametersAllowSplitAccounting 207MaxAccountingSplits 207

AccountingCombinationPull integration event 211, 212

AccountPull integration event 204AccountType integration event 210AccountType.csv file


AccountTypePull integration event 209adapter sources

about 31audit messages 32viewing 31

addingcommon suppliers 235new schemas 47users 160, 161

addresspartitioned 195shared address 195

address integration eventsAddressExport 200AddressPull 196SharedUserAddressMap 196, 199

Address.csv fileexample 198field descriptions 198

Address_Export.csv file 200addresses

about 195billing 200loading data 196

AddressExport integration event 200AddressPull integration event 196

Index


Index

administrative tasks, permissions for 171AllowNonWhole units of measure 190AllowSplitAccounting parameter 207ANSI units of measure 188application authentication parameters

ModifyUserProfileOnInitialLogin 168ModifyUserProfileOnInitialLogon 170OrganicGrowth 170

application base data parametersDefaultBillToAddress 200DefaultLanguage 24, 106DefaultOrganicUserLocale 103, 170

application classification code parametersCommodityCodeUIDomainImpl 144SystemCommodityCodeDomainName

144Application.Approvable.AllowSplitAccounti

ng parameter 207Application.ClassificationCodes.UnspscAud

itFile parameter 146Application.Messaging parameters 54, 84Application.Messaging.MessageConfigurati

onFiles parameter 96ARFHintTotalCost field controller

about 127using 127

Ariba Buyeraddress 195configuring organic user growth 170data types 18locale 99partitioned commodity codes 143setting up non-English configurations 113supplier data 217system ID 162users 159

Ariba Buyer Administratorediting shared users 161using the Supplier Manager 234

Ariba Category Management integration 149Ariba cXML Channel

See also cXML templatesabout 38, 83overview 83parameters 84

Ariba File Channelabout 38, 53deleting data 59file readers 55message configuration examples 256parameters 256

Ariba HTTP Channelabout 38overview 95parameters 96

Ariba Network IDs 220Ariba SN

Ariba cXMLChannel 38loading suppliers 229, 231suppliers 220

Ariba Supplier Network. See Ariba SNAriba Technical Support xiiariba.basic.core.Address type 195ariba.basic.core.CommodityCode class 143ariba.common.core.address object 195ariba.common.core.PartitionedCommodityC

ode class 143ariba.common.core.User object 159ariba.procure.core.action.SetAccountingFro

mCommodityCode trigger action 156

ariba.user.core.User object 159AribaDBCharset parameter 114AribaNetworkFullSubscriptionSync

scheduled task 230AribaNetworkID for supplier location 228AribaNetworkOrganizationSync scheduled

task 229Asian language configurations

character encodings 113considerations 117

ASMSharedDomainList parameter 145assigning

permissions to users 185roles to groups 182, 183roles to users 184supplier IDs 232

attributes, mapValueType 28


Index

audit filesparameter for 146UNSPSC 146

audit messages, adapter sources 32AutoSetAdapterSourceAfterManualModific

ation parameter 32available currencies 122AW components

about 87AWMethodInvocation 92AWRepetition 92AWString 93expressing primitive logic statements 88in template files 89

AWConditional element 90AWElse blocks 90.awl file extension 86AX components

AXAssign 93AXConditional 94

Bbank selling rates 138base and reporting currencies 123batch operations 58billing address 200binding, dynamic 87bulk loading

common suppliers 236suppliers 234

Ccanonical list. See canonical valuescanonical units of measure 189canonical values

about 25in mapped data 25integration events 27list of unpartitioned names 25

catalog index, rebuilding 234Catalog item PunchOut 239

catalog load, adding suppliers 230catalog searching, Asian languages 117catalogs, translating units of measure 188change orders in supplier location

configuration 228changing. See modifyingChannel parameter 245channel parameters

about 255Ariba File Channel 256ChannelContextMapFields 260DataQueueSize 254Decoder 259defaultValue 260DetailFileName 250Details 249EmptyValue 258EmptyVectorOnNoData 254Encoder 259Encoding 257FieldName 260FileReaderParams 258, 259FileType 260HeaderFileName 250IgnoreSourceOfTruth 254IncludeLocationRef 255IncludeSubclasses 255InnerJoin 259InternalVectorFields 255JoinFields 250Locale 257LogNonFatalErrors 255Name 260OnEmptyFile 258OnEmptyLines 258OnInvalidData 259ParentField 250RowDelimiter 255Separator 259Threads 260useExplicitNulls 259

ChannelContextMapFields parameter 260channels. See integration channels


Index

character encodingsAsian configurations 113for locale 110invalid formats 111specifying 114

character sets, specifying 115charsets, databases 114Chinese configurations 113CIF 3.0 files units of measure 188classes

ariba.basic.core.CommodityCode 143ariba.common.core.PartitionedCommodit

yCode 143encoder and decoder 55

classification code domains 145classification codes

See also commodity codesabout 141eClass Standardized Material and Service

Classification 141global standards 141hierarchies 142mapping files for 152NAICS 141sending to external systems 145UNSPSC 141

ClassificationCodeDomainMeta.csv file field descriptions 151

ClassificationCodeDomainMetaPull integration event 150, 151

ClassificationCodeMap.csv file field descriptions 152

ClassificationCodeMapPull integration event 152

codes, classification. See classification codescollection of related currencies 122comma-separated value (CSV) files. See

CSV filesComment field in mapping files 26

commodity code integration eventsClassificationCodeDomainMetaPull 150,

151ClassificationCodeMapPull 152CommodityCodePull 150CommodityExportMapPull 153CommonCommodityCodePull 147

commodity code map 146commodity code parameters

Application.ClassificationCodes.CommodityCodeUIDomainImpl 144

Application.ClassificationCodes.SystemCommodityCodeDomainName 144

commodity codesabout 143ACM integration 149domain meta 144domain versions 144domains 143enabling and disabling 148export events 157external standards 148files 148language pull events 157loading 148mapping with wildcards 153mappings 145mappings (correcting mappings) 156NONMAPPEDCOMMODITY 157object model 143partitioned 143PunchOut items 157sample data 148shared 143translating between sets of codes 146UNSPSC audit files 146

CommodityCodePull field descriptions 147CommodityCodePull integration event 150CommodityCodeReport scheduled task 156CommodityExportMap.csv file



Index

CommodityExportMapPull integration event 153

Common Data Server (CDS)integration events 54shared addresses 195updating 38

common data. See canonical valuescommon suppliers

about 218adding 235bulk loading 236linking 233reactivating 238

CommonCommodityCodePull integration event 147

CommonSupplierIDMap.csv file 21, 237CommonSupplierIDMapExport integration

event 238CommonSupplierIDMapHeader.csv file 21,

237, 238CommonSupplierIDMapHeaderExport

integration event 238CommonSupplierIDMapPull integration

event 234, 236CommonSupplierSyncUsingSupplierLocatio

nID scheduled task 229communications channel. See integration

channelscompany codes, default accounting

information 155Company.csv file in CSV configurations 205configuration files

date strings 100initialization order table file 33

configuring roles, groups, and permissions 171

ConnectionInfo.table 251contacts at a supplier location 227conversion types for currency 125countries

default currency 123defining mappings 108in locales 98integration events and parameters 107

country fields 108

Country.csv file example 108CountryLanguagePull integration event 108CountryMap field descriptions 109CountryMapPull integration event 108CountryPull integration event 107Create Operation option 252creating. See addingCSV configurations, accounting information

205CSV file format

about 19multilingual use 19

CSV filesas data sources 17multiple files as data source 20single file as data source 20special characters in 199

CSVReader, null 259currency

available 122base and reporting 123choosing a default 140code 131considerations for ERP systems 129conversion rate and types 124defining data 121direct historical rate 128euro considerations 125field descriptions 132groups 122historical conversion 128in Asian configurations 115in reporting 123integration events and parameters 121Oracle configurations 129, 136overview 121PeopleSoft configurations 130preferred and default user 123reciprocal historical rate 128SAP configurations 130, 137tailoring rates 138transaction 123, 124triangulated historical rate 128user default currency 164


Index

currency conversion ratesavailable currencies 122defined 124performance cache 122types for SAP 137

currency group 122currency integration events

CurrencyConversionRatePull 135CurrencyGroupPull 139CurrencyMapPull 133CurrencyPull 115, 131EuroConversionRatePull 137

currency parametersCurrencyRateCacheSize 122setting 115ZARIBTVARV 138

currency rates, tailoring 138Currency.csv file 133CurrencyConversionRate field descriptions

135CurrencyConversionRatePull integration

event 135CurrencyGroup field descriptions 139CurrencyGroupPull integration event 139CurrencyMap.csv file

about 134field descriptions 134

CurrencyMapPull integration event 133CurrencyPull integration event 115, 131CurrencyRateCacheSize parameter 122custom date formatter, specifying 80customizing

cXML templates 85data mappings 74default exporters 74encoding mappings 110

cXML elements, standard 85cXML files, units of measure 188cXML templates

about 83customizing 85hash tables 91loops 92

Ddata

See also mapped datacanonical values 25commodity codes 148defining currencies 121deleting with integration event 58, 59detail 21exporting manually maintained 73global 18header 21loading for addresses 196multilingual 21partitioned 18, 159specifying character sets 115supplier 217types 18unpartitioned 159

data file encoding 115data files for mapped data 25data implementations, default configuration

18data mappings, customizing 74data pull schema 47data source parameters

about 249, 254ExternalConnection 251Filename 250VectorFilename 250

data sourcesmultiple CSV files 20overview 17single CSV file 20vector of file names 20

database schema 49databases, charset 114DataQueueSize parameter 254date formatter, specifying a custom 80date strings in configuration files 100dates, valid formats for 100DBConnection schema 49decoder classes 55Decoder parameter 259


Index

default accounting informationby account type and account assignment

155by company code 155

default exporters, customizing 74default language performance considerations

116default settings

accounting information 202, 213billing address 200currency for users 164data implementations 18integration event values 76language parameters 106locale 98locale mappings 110locale parameters 103organizations 160permissions 167user currencies 123

DefaultLanguage parameter 24, 106DefaultLocale parameter 103DefaultOrganicUserLocale parameter 103,

170DefaultProcureLineItemFromApprovable

trigger 214DefaultProcureLineItemFromRequester

trigger 214defaultType key 262DefaultUnitOfMeasure parameter 194defaultValue entry key 60defaultValue parameter 260defining load order 33Delete Operation option 252deleting data

from fields 58inactive in database 59languages 104with integration event 59

detail data file 21DetailFileName parameter 21, 64, 66, 250Details key 64Details parameter 249Direct conversion type 125direct historical rate for currency 128

Disable parameter 245disabling commodity codes 148disabling integration events 42DOCTYPE line in extension files 74document type definition 74document type definition (DTD) file 74documentation typographic conventions xiidollar sign ($) symbol 87domain meta 144domains

commodity codes 143domain meta 144for naming 220mapping 145UNSPSC audit files 146version 144

dual-currency reporting 123dynamic binding 87dynamic elements 85

EeClass Standardized Material and Service

Classification codes 141Economic Monetary Union (EMU) currency

122, 123EditPermissionPull integration event 176elements

AWConditional 90dynamic 85standard cXML 85

empty strings, CSV reader 258EmptyValue parameter 258EmptyVectorOnNoData parameter 254enabling commodity codes 148encoder classes 55Encoder parameter 259Encoding parameter 257EncodingMap.csv file, customizing 110English, including in every configuration 105Enterprise Resource Planning (ERP)

systems. See ERP systemsequals key 264ERP field value 30


Index

ERP systemsand multilingual configurations 97as data sources 17currency considerations 129

errorsfor Excel import 69logging 69

euro currencyconsiderations 125conversion rules 125

EuroConversionRatePull integration event 137

European configurations, Unicode Euro characters 114

events. See integration eventsEventSource parameter

about 49batch operations 58in message configuration files 251with integration events 22

examplesAccount.csv file 205AccountType.csv file 210Address.csv file 198CommodityExportMap.csv file 154Country.csv file 108CurrencyConversionRatePull integration

event 137GroupSharedUserMap.csv file 182integration events 41, 42Language.csv file 105message configuration file 245message definition files 243metadata XML file 215NAICS sample commodity codes 148PartitionedCommodityCode.csv file 150Permission.csv file 176PermissionsMap.csv file 184PropagateDefaultShippingOnChange 213Role.csv file 178SharedUser.csv file 164

SplitAccountingType.csv file 208Supplier.csv file 223SupplierLocation.csv file 225SupplierLocationSupplement.csv file 228UnitsOfMeasure.csv file 190UNSPSC code mapping 152User.csv file 166

Excelerror messages 69file reader 65import error handling 255worksheets, multiple 66

exclude key 264ExcludeSupplierDirectCatalogItems

parameter 231ExecutePermissionPull integration event 177ExecutionNode parameter 44, 245export events

about 70commodity codes 157filtering 77language 71message configuration 70message definition 70

export filesnaming 71specifying field order 72

export language, specifying 71Export value for fields 50exporters

configuring new 73customizing default 74

exporting manually maintained data 73extension files

declaring DTD 74DOCTYPE line 74integration mappings 74

ExternalConnection field 48ExternalConnection parameter 251extrinsics, adding to purchase requisitions

213


Index

Ffield order, specifying in export files 72field values

See also fields; file field descriptionscontrolling the sources 29ERP 30ORMS 30sources of 29

FieldName parameter 260fields

See also file field descriptionsadding to groups 81CommodityCodePull 147controlling sources of values 29country 108CountryMap 109currency 132CurrencyConversionRate 135CurrencyGroup 139CurrencyMap 134deleting data 58ExternalConnection 48FullObject value 50in data mapping files 26LanguageMap 106languages 104LocaleID 101LocaleMap 102PartitionedCommodityCode 150removing mapping 81setting accessibility and scope 50shared address 197

file field descriptionsAccount.csv file 205AccountType.csv file 209Address.csv file 198ClassificationCodeDomainMeta.csv file

151ClassificationCodeMap.csv file 152CommodityExportMap.csv file 153Group.csv file 178, 180GroupSharedUserMap.csv file 182Organization.csv file 162Permission.csv file 175Role.csv file 178

RolePermissionMap.csv file 184SharedUser.csv file 163SharedUserShipToAddressMap.csv 199SplitAccountingType.csv file 208Supplier.csv file 223SupplierLocation.csv file 224SupplierLocationSupplement.csv file 227UnitOfMeasureCIFMap.csv 193UnitOfMeasureMap.csv 192UnitsOfMeasure.csv 190User.csv file 166

file format 26file readers, Ariba File Channel 55Filename parameter 57, 250FileReaderParams parameter 258, 259files

commodity code standards 148detail data 21header data 21integration mapping 261message configuration 39message definition 39UNSPSC audit 146

FileType parameter 260filter conditions

example 78for export events 78

filtering export events 77Formatters parameter 80, 263formatterType key 263FullObject value for fields 50

GGetPendingAribaNetworkOrganizationSync

scheduled task 229ghost cards in supplier location information

228global data 18, 143global instance

about 113CSVReportsCharset parameter 117parameter settings 118Tibco.RVEncoding parameter 115Unicode support 113


Index

global standards for classification codes 141greaterThan key 264greaterThanEquals key 265group integration events

GroupExport 180GroupPermissionMapPull 183GroupPull 178, 179, 180GroupRoleMapPull 173, 182GroupSharedUserMapPull 181GroupUserMapPull 173load order 186SharedUserPermissionMapPull 185

Group.csv file field descriptions 178, 180Group_Export.csv file 180GroupExport integration event 180GroupMap.csv file 182, 199GroupPermissionMap.csv file 183GroupPull integration event 178, 179, 180GroupRoleMap.csv file 182GroupRoleMapPull integration event 173,

182, 183groups

See also permissions; roles; usersabout 171adding new fields to 81AddressPull 60and roles 173assigning roles to 182, 183assigning users to 182, 199configuring 171default configuration 172for user validation 169integration events for 178, 179, 180

GroupSharedUserMap.csv fileexample 182field descriptions 182

GroupSharedUserMapPull integration event 181

GroupUserMapPull integration event 173

Hheader data file 21header-detail pull events 62HeaderDetailFileSchema schema 21HeaderFileName parameter 21, 64, 250hierarchies, classification codes 142historical currency conversion 128Human Resource Management System

(HRMS) as data source 17

IIBM WebSphere Business Integration

Adapter channel 38IDs, assigning to suppliers 232IgnoreSourceOfTruth parameter 32, 254Import Mapping Failure notification 158in key 265inactive data, deleting 59IncludeLocationRef parameter 69, 255IncludeSubclasses parameter 255IncrementalPull parameter 246Index Builder task in Ariba Buyer

Administrator 234indirect fields, setting to null 259initdb command for loading languages 35initialization order 33, 34InnerJoin parameter 259integration channels

See also channel parametersAriba cXML Channel 83defined 38list of 38

integration event filesmodifying 45parameters 243, 244


Index

integration eventsSee also integration events for accounting;

addresses; commodity codes; currency ; groups; language; locale; permissions; roles; suppliers; units of measure; users

accounting entities 205adding users 161canonical list of values 27defined 37defining load order 33deleting data 59disabling 42EventSource 251EventSource parameter 22examples 41, 42for accounting entities 205for mapping 27initialization order 34load order for 33, 186mapping field names 76naming 45partitioned data 37pushing to external systems 247reinitializing 46setting default values 76SimpleMapTypePull 28type narrowing 76

integration field property 60, 75, 261integration mappings

extension file 74files 54, 59, 74

integration schemasSee also schemasabout 46

integration tableMapType parameter 28ResourceFilename parameter 23

IntegrationExt.aml file 74IntegrationSchemas.aml file 47InternalVectorFields parameter 68, 255invalid character encoding formats 111isNull key 266

JJapanese-language configurations

encodings for 113requirements 117

join token 237JoinFields parameter 64, 250

KKey field in mapping files 26keys

See also parametersdefaultType 262defaultValue 60Details 64equals 264exclude 264formatterType 263greaterThan 264greaterThanEquals 265in 265IsNull 266lessThan 264lessThanEquals 264mapField 60, 262metadataIntegrationTypeOverride 76, 263notEquals 264notIn 265Signature 41

Llanguage considerations, Asian language

configurations 117language data, loading 35language export events, creating 71language fields 104language integration events

LanguageLanguagePull 105LanguageMapPull 105LanguagePull 61LocaleLanguage 102


Index

language pull eventsabout 60commodity codes 157defining 22

Language.csv file example 105LanguageLanguagePull integration event 61,

105LanguageMap fields 106LanguageMap.csv file 106LanguagePull integration event 104languages

deleting from a partition 104directories 100filtering available languages 105in locales 98integration events and parameters 104load order for 34setting default 24, 106specifying for export 71variant, in locales 98

lessThan key 264lessThanEquals key 264line item split accounting. See split

accountingline numbers in Excel import 69linking suppliers 233, 235Load And Delete Operation option 253Load Operation option 252load order

defining 33for languages 34integration events 186

LoadDB.txt fileabout 33part descriptions 34

LoadDBLanguage.txt fileabout 34part descriptions 35

loadingaddress data 196commodity codes 148language data 35suppliers from Ariba SN 229

localeconsiderations for SAP integrations 117for new users 170for non-English configurations 115objects 98

locale integration eventscountries 107CountryLanguagePull 108CountryMapPull 108CountryPull 107for languages 104for locales 100LanguageMapPull 105LanguagePull 104LocaleIDPull 100LocaleMapPull 102LocalIDPull 101

Locale parameter 257locale parameters

default settings 103setting 115

LocaleID fields 101LocaleIDPull integration event 100LocaleLanguage integration event 102LocaleMap fields 102LocaleMap.csv file 102, 106LocaleMapPull integration event 102locales

character encodings 110default mappings 110defined 98for suppliers 107integration events and parameters 100language, country, and language variant 98preferred settings 98resource files 99setting default 103specified in login URL 99translated versions of names 102

LocalIDPull integration event 101locations, supplier 218logging errors 69LoggingName parameter 45, 246login URL, specifying locale 99LogNonFatalErrors parameter 69, 255loops in cXML templates 92


Index

Mmanually maintained data, exporting 73ManuallyMaintained adapter source 31mapField key 60, 262mapped data

about 18, 25canonical values 25data file formats 26data files 25shared across partitions 25types 18

mapping filesfield descriptions 26formats 26partitioned 25unique key 26

mapping integration events 27MappingLog log listener 158mappings

commodity codes 145customizing encodings 110default locale settings 110removing from a field 81units of measure 188, 191units of measure considerations 193

MapType parameter 28mapValueType attribute 28mark and sweep 251MaxAccountingSplits parameter 207MergedSchemaName parameter 48message configuration files

Ariba File Channel example 256defined 39event source parameter 251example 245export events 70IgnoreSourceOfTruth parameter 33multiple 42parameters 245understanding 41

message configuration parametersSee also data source parametersabout 245Channel 245default channel parameters 255

Disable 245ExecutionNode 245IncrementalPull 246LoggingName 246MessageParametersOperation 252Request-specific 248Schedules 246SchemaName 248TopicName 247Visible 247

message definition filesabout 39defined 39example 56, 243export events 70parameters 244restarting Ariba Buyer 46

message definition parametersSignature 244TopicName 244Type 244

message types 40MessageConfiguration.table 41MessageConfigurationFiles parameter 45MessageDefinition.table file 39, 56, 243MessageParameters parameter 246messages, defined 38metadata XML files

accounting combinations 212example 215extension files 55

metaDataIntegration field property 50, 79metadataIntegrationTypeOverride field

property 50metadataIntegrationTypeOverride key 76,

263migrated configurations, disambiguating

users 163modifying

multilingual strings 24schemas 47user profiles 160

ModifyUserProfileOnInitialLogon parameter 170


Index

multilingual configurationsSee also global instanceadditional information 111and ERP systems 97defined 14, 97getting more information 119including English 105language directories 100LanguageLanguagePull integration event

61locale objects 98overview 97, 113resource files 99

multilingual data 21multilingual strings, primary translation 24multilingual uses, CSV file format 19multiple CSV files as data source 20multiple Excel worksheets, working with 66multiple message configuration files 42

NNAICS

about 141sample file 148

Name parameter 260naming

exported files 71integration events 45system for suppliers 220

None value for fields 50non-English configurations

See also multilingual configurationsadditional information 111character encodings 113getting more information 119overview 113

NONMAPPEDCOMMODITY commodity code 157

North American Industry Classification System. See NAICS

notEquals key 264Notification of Import Mapping Failure 158notIn key 265null, in CSVReader 259

Oobject manager configuration file 74object model commodity codes 143ObjectManager.acf 74OnEmptyFile parameter 258OnEmptyLines parameter 258OnInvalidData parameter 259Operation parameter 252Operation parameter options

Create 252Delete 252Load 252Load And Delete 253Update 252Update And Delete 252Update Elements Only 253

operations, batch 58Oracle configurations

accounting entities 206currency considerations 129units of measure 194UOM_CODE 194

Oracle Financialsand multilingual data 97partition currency considerations 136

order methods in supplier location 227orders, split by shipping address 228organic user growth

about 170adding users 161, 170configuring 170

organization IDsabout 219adjusting 239

Organization.csv file field descriptions 162Organization_Export.csv file 162OrganizationExport integration event 162OrganizationPull integration event 162organizations

default organization ID 162defined 160supplier considerations 162

ORMS field value 30


Index

Pparameters

See also parameters for accounting; application; channels; commodity codes; currency; data sources; locale; message configuration; message definition; users

Ariba cXML Channel 84AribaDBCharset 114AutoSetAdapterSourceAfterManualModif

ication 32channel 255data source 249, 254DefaultLanguage 24, 106DefaultLocale 103DefaultOrganicUserLocale 103DefaultUnitofMeasure 194DetailFileName 21, 64, 66EventSource 49, 58, 251ExcludeSupplierDirectCatalogItems 231ExecutionNode 44FileName 57Formatters 80, 263HeaderFileName 21IgnoreSourceOfTruth 32, 33IncludeLocationRef 69, 255integration event files 243, 244InternalVectorFields 68JoinFields 64LoggingName 45LogNonFatalErrors 69, 255mapField 60MapType 28MergedSchemaName 48message definition files 244MessageConfigurationFiles 45ParentField 64performance-tuning 230ResourceFilename 23RowDelimiter 69SAPAdapterLocale 117SubmitSupplierLocationCondition 241System.Database.AribaDBCharset 114

System.Messaging 85TopicName 41Type 41UnspscAuditFile 146VectorFileName 20visible 46

Parameters.table file settings 55ParentField parameter 64, 250partitioned commodity codes 143partitioned data

about 159and integration events 37type 18

partitioned mapping files 25PartitionedCommodityCode.csv file


partitions, deleting languages 104PasswordAdapters parameter 163PeopleSoft configurations

accounting fields for 206currency support 130historical currency conversion

considerations 138performance

currency conversion rate cache 122default language considerations 116

performance-tuning parameter 230permission integration events

EditPermissionPull 176ExecutePermissionPull 177load order 186PermissionExport 176PermissionPull 175RolePermissionMapPull 173, 183

permission map 183Permission.csv file


Permission_Export.csv file 176PermissionExport integration event 176PermissionMapPull integration event 183PermissionPull integration event 175


Index

permissionsSee also groups; roles; usersabout 171assigning to groups 183assigning to users 185associating with roles 183configuring 171default configuration 172inheriting from groups or roles 173integration events for 175setting for users 167

postal address. See addressesprecision, in currency 132preferred currency 123Preferred field in mapping files 26preferred locales 98primary translation of a string 24Product.csv file in CSV configurations 205profile information

suppliers 217users 159

PropagateDefaultShipping trigger action 213PropagateDefaultShippingOnChange trigger

example 213properties

integration field 60, 75, 261metaDataIntegration field 79PushOnly 247rank field 77sourceOfTruth field 30, 168

Publish events, making visible 46Publish message type 40pull events

language 22, 60simple 21, 55

punching out, units of measures 194PunchOut

catalog 239considerations 194

PunchOut itemscommodity codes for 157NONMAPPEDCOMMODITY 157Notification of Import Mapping Failure

158

purchase requisitions, adding extrinsics 213purchasing cards (PCards) 227PushOnly property 247

Rrank field property 72, 77reactivating deleted suppliers 238rebuilding catalog indexes 234reciprocal conversion type 125reciprocal historical rate for currency 128Reference value for fields 50ReindexSearchIndex scheduled task 234reinitializing integration events 46reporting, dual-currency 123Request-Reply message type 40Request-specific parameters 248requirements, Japanese-language

configurations 117resource files 99resource.date.csv file 100ResourceFile schema 49ResourceFilename parameter

about 23, 249wildcards in 23

ResourceFileSchema schema 22resources for multilingual data 23role integration events

load order 186RoleExport 179RolePull 177

Role.csv fileexample 178field descriptions 178

Role_Export.csv file 179RoleExport integration event 179RolePermissionMap.csv file


RolePermissionMapPull integration event 173

RolePull integration event 177


Index

rolesSee also groups; permissions; usersabout 171and groups 173assigning to groups 182assigning to users 184associating permissions 183configuring 171default configuration 172integration events for 177

RowDelimiter parameter 69, 255

Ssample data, commodity codes 148SAP systems

account type and assignment accounting information 155

accounting fields for 206accounting information by company code

155bank selling rates 138currency conversion rate types 137currency support 130locale considerations 117Type M currency conversion rates 138

SAPAdapterLocale parameter 117scheduled tasks

AribaNetworkFullSubscriptionSync 230AribaNetworkOrganizationSync 229CommonSupplierSyncUsingSupplierLoca

tionID 229GetPendingAribaNetworkOrganizationSy

nc 229ReindexSearchIndex 234SupplierLocationCheck 240UpdateSupplierPendingItems 231, 239

Schedules parameter 246schema definitions 41SchemaName parameter 248

schemasabout 39creating new 47data pull 47default configuration 49integration 46modifying 47ResourceFile 49ResourceFileSchema 22SimpleFile 49SimpleParams 49using existing 47

scope, setting for fields 50Separator parameter 259server resource files 99Service message type 40SetSupplierLocation action 226SetSupplierLocationOnSupplierChange

trigger 226shared addresses

about 195field descriptions 197

shared commodity codes 143shared data

See also mapped dataaddresses 195

shared user integration eventsSharedUserAddressMap 196SharedUserPermissionMapPull 185SharedUserPull 160SharedUserRoleMapPull 184SharedUserShipToAddressMap 167SharedUserSupervisorPull 165

shared users 159SharedUser.csv file


SharedUserAddressMap integration event 196, 199

SharedUserPermissionMap.csv file 185SharedUserPermissionMapPull integration

event 185


Index

SharedUserPull integration event 160SharedUserRoleMap.csv file 185SharedUserRoleMapPull integration event

184SharedUserShipToAddressMap integration

event 167SharedUserShipToAddressMap.csv file field

descriptions 199SharedUserSupervisorPull integration event

165shipping information, defaulting 213ship-to addresses

shared users 167shipping addresses 199splitting orders 228

Signature key 41Signature parameter 244simple pull events 21SimpleFile schema 49SimpleMapTypePull integration event 28SimpleParams schema 49single CSV file as data source 20sourceOfTruth field property 30, 168sources of field values 29sourcing events and supplier data 221special characters in a CSV file 199split accounting

about 203configuring 203integration event for 207max accounting splits 207parameters 207

SplitAccountingType.csv fileexample 208field descriptions 208

standard cXML elements 85strings, primary translation 24SubmitSupplierLocationCondition

parameter 241Subscribe message type 40supervisors 164, 165

supplemental source of truth controlabout 31enabling 32

supplier dataabout 217bulk loading 234how it is created 221loading 221sourcing events 221

Supplier Direct partition 221supplier integration events

CommonSupplierIDMapExport 238CommonSupplierIDMapHeaderExport

238CommonSupplierIDMapPull 236SupplierExport 222, 226SupplierLocationExport 222, 226SupplierLocationSupplementExport 222,

229SupplierLocationSupplementPull 222, 226SupplierPull 222, 224

supplier locationsabout 227associating purchasing cards 227change order acceptance 228choosing a preferred location 226contact information 227defined 218defining AribaNetworkID 228detecting errors in 239ghost pcard number for 228order method for 227specifying locales 107validating 241

Supplier Manager, using 234supplier organization considerations 162Supplier.csv file


SupplierExport integration event 222, 226SupplierLocation.csv file



Index

SupplierLocationCheck scheduled task 240SupplierLocationExport integration event

222, 226SupplierLocationSupplement.csv file


SupplierLocationSupplement_Export.csv file 229

SupplierLocationSupplementExport integration event 222, 229

SupplierLocationSupplementPull integration event 222, 226

SupplierPull integration event 222, 224suppliers

See also supplier dataabout 217assigning IDs 232common 218creating during catalog load 230defining supplier profiles 222linking 233, 236loading from Ariba SN 229, 231locations 218managing configurations 234naming 220organization ID 219profile information 217reactivating 238relationship diagram 219

SupplierXMLPull integration event 231symbol, $ 87syntax, $ 87system ID 162system version, commodity code domains

144System.Base.DefaultLocale 103System.Database.AribaDBCharset

parameter 114System.Messaging parameter 85System.PasswordAdapters parameter 163SystemAllNodeUniqueName parameter 149

Ttechnical support (Ariba) xiitemplates for cXML orders 83Threads parameter 260TIBCO ActiveEnterprise channel 38topic names

about 39parameter 41

TopicName parameter 41, 244, 247transaction currency

choosing 123defined 124

translating sets of commodity codes 146triangulated historical rate for currency 128triangulation conversion type 125trigger actions

ariba.procure.core.action.SetAccountingFromCommodityCode 156

DefaultProcureLineItemFromApprovable 214

DefaultProcureLineItemFromRequester 214

PropagateDefaultShipping 213SetSupplierLocation 226SetSupplierLocationOnSupplierChange

226UpdateMoneyFields 126

Type B currency conversion rates for SAP 138

Type M currency conversion rates for SAP 138

type narrowing in integration events 76Type parameter 41, 244typographic conventions xii

UUNCEFACT

standard 188units of measure 189

UnicodeEuro characters 114support for global instance 113

unique key in mapping files 26


Index

UnitOfMeasureCIFMap.csv file field descriptions 192

UnitOfMeasureCIFMapPull integration event 192

UnitOfMeasureLanguagePull integration event 190

UnitOfMeasureMap.csv file field descriptions 191

UnitOfMeasureMapPull integration event 27, 191

UnitOfMeasurePull integration event 189units of measure

about 187allowing non-whole 190ANSI mapping 188default 194in Oracle configurations 194mapping considerations 193mapping files 188PunchOut 194UNCEFACT standard 188, 189

units of measure integration eventsUnitOfMeasureCIFMapPull 192UnitOfMeasureLanguagePull 190UnitOfMeasureMapPull 27, 191UnitOfMeasurePull 189

UnitsOfMeasure.csv fileexample 190field descriptions 190

UnitsOfMeasureCIFMap.csv file 188UnitsOfMeasureMap.csv file 188unpartitioned data

loading 189shared users 159

UNSPSCaudit files 146classification codes 141code mapping example 152

UNUOM. See UNCEFACTUOM. See units of measure

UOM_CODE 194UOMInfoPull integration event 194Update And Delete Operation option 252Update Elements Only Operation option 253Update Operation option 252UpdateMoneyFields trigger action 126UpdateSupplierPendingItems scheduled task

231, 239useExplicitNulls parameter 259user accounts. See usersuser integration events

Organization Export 162OrganizationPull 162SharedUserPull 160, 163SharedUserShipToAddressMap 167SharedUserSupervisorPull 165UserPull 160, 165

user parametersApplication.Authentication.ModifyUserPr

ofileonInitialLogin 168Application.Authentication.ModifyUserPr

ofileOnInitialLogon 170Application.Authentication.OrganicGrowt

h 170Application.Base.Data.DefaultOrganicUse

rLocale 170DefaultOrganicUserLocale 170ModifyUserProfileOnInitialLogon 170PasswordAdapters 163

user preferences 167user profiles

modifying 160validating 169

User.csv fileexample 166field descriptions 166

UserPull integration event 160, 163, 165


Index

usersSee also groups; permissions; rolesadding 160, 161adding to groups 181adding with organic user growth 170Ariba Buyer 159assigning permissions to 185assigning roles to 184assigning to groups 182, 199default configuration 172default currency for 164default organization 160default permissions 167disambiguating 163locale for new 170maintaining lists of 159modifying profiles 160organic user growth 161overview 159profile information 159shared 159ship-to addresses 167, 199specifying supervisor for 164updating information 167validating profiles 169

UserValidation group 169

Vvalidating

supplier location 241user profiles 169

Value field in mapping files 26value for naming 220variants, language 98VectorFile schema 49VectorFileName parameter 20VectorFilename parameter 250versions

commodity code domain 144vertical bar (|) character 88viewing an object’s adapter source 31Visible parameter 247visible parameter, Publish events 46

WWeb server resource files 99wildcards

in ResourceFilename parameter 23using in commodity code mapping 153

ZZARIBTVARV parameter 138

ARIBA, INC.

807 11th AvenueSunnyvale, CA 94089 USATelephone: 650.390.1000Fax: 650.390.1100

www.ariba.com

ariba buyer 8.2 data load guide - connect.ariba.com · copyright © 1996-2004 ariba, inc. ariba and...

Documents