Platform

Platform

A place for Apptio product users to learn, connect, share and grow together.

 View Only

Apptio API Demo Scripts 

Wed January 25, 2017 11:48 PM

In this article:

Introduction

Apptio supports three APIs: the Apptio Platform API, the Frontdoor API, and the DataLink API. 

 

This document provides Apptio Platform API demo scripts in one or two commonly-used scripting languages, as well as instructions on how to set up the demo scripts for testing. It also provides users with an orientation to the mechanics of using the API so that they can then apply the learning to their own scripted solutions.

 

Datalink uses the Apptio API to transport data. The Apptio API can also be used independently for data upload or download operations (for example, batch operations), which Datalink doesn't readily support. Use of the API is more involved and usually requires some scripting or programming background to implement and maintain. Therefore, it is recommended to use Datalink unless you have advanced needs and resources to implement and maintain the API implementation.

 

The Apptio API is distinct from the Datalink API: The Apptio API is used to upload to Apptio project tables, or download from Apptio project tables (including those in reports), and it is what Datalink uses under the hood. The Datalink API is used to automate Datalink agent connector execution. To learn more about the Datalink API, refer to DataLink API Usage & Sample Scripts.

 

The script attached to this article has been tested against the following specific releases, however, it should work with other releases too:

  • r11.8.3.5
  • r12.3.2

 

Basic operations

The first demo script is named ApptioAPI_Demo_Basic_v2.ps1. It is written in Windows PowerShell, which is widely available on Windows systems, can leverage .NET libraries, and can be used by software, such as SQL Server Management Studio, to implement load and extraction from SQL Server. (This subject will be covered in more detail in future releases of this document.)

 

The script is attached and commented. The usage is as follows; This is displayed if the script is executed with no arguments:

 

You need to specify -up or -down.
Usage (using API Keys):

ApptioAPI_Demo_Basic_v2.ps1 -help


ApptioAPI_Demo_Basic_v2.ps1 -down [-APIURL "valid API URL"]

[-downtimeperiod "Apptio time period"]
[-downloadfolder "folder to download to"] [-downfile "file name"]


ApptioAPI_Demo_Basic_v2.ps1 -up [-v1] [-upfile "path to file to upload"]

[-apptiohost "https://domain-r12.apptio.com"]
[-domain "domain.com"] [-project "Project Name"] [-table "Table Name"]
[-uptimeperiod "Apptio time period"] [-transformation overwrite | append]

 

Usage (using username/password auth):

ApptioAPI_Demo_Basic_v2.ps1 -help


ApptioAPI_Demo_Basic_v2.ps1 -user "username@domain.com" -pass "password"

-down [-APIURL "valid API URL"]
[-downtimeperiod "Apptio time period"]
[-downloadfolder "folder to download to"] [-downfile "file name"]


ApptioAPI_Demo_Basic_v2.ps1 -user "username@domain.com" -pass "password"

-up [-v1] [-upfile "path to file to upload"]
[-apptiohost "https://domain-r12.apptio.com"]
[-domain "domain.com"] [-project "Project Name"] [-table "Table Name"]
[-uptimeperiod "Apptio time period"] [-transformation overwrite | append]

 

It is possible to provide combinations of the optional arguments and execute without modification. However, if you want to use only the "-up" and "-down" flags, you can edit the script to modify the necessary variables. Following is an explanation of the variables, what they contain, and what you may need to do for setup.

 

Authentication Arguments

The following arguments support API Keys authentication. This is the preferred method for use with v12 environments. 

 

-pubkey "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  This argument supplies a valid API Key public key.  See  API keys and Frontdoor: Overview and FAQs for more information on how to obtain a public key.

 

-secret "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"  This argument supplies a valid API Key secret key. See  API keys and Frontdoor: Overview and FAQs for more information on how to obtain a secret key.

 

-envid "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  This argument supplies a valid v12 environment ID. See API: Get Frontdoor Environment Information  for information on how to obtain this ID using the API. You can also request it from Apptio Support or your CSM or CSE.

 

The following arguments support username / passsword authentication. This is for backward compatibility with r11 environments and should not be used in v12 environments. 

 

-user "user@domain.com" -pass "password"  These arguments specify a user account that has access to the project that contains data to download and the password for that account. Remember that if you create a new account to support this, you will need to edit the account after creation to uncheck the "Single-Use Password" check box, or the API may not respond.

 

Download Arguments

-APIURL "valid API URL"  This argument specifies a valid, quoted, Apptio API URL. This can be obtained from almost anything in Apptio by clicking the export icon, which appears as follows: 

