Datalink (Classic) Coupa Connector Guide

◆ Applies to: Datalink (Classic) 4.8.7 and later

Use the Datalink (Classic) Coupa Connector to export Coupa data then import it into your Apptio instance to generate reports in Apptio Vendor Insights.

Configure the connector

1. Open the Datalink (Classic) Agent, then click New Connector.
2. Click the Coupa Connector.
   
3. Enter a Connector Name .
4. Optionally, select Add this connector to a connector group. For information on connector groups, see Group multiple connectors.

Define the query information

• REST URL - The URL for your Coupa instance.
• Requires Authentication - Select this check box, then select OAuth2.0 as the Authentication Type .

• Authorization_Url - https://{organization_name}.coupahost.com/oauth2/token

• Token_Url - https://{organization_name}.coupahost.com/oauth2/token

• Client_Id - See Set up OAuth Client ID on Coupa for information on generating Client ID.

• Client_Secret - See Set up OAuth Client ID on Coupa for information on generating Client Secret.

• Grant_Type - Select "client_credentials" from the drop-down.

• Scope - Scope can be defined on the page when setting up Client ID and Client Secret on Coupa. See Set up OAuth Client ID on Coupa for information. It is recommended to add only the scopes which are applicable/related to the query.

After entering all the details, select Get OAuth2.0 tokens to fetch the tokens.

Define the properties

Select a retrieval mode and a Coupa object.

Select a retrieval mode

Configuration steps differ for each retrieval mode:

• Initial Data (All data) - Retrieve all data up to the connector run date. This destination transformation is set to overwrite the previous data.
• Initial Data (Data starting from) - Retrieve data starting from a set month and year up to the connector run date (>= [start month] / 01 / [start year]). This destination transformation is set to overwrite the previous data.
• Delta Data (Starting from beginning of last month) - Retrieve data from the beginning of the previous month up to the connector run date (>=[last month’s month] / 01 / [last month’s year]). This destination transformation is set to append the new data to the previous data.

When first setting up the Coupa integration with Apptio , it is recommended that you use an Initial Data retrieval mode to populate Apptio with your required historical data. The initial data will populate the time period specified using the Specific Time options in the Apptio destination , Time Period setting (see Configure the Apptio destination settings ). The Delta Data  option is designed to be the retrieval mode for scheduled connector runs. This option serves to retrieve records that have been updated in Coupa, and then append them to the same table in the same time period. In this case, you can then use the TBM Studio Remove Duplicates feature to help ensure that only the latest version of a given record is used in Apptio .

NOTE : Coupa recommends using the Initial Data (Set Start Date) option for initial data loads to avoid transferring unnecessary data volumes. Although Initial Data (All Data) may be appropriate for Suppliers and Contracts.

Select a Coupa object

You can access and import the following types of Coupa API data and filter criteria (in addition to the Retrieval Mode data range) into your Apptio instance:

NOTE : Invoice Lines and Invoice Line Accounts are filtered by the status of their parent Invoice.

Select a status filter

• Default - Set queries to the Coupa API to Apptio 's default status filters.
  These filters are:
  • Active and Inactive for the supplier object.
  • Published and Inactive for the contracts object.
  • Approved and Voided for both the invoice and invoice lines object.
    For example, querying the supplier object with the Default status filter results in a set of records that have either Active or Inactive status. Queries to the purchase order and purchase order line objects do not include any status filters by default.
• All Statuses - Remove all status filtering from the queries to the Coupa API.

Retrieve additional fields

You can enter key-value pairs to specify additional columns to be included in the table uploaded to TBM Studio , and the JSON properties from which those columns will pull their values.
To do so:

1. Select the Retrieve Additional Fields (Advanced) check box.
2. In the Additional Fields box, enter key-value pairs per line, using a colon as the delimiter (for example, Cost Center: order-lines.custom-fields.cost-center.name ).

The JSON properties will be pulled relative to the Coupa object being queried. For Purchase Order Line Account and Invoice Line Account objects, the root object for each record will be account-allocation if the given account is a member of an account allocation, otherwise the root object will be account. For example, the additional field "Some Field Name: some.path" for an Invoice Line Account object would pull its value from invoice.invoice-lines.account-allocations for accounts that are members of an account allocation, and invoice.invoice-lines.account for accounts that are not members of an account allocation.

