Datalink REST Service connector

Edit online

Use the REST (Representational State Transfer) Service connector to extract data from a RESTful web-services enabled application, then load the data into your Apptio instance.

The REST Service connector supports the following file formats for data ingestion.

XML

TXT

JSON

XLS

TSV

CAT

CSV

XLSX

A connector enables you to extract and load data from REST applications into an Apptio instance. The REST connector allows you to connect to any RESTful API endpoint and pull in data to Apptio destination. It is similar to the REST connector on Datalink Classic. Releasing the REST connector on new Datalink will help in migrating customers over from Datalink Classic. The connector does not write anything to the source system.

Datalink extracts tables on a schedule. Schedules can be set up and run on daily, weekly, monthly, and custom cadences. The REST connector supports both Gregorian and non-Gregorian calendar types.

In subsequent release, the REST connector will be enhanced with custom mime support.

The REST connector supports only r12 as a destination. The connector is compatible with all versions of R12 Apptio product version. OAuth 2.0 Grant type is supported by the REST connector.

Supported custom headers

The REST Service connector supports an extensive list of custom headers.

API_SECRET

LOB

BucketSecretKey

API_KEY

x-ApplicationKey

$Fromdate

Accept

Title

$Todate

externalIdroleARN

ID

env

roleSessionName

Tags

format

Content-Type

privateKey

key

CWR_Type

tenancyId

name

Cost_Center

region

password

Employee_ID

authUserId

grant_type

Position_ID

keyFingerprint

company_name

location

cache-control

username

Supplier

x-api-key

Token

Manager

api-version

Hire_Date

BucketAccessKey

Configure the connection

  1. Open Datalink , and select New Connection .
  2. Enter a Connection Name , and then select Next .
  3. In the Data Type window, select REST Service , and then select Next .
  4. Select an agent from the list, and then select Next

Configure the Apptio destination settings

  1. Link your connector to your Apptio destination:
    • Instance Enter your Costing Standard instance.
    • Domain: Enter the domain name of the destination Apptio instance.
    • Project: Enter the name of the destination project.
    • Branch: If you are using the branching feature in TBM Studio R12, enter a branch name to upload data into that branch. For more information, see Best practices: Branching projects .
      • This feature requires R12.5 or later. If you are using an earlier version of R12, then the data is loaded into the trunk.
      • If the branch name is misspelled or no longer exists, for example, if the branch is closed and a later build completes, then an error is reported.
    • Source: Enter the name of the source system for the data.
    • Transformation - Select from the following:
      • Append: Add the data to the end of the destination table.
      • Overwrite: Replace the existing data in the table with the new data.
    • Category: Enter a category for the table. This option is available only when the destination Apptio instance is R12.
    • Time Period: Select the time period to load. Select the current or previous month based on the date the load occurs, or select a specific month and year.
  2. Select Next .

Configure the REST source details

Enter the following REST query information:

  1. Under Authentication Type , select a suitable authentication type for your connection. The supported authentication types include the following: Basic, Digest, OAuth 2.0, Custom and Apptio .
    Note:

    The Apptio authentication type supports the following headers: apptio-current-environment , apptio-opentoken , app-type , app-version , and content-type .

  2. In the REST URL box, enter the base URL for your REST instance. Example

    https://company.restservice.com/

  3. In the URL Path , enter the Resource Path. Example

    api/v1/2023-01?name=john&age=23

    Note:

    Using this field, you can replace a URL's date element with a filename pattern.

    To reference date elements that change on a regular basis, you can use the following date variables.

    {M} - One-digit month (1, 2).

    {MM} - Two-digit month (01, 02)

    {MMM} - Three-letter month abbreviation (Jan, Feb).

    {CY} - Two-digit calendar year. This assumes a 20 prefix.

    {CYYY} - Four-digit calendar year (2012, 2013, 2014).

    Example:

    api/v1/{CYYY}-{MM}?name=john&age=23

  4. Depending on the selected authentication type, configure the following settings.
Authentication Type Settings
Basic

Configure the following settings:

Username: Enter a valid username.

Password: Enter the password.

Digest

Configure the following settings:

Username: Enter a valid username.

Password: Enter the password.

OAuth 2.0

With OAuth 2.0 authentication, Datalink gets an access token using the values of the OAuth 2.0 input fields. Datalink encrypts the access token and uses it while executing the connector.

To use the OAuth 2.0 authentication, complete the following steps.

Register Datalink as the client application with your OAuth 2.0 source and make a note of the Client_ID and Client_Secret values.

If prompted for a redirect URL during registration, use the following URLs according to your region:

NA: https://datalink.apptio.com/apptioconnect/app

EU: https://datalink-eu.apptio.com/apptioconnect/app

APAC: https://datalink-au.apptio.com/apptioconnect/app

Enter the information to retrieve the OAuth 2.0 access tokens:

Authorization URL: Enter the URL used for OAuth 2.0 authorization.

Token URL: Enter the URL used for retrieving and refreshing access tokens.

Client ID : Enter the Client_ID for the registered Datalink application.