This icon appears in the r11 Data tab of the studio in association with any Transform Table or Raw Table view, or via the "Export" button in the ribbon of the TBM Studio in r12 when a table is selected.

 

In reports, you can access it by right clicking at the base of a table (for example, in the totals row area).

  

-downtimeperiod "Apptio time period"  This argument specifies a correctly-formatted Apptio time period to download from (for example, Aug:FY2016). This will replace any time period that happens to be in the APIURL.

 

[-downloadfolder "folder to download to"]  This argument specifies the folder for the downloaded data.

 

[-filename "file name"]  This argument specifies the name for the file to which the data is downloaded.

 

Upload Arguments

[-v2]  This argument specifies use of the API v2 URL for upload. This is optional and is only necessary in specific situations.

 

[-upfile "path to file to upload"]  This argument specifies the path to a file that is to be uploaded.

 

[-apptiohost "https://domain-dev.apptio.com"]  This argument specifies the Apptio host instance where the project the file is being uploaded into resides.


[-domain "domain.apptio.com"]  This argument specifies your company's domain.

 

[-project "Project Name"]  This argument specifies the project name into which the file will be uploaded.

 

[-table "Table Name"]  This argument specifies the name of the table into which the data is to be loaded.


[-uptimeperiod "Apptio time period"]  This argument specifies a correctly-formatted Apptio time period into which to upload (for example, Aug:FY2016).

 

[-transformation overwrite | append]  This argument specifies whether or not the table should be overwritten or appended to.

 

(Back to top)

 

 

This article is open for your feedback. At the bottom of this screen, click Add a comment.









#TBMStudio

Statistics
0 Favorited
82 Views
1 Files
0 Shares
7 Downloads
Attachment(s)
zip file
ApptioAPI_Demo_Basic_v2.zip   3 KB   1 version
Uploaded - Tue October 29, 2024

Comments

Thu October 22, 2020 12:49 AM

This was a great source that I have used to build a std API interface to use. I have extended this by including the data download, validation, cleanup and upload all together. I have written a post about what I have done here: ETBMA R12 Case Study - Powershell and the Apptio API's  


#TBMStudio

Fri March 08, 2019 01:37 PM

Bear in mind per the Browser Security Protocol Update blog post Apptio has discontinued support for TLS v1.0 and TLS v1.1 so you need PowerShell to be using TLS 1.2 or higher.  The ServicePointManager.SecurityProtocol Property (System.Net) | Microsoft Docs document describes the utility used to specify TLS version. Command line usage would look like this:

 