Configure the Coupa Connector Apptio destination settings

Link your connector to your Apptio destination. From within the connector, click Apptio Destination on the left menu to jump to these settings. If the connector is a part of a connector group, the Apptio Destination settings for Apptio Instance , Domain , Project , and Branch are disabled and instead inherited from the group settings.

Apptio Version - Select your destination Apptio version:

• R11 :
  • Host name - Enter the Apptio server URL. Select Use SSL to encrypt the data using SSL (Secure Sockets Layer).
  • Username - Enter the user name that will be used to log in to the Apptio instance (for example, JoeUser@apptio.com).
  • Password - Click Edit Password to enter or edit the password associated with the username.
• R12 with Frontdoor - Select the Apptio Instance from the list of valid Access Administration applications.

Domain - Enter the domain name of the destination Apptio instance.

Project - Enter the name of the destination project.

Table - Enter the name of the destination table. This is the name of the table only, not the URL or path information. If the table does not exist, it will be created.
NOTE : Some connectors do not display this option when the target table is predefined as part of an application.

Source System - Enter the name of the source system for the data.

Time Period - It is recommended that you select Specific Time as the Time Period , then select the date of the beginning of a project or the first month of the fiscal year. It is recommended that you use one of the Initial Data retrieval modes (see Define the properties ) to populate your Apptio instance with historical data. This data is placed in the time period specified by the Specific Time settings.

Validation - Select this check box to validate the uploaded data using the existing dataset. If the columns do not match, the uploaded data will be held in a staging area but will not be added to the dataset. An email is sent to Datalink (Classic) Admin users notifying them that the upload did not pass validation. In this case, the Admin can go to the TBM Studio Data tab and manually approve the upload. It is a best practice to validate the data before you upload it.

Disable Logins - Select this check box to disable log in to the destination Apptio instance. This option is available only when the destination Apptio version is R11.

Advanced Options - Click to set the following advanced options:

• Data Encoding - Select the character encoding to use with queries. This option is available only when the destination Apptio instance is R12.
• Category - Enter a category for the table. This option is available only when the destination Apptio instance is R12.
• Branch - If using the branching feature in TBM Studio R12, enter a branch name to upload data into that branch. For more information, see Branch projects .
  • This feature requires R12.5 or later. If using an earlier version of R12, the setting is ignored, and the data is loaded into the trunk.
  • If the branch name is misspelled or no longer exists (for example, the branch is closed, and a subsequent build completes), an error is reported.
• Transformation - Select a value appropriate for the retrieval mode you selected:
  • Initial Data (All data) - Set to Overwrite the previous data.
  • Initial Data (Data starting from) - Set to Overwrite the previous data.
  • Delta Data (Starting from beginning of last month) - Set to Append the new data to the previous data.

Warning : In Datalink (Classic) 4.8.15 and later, account segment columns in tables uploaded by the Datalink (Classic) Coupa Connector for Purchase Order Line Accounts and Invoice Line Accounts adhere to the following new naming conventions:

• Account Segment 01-09 remain the same (a 0 precedes numbers 1-9 ).
• Account Segment 010 and above no longer require a 0 before the number. For example, Account 010 is now Account 10, and Account 011 is now Account 11.

When appending to a table that used the previous naming convention (Account 010 instead of Account 10), the new, renamed account segments columns are added to the table. Table records that existed prior to Datalink (Classic) 4.8.15 continue to store account segment data using the previous naming convention.

NOTES :

• All Coupa Connectors must be scheduled to run monthly.
• The Datalink (Classic) schedule does not support a 13-month calendar. In this case, use a weekly or monthly schedule.
• Select the yearly option to get initial data for all Coupa objects.

Expected values

The following table shows the values expected when pulling data from Coupa:

Troubleshoot issues with the connector

If the connector fails during execution, try clearing the Validation check box. Run the connector, then re-check the Validation check box for future execution runs.

Note that for Datalink (Classic) 4.8.8 (new-master-12000 build) and later, the execution ID is not present in log files.