Datalink (Classic) Digital Fuel Connector Guide

Edit online

◆ Applies to: Datalink (Classic)  4.6.18 and later

Use the Digital Fuel Connector to extract data from Digital Fuel database instances into your Apptio instance.

Configure the connector

  1. Open the Datalink (Classic) Agent, then click New Connector.
  2. Click the Digital Fuel 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.

Specify the Digital Fuel database settings

Enter the following Digital Fuel database instance information:

  • Server - Enter the Digital Fuel database server name or IP address. For example, dftest-oracledb.com or 10.100.200.300 .
  • TCP/IP Port - Optionally, enter the Digital Fuel Oracle database instance port number. The default value is 1521.
  • SID - Enter the Digital Fuel database Oracle System Identifier. For example, orcl .
  • Credentials - Enter the user name and password used to log in to the database instance.

Define the Database Query

In the Database Query box, enter or paste the SQL query used to retrieve data to send to Apptio . Note, all data files loaded into Apptio must have a header row. You can scope the values for query arguments using {MM} for the month (01-12), and {CYYY} for the four-digit calendar year. Variables can only be used once in the query. Any subsequent occurrences are placed into the query without substitution, which will likely cause an error. To make multiple references to the variables, set a SQL variable in your query similar to SET @Datestring = {CYYY}{MM} , then reference this variable throughout your query in place of {CYYY}{MM}.

Configure the 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 into 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 - 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.
NOTE : The Offset from Current Month option loads to a period that is offset from the source month. A positive offset indicates the number of future periods, and a negative offset indicates the number of past periods.

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. Learn more about Email Notification Workflow for Validation Failure .

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 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.

Configure connector email notifications

After you configure email notifications for your Datalink (Classic) Agent See Configure agent email notifications Configure agent email notifications (see - link requires TBM Connect credentials) , you can configure email notifications for each connector. You can specify that an email notification be sent when a connector succeeds or fails. Click Notify or Notify & Archive in the left menu to jump to the email configuration settings; otherwise, scroll down to the Notify or Notify & Archive section.

  1. Select your email preferences:
    • Send an email notification when this connector succeeds .
    • Send an email notification when this connector fails .
  2. In the To  box, enter one or more email addresses, separated by a comma or semicolon. Enter a subject in the Subject box.

Schedule the connector

Schedule the connector to run at specific times.

Set up and enable the schedule

  1. From within the connector, click Schedule on the left menu to jump to these settings.
  2. Select Enable Schedule .
  3. Enter your schedule options:
    • Frequency sets the schedule options.
    • 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.

Test the connector

Click Test in the upper-right corner to test the connector. If there is an error, it will be flagged and you can then jump directly to that part of the connector definition. Clicking Test saves any changes made to the connector.

Save the connector configuration

Click Save in the upper-right corner to save the connector. If there is information missing from configuration, it will be flagged for you.

Execute or cancel the connector run

  • To run the connector, open the Datalink (Classic) Agent, click Actions next to the connector, then click Run Now .
  • To cancel a currently running connector, open the Datalink (Classic) Agent, click Actions next to the connector, then click Cancel Run .

View execution history

View a report of execution results that lists the sources, destination, target period, execution start and end time, an explanation of the results, and the number of uploaded bytes for each run of the connector.

  1. Open the Datalink (Classic) Agent, click Actions next to the connector, then click View Execution History .
  2. By default, the Execution History displays run information for the previous three months. To view up to 12 months of history, change the values in the From and Until fields, then click Get Execution Records .