PS> [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
PS> Invoke-WebRequest "https://client.apptio.com...

 

Scripts may need to utilize this if it isn't the default in your environment.


#TBMStudio

Thu December 06, 2018 09:37 AM

Super helpful. Thank you.


#TBMStudio

Mon February 26, 2018 12:17 PM

Excellent supplement Robert!


#TBMStudio

Fri January 19, 2018 10:42 AM

Thought I would share my code, maybe it can help another with strict security requirements! 

 

I wrote a PowerShell .ps1 for authenticating via FrontDoor for API calls.  You must authenticate via API.  For my scripts I am using a Windows 2012 R2 server with windows task scheduler.  Couple things to keep in mind.

 

1. You can setup a secured API key if your environment utilizes SSO, this is done through the user account management in Frontdoor.

2. I masked the API key on our server and encrypted it due to security reasons

3. Use at your own risk

4. I would suggest coping and pasting the below into PowerShell ISE for a better view of the code

 

This script is pretty long and if you have any specific questions please let me know!

 

#############################################################################################################

#Script to use API calls for Apptio FrontDoor applications #
#Script written by Robert Schneider December 15th 2017 currently using API Key #
#############################################################################################################

$PSScriptRoot = Split-Path $MyInvocation.MyCommand.Path -Parent #set the current path of the script Get-location |select path 
$secretkey = "$PSScriptRoot\secretkey.pwd" #setting path of secretkey file
$publickey = "$PSScriptRoot\publickey.pwd" #setting path of publickey file

if (((Test-Path $secretkey) -eq $false) -or (Test-Path $publickey) -eq $false){ #testing path for public / secret key file

#below is a custom input form for the public/private key pair
Add-Type -AssemblyName System.Windows.Forms
Add-Type -AssemblyName System.Drawing

$objForm = New-Object System.Windows.Forms.Form 
$objForm.Text = "Public/Private Key Entry"
$objForm.Size = New-Object System.Drawing.Size(300,250) 
$objForm.StartPosition = "CenterScreen"

$OKButton = New-Object System.Windows.Forms.Button
$OKButton.Location = New-Object System.Drawing.Size(75,180)
$OKButton.Size = New-Object System.Drawing.Size(75,23)
$OKButton.Text = "OK"
$OKButton.DialogResult = [System.windows.forms.dialogresult]::OK
$objForm.AcceptButton= $OKButton
$objForm.Controls.Add($OKButton)

$CancelButton = New-Object System.Windows.Forms.Button
$CancelButton.Location = New-Object System.Drawing.Size(150,180)
$CancelButton.Size = New-Object System.Drawing.Size(75,23)
$CancelButton.Text = "Cancel"
$CancelButton.DialogResult = [System.windows.forms.dialogresult]::Cancel
$objForm.AcceptButton= $CancelButton
$objForm.Controls.Add($CancelButton)

$objLabel = New-Object System.Windows.Forms.Label
$objLabel.Location = New-Object System.Drawing.Size(10,20) 
$objLabel.Size = New-Object System.Drawing.Size(280,20) 
$objLabel.Text = "PLEASE ENTER PUBLIC KEY:"
$objForm.Controls.Add($objLabel)

$objTextBox = New-Object System.Windows.Forms.TextBox 
$objTextBox.Location = New-Object System.Drawing.Size(10,40) 
$objTextBox.Size = New-Object System.Drawing.Size(260,20) 
$objForm.Controls.Add($objTextBox)

$objLabel = New-Object System.Windows.Forms.Label
$objLabel.Location = New-Object System.Drawing.Size(10,100) 
$objLabel.Size = New-Object System.Drawing.Size(280,20) 
$objLabel.Text = "PLEASE ENTER PRIVATE KEY:"
$objForm.Controls.Add($objLabel)

$objTextBox2 = New-Object System.Windows.Forms.TextBox 
$objTextBox2.Location = New-Object System.Drawing.Size(10,120) 
$objTextBox2.Size = New-Object System.Drawing.Size(260,20) 
$objForm.Controls.Add($objTextBox2)

$objForm.topmost = $true

$result = $objform.ShowDialog()

if ($result -eq [System.Windows.Forms.DialogResult]::OK)
{
$x= $objTextBox.Text
$y= $objTextBox2.Text
}
if ($result -eq [System.Windows.Forms.DialogResult]::Cancel)
{
$wshell = New-Object -ComObject Wscript.Shell
$wshell.Popup("YOU HAVE CANCELLED YOUR INPUT, PLEASE TRY AGAIN AND ENSURE YOU'RE SELECTING OK.",0,"Error")|Out-Null
exit}

#end of custom input form for the public/private key pair

$x|ConvertTo-SecureString -AsPlainText -Force|convertFrom-SecureString > $publickey #exporting and encrypting publickey
$y|ConvertTo-SecureString -AsPlainText -Force|convertFrom-SecureString > $secretkey #exporting and encrypting secretkey
}

$secretkeyplain = Get-Content -path $secretkey #pulling encrypted secretkey

$publickeyplain = Get-Content -path $publickey #pulling encrypted publickey

$PlainTextSecret= [Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR( (ConvertTo-SecureString $secretkeyplain) )) #unencrypting secretkey

$PlainTextPublic= [Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR( (ConvertTo-SecureString $publickeyplain) ))#unencrypting publickey

$string =@{keySecret=$PlainTextSecret;keyAccess=$PlainTextPublic} |convertto-json -compress #creating hash-table to pass public/private key pair to apptio

$header = Invoke-WebRequest -Method Post -Uri 'https://frontdoor.apptio.com/service/apikeylogin' -ContentType "application/json" -Body $string |Select -ExpandProperty headers #retrieving key header for opentoken

$opentoken=@{"apptio-opentoken"=$header."apptio-opentoken"} #must be in a table format for passing credentials must pass in -header parameter in invoke-restmethod (get) and Invoke-WebRequest (curl/post)

#############################################################################################################
#Remaining script are API calls using opentoken from authentication above must pass $opentoken in -header #
#############################################################################################################


#TBMStudio

Thu October 19, 2017 02:36 PM

Thanks Dan, that worked!


#TBMStudio

Thu October 19, 2017 11:58 AM

The following should work when appended:

&showRawNumbers=true&rawNumberPrecision=15


#TBMStudio

Wed October 18, 2017 06:23 PM

Is there a download argument that will pull the decimal places of a value? When exporting to excel I can see the decimal places of the data, but when pulled via API it is being rounded to a whole number. Thanks!


#TBMStudio