Client Secret: Enter the Client_Secret value for the registered Datalink application.

Scope: Optionally, assign a scope to limit the amount of access granted to an access token. For example, an access token issued to a client app may be granted READ and WRITE access or just READ access.

Grant Type: Select a Grant Type. The options are
  • Authorization Code
  • Client Credentials

When the OAuth2.0 access token expires, Datalink automatically attempts to refresh it.

Custom

This method enables additional authentication with the REST connector. To use the Custom authentication, configure the following settings:

Header Name: A mandatory field for Custom Authentication type, it is used to set Authorization header or any header required to send the request.

Header Value: A mandatory field for Custom Authentication type, it is used to set a value corresponding to the Header Name field.

Apptio

Configure the following setting:

Need Refresh Token: Use this setting to generate Access Administration token on runtime and schedule the connection. Select Yes , and enter the Frontdoor Key and Frontdoor Secret .

  1. In the Destination Table Name box, enter the name of the destination table. Provide only the table name; do not enter the URL or path information. If the table does not exist, it will be created.
  2. Under Time Period , specify the time period to load. The time period will be used to replace the Date variables like {D}, {DD}, {M}, {MM}, {MMM} , {CY}, {CYYY} given in the resource path URL, to fetch data from the source for the selected time period.
  3. Select Next .

Schedule the connection

Schedule the connection to run at specific times.

  1. Choose between a time-based schedule and an event-based schedule.
  2. Enter the schedule details.

    Run dates are in your selected time zone and, upon save, are displayed in the Next Run column in the connector list. If you do not select a time zone, UTC is used.

Save the connection configuration

Select Complete in the lower-right corner to save the connection. If there is information missing from the connector, it will be flagged for you.

Run the connection

Your connection runs according to the schedule you specified for it.

To run the connection manually at any time, select run icon next to the connection in the list.

The status shows as Run initiated . When the connection completes successfully, the status changes to Success .

View execution history

View a report of execution results that lists details for each run of the connector.

Select Information Icon next to the connection.

From the Run History list, select a date to get more details about that execution.

REST 2.0 BETA connector

There are two benefits for REST 2.0 BETA connector:

  1. Custom headers
  2. Pagination

Custom headers

There is no limit in custom headers that REST 2.0 BETA connector supports. You can add any key value pair.

Pagination

Four types of pagination are supported here:

  1. No Pagination (default)
  2. Limit Offset (new partial UX introduced)
  3. HATEOAS (new partial UX introduced)
  4. LINK-HEADER (new partial UX introduced)

No Pagination

This is the default one. No additional field is required to configure.

Limit Offset

If you select this, additionally four fields should be configured:

  1. Limit Param Name: Its a mandatory field, need to mention the PageLimit parameter name.
  2. Limit Param Value: Its a mandatory field, need to mention the PageLimit value.
  3. Offset Param Name: Its a mandatory field, need to mention the Offset parameter name.
  4. Payload Locator: Its not mandatory, but if the actual data is inside another JSON object, then need to specify the payload locator path using ^ as a delimiter.
    Note:

    Limitation and Used Cases:

    1. We only supports JSON.
    2. ^ will be delimiter for Payload Identifier, if any element has ^ in there name then process will not work as expected. For example 1. (result^members) to fetch data from members 2. (result) to fetch data from result.
    3. Only supports two level (level1^level2) from root of JSON.
    4. POST method is not supported with Pagination.
    5. Should not enter Limit and offset name in URI path, but can add filters and query parameters to it.
    6. Limit and page number we are not supporting, only offset and limit parameter is supported where offset starts from 0 and keep on adding limit value to it for next page until empty or JSON array size less than limit.

HATEOAS

If you select this, additionally two fields should be configured:

  1. Payload Locator: Its not mandatory, but if the actual data is inside another JSON object, then need to specify the payload locator path using ^ as a delimiter.
  2. Next Link Locator: Its mandatory, should specify the next link locator path using ^ as a delimiter to retrieve the next page URL. The URL should be the complete URL.
    Note:

    Limitation and Used Cases:

    1. We only supports JSON.
    2. ^ will be delimiter for Payload and NextLink Identifier, if any element has ^ in there name then process will not work as expected. For example 1. (result^members) to fetch data from members 2. (result) to fetch data from result. '
    3. Only supports two level (level1^level2) from root element.
    4. POST method is not supported with Pagination.
    5. NextLink Locator should be in response body, if its in header it will not work as expected.
    6. NextLink Locator URL should be the complete URL including the base URL.

LINK-HEADER

The Link header contains one or more links, each enclosed in angle brackets (<>), followed by a rel attribute that indicates the relationship of the link (e.g., next, prev, first, last).If you select this, no additional field is required to be configured.

Example syntax of response headers - Link: <url>; rel="relation", <url>; rel="relation"

Note:
  • We only supports JSON
  • Only supports two level (level1^level2) from root element.
  • Link should come in response headers for this to work. It will be fetching from the page being used in resource path to the last page till rel="next" exist.