Integration Type Considerations

Integration Types

There are two ways to integrate with Coupa:

CSV
API

Considerations

CSV Considerations:

Built-In Integration Dashboard capabilities include:
- History of all import and export integration runs are available with a detailed breakdown of success vs failure
- History of all the failures that ever occurred are also available
Built-in error handling capabilities include:
- Notifying business teams on functional errors and integration admins on technical errors is available by setting those users as Integration Contacts
- Ability for users with specific permissions to view the CSV files to perform any reviews and can take necessary actions
Integration routines with huge data sets/volumes should consider CSV approach
Coupa can archive the CSV files on the SFTP for reprocessing them if needed
Multiple CSV files can be processed in parallel at a time
You need an easy audit trail of data moving between systems
You want a clearly defined hand-off between internal and external systems
Your IT team is more comfortable parsing data and doing data transformations with CSV flat files as opposed to using XML data and making REST API calls
In built Coupa internal integration monitoring.
After a successful sftp file read/write, middleware should automatically close the sftp connection.

API Considerations:

Use the Coupa REST API when
- You need to update data in Coupa real time
- You have a need to orchestrate different service calls across multiple systems
- You want sophisticated error handling
- You need to make frequent API calls with small numbers of records (API should not be used for infrequent batch integrations for example)
Do not use Coupa REST API when
- Bulk import/exporting data
- There is no business need to have real time data integration (e.g. nightly update of users from ERP to Coupa)
- You do not have a middleware tool to simplify and monitor API-based integrations
OAuth2/OIDC Authentication
Customer can perform additional API calls to utilize Coupa Integration and error handling dashboard capabilities.
We do not archive the API request payloads.

Regional/Country Specific Considerations

NA

Do's & Don'ts

Integration Type	Design Element	Recommended Design	Alternative Design	Risky Design	Rationale
CSV	File Naming Convention	File Naming Convention: <IntegrationObject>_<DateTimeStamp>.csv Example: Users_20220128_091003.csv		File Names with out dated time stamp Example: Users.csv	^{Having unique filenames will help to identify the file when troubleshooting issues.}
CSV	File Extension	Use lowercase .csv as file extension		using uppercase .CSV as file extension	^{Coupa doesn't support uppercase.CSV as file extension.}
CSV	File Encryption	PGP key encryption	No encryption		^{Coupa supports PGP key encryption/decryption for both SFTP import and exports of CSV files}
CSV	Special Characters	New Line and carriage return characters should be handled properly. Double quotes should be escaped with additional double quotes. Recommended enclosing every field in double quotes.		Not handling special characters	^{Not handling special characters as part of the integration development will result in failures during the file upload.}
CSV	File Size	File size should not be exceeding 8 MB. Larger files should be split into multiple 8 MB files. Multiple records should be sent in single file.		Sending one file per record into Coupa or files greater than 8 MB.	^{Higher the volume, the longer it takes for the system to complete the import process and potentially impacting other functions of the system.}
CSV	Data Mapping	Include only the fields that are needed for the integration from the headers. Integration Transactional Formats will be used for exports where we can add/remove columns from the CSV file headers.		Including all the fields in the header irrespective of the usage	^{Removing unwanted fields from the CSV file headers will help with the system performance and troubleshooting errors.}
CSV	Parsing Data	Using column names		Using position of the field in the file	^{Using positions to read the data from a CSV file causes issues when the file format changes if an Integration Admin add/removes a field in the integration export formats.}
CSV	Integration Contacts	Setup integration contacts for all the integrations in scope to receive functional/technical error email notifications		Not setting integration contacts	^{By default, all Coupa Admins will receive integration related error notifications. To send emails to specific team members that handles the integrations, setting up integration contacts is the way.}
CSV	SFTP Authentication	SSH Keys	Basic username and password		^{Coupa does support SFTP authentication using SSH keys and basic username/password.}
CSV	SFTP Connection	After a successful sftp file read/write, middleware should automatically close the sftp connection		Leaving the sftp connection active in idle state for longer periods of time	^{Leaving it idle can cause issues where other system won't be able to access the SFTP}
CSV/API	Data Dependency	Orchestrate dependencies by properly spacing inbound files to Coupa Example: Suppliers should be pre-loaded before uploading Remit-To Addresses into Coupa.		Not considering the data dependencies
API	Payload	Choose only the required and used fields for POST/PUT operation. Only one record can be loaded at a time through POST/PUT API action		Including unwanted fields in payload will increase the processing time it takes for each record.	^{API will be much more responsive when the payloads are only including fields that are needed.}
API	Schema Validation	Build the payloads using XML/JSON examples or with no strict schema validations		Building integrations with strict API validations	^{Do not recommend strict XSD validations. This way integration doesn't result in failures when XSD schema changes over multiple Coupa releases.}
API	API Response Filters	Fields query param	API Response Filters	Not using API filters or fields query parameter
API	Parallel Threads	Not to exceed more than 8 parallel threads for all API calls at a given single point in time	No parallel execution and only one API call at a given point in time	More than 8 parallel threads.	Performing API calls using parallel threads will help in processing records faster. Using more than 8 parallel threads will start impacting other functions performed by users in the system.
API	Special Characters	Using CDATA for XML payloads	Passing Content-Type header
API	Authentication	OAuth2/OIDC Clients		API keys	^{API keys feature is being deprecated and is not available for new customers.}
API	Payload Format	JSON	XML		^{Coupa REST APIs support both XML and JSON formats}
API	Error handling	Use Integration Runs API to record the success vs errors and to validate the total number of records that are processed.