Datalink (Classic) CA PPM (Clarity) Connector Guide
Applies to: Datalink (Classic) 4.0 and later
Requires CA PPM 15.1 and later. Using Basic Authentication (Federated SSO is not supported).
NOTE : The connector uses the REST API that was introduced along with the Modern UX in CA PPM 15.1. This API is still evolving and not officially supported by CA. Apptio provides best-effort support for this connector but cannot assure ongoing compatibility with all CA PPM environments.
The CA PPM (Project and Portfolio Management, formerly known as "Clarity") Connector can import data served through the CA PPM REST API into your Apptio instance.
Three types of CA PPM data available through the REST API align with the components and Apptio Master Datasets. The following relationships exist between the CA PPM objects and Apptio master datasets:
| CA PPM Object | Apptio Master Data set |
|---|---|
| Projects | Projects Master Data |
| Resources | Labor Master Data |
| Timesheets | Time Tracking Master Data |
CA PPM provides support for user-defined processes, which can be configured to query for data and write the results out to a file on a schedule. The CA PPM SaaS version includes an SFTP server which can be used as the target of the file. In this case, the Datalink (Classic) SFTP Connector (see Configure the SFTP Server Connector ) can be configured to retrieve the file. When CA PPM is on-premises, the location must be accessible from the CA PPM instance and is likely behind a firewall. In this case the Datalink (Classic) on-premises agent with a file system (see Configure the File System Connector ) or the Windows Share Connector (see Configure the Windows Share Connector ) may provide a better solution.
Configure the connector
NOTE : This connector brings in all fields available for a certain object.
- Open the Datalink (Classic) Agent, then click New Connector.
- Click the CA PPM Connector .
- Enter a Connector Name .
TIP : For clarity, consider naming your connector with a description of the function of the connector. For example, use CA PPM Projects rather than CA PPM 1. - 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 secured URL for your CA PPM instance.
-
Requires Authentication - Select this check box if your CA PPM instance requires
authentication, then select Basic Auth as the Authentication Type :
- Username - Enter the CCA PPM user name.
- Password - Enter the password associated with Username.
- Time Period - Select the time period to load. Select the current or previous month based on the date the load takes place.
- JSON Passthrough - Select this check box to use JSON passthrough instead of XML conversion. When this option is selected, JSON data is uploaded to Apptio as-is instead of first being converted to XML. This option requires the Apptio instance to be version 12.2.4 or later.
Select the properties
Select from the following CA PPM queries to use:
- Projects
- Resources
- Time Sheets
- Enter Custom CA PPM Object - If you select this option, it must match the specifications outlined in the REST API documentation for your instance. To find your REST API documentation, go to the Administration Tab in your instance, then in the General Settings column, select System Options . Scroll down to the API section and navigate to the URL that appears to the right of AP Documentation URL .
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.
- Select your email preferences:
- Send an email notification when this connector succeeds .
- Send an email notification when this connector fails .
- 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
- From within the connector, click Schedule on the left menu to jump to these settings.
- Select Enable Schedule .
- 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.
Master dataset mappings
Mappings in this topic are based on a standard CA PPM system. Therefore, if any fields were changed, added, or deleted, the CA PPM field required for mapping may be different. Also, you may have created additional values in your CA PPM system that can be mapped to Apptio Master Dataset fields. If this is true, map these values to the appropriate fields.
| Projects Master Data Field | Projects Master Data Field Description | CA PPM Object | CA PPM Field | Comments |
|---|---|---|---|---|
| Expense Type | Designation for costs that are either Operating Expenses or Capital Expenditures. Valid values: OpEx or CapEx. | Projects | costType displayValue (see comments) |
Mapping is required to correctly classify Expense Types. |
| Project ID | The project code or identifier as defined by the project portfolio management and other systems. | Projects | _internalID | |
| Project name | A unique name for the project. | Projects | name | |
| Spend Type | The investment categorization of the IT expenditure or budget. Valid values are typically either Run/Change the Business (RTB, CTB)or Run/Grow/Transform the Business (RTB, GTB, TTB). | Projects | displayValue | Depending on CA PPM configuration, it may be mapped from displayValue |
| Status - Overall | Overall status of the project budget expressed as Apptio required values: Red, Yellow or Green. |
Projects | progress displayValue | |
| Approved Budget | The amount of capital and operating expenditure approved for a specific project. This number reflects the latest total approved project budget for the year and may differ from the original / baseline project budget. | Projects | budgetCostTotal amount | |
| Baseline End Date | Date the original approved project was scheduled to be complete. | Projects | scheduleFinish | |
| Due Date | The updated, approved date by which the project is to be completed. | Projects | agilePlannedEndDate | |
| Priority | The priority or importance of a project. Example values include: Pri 1, Pri 2, Pri 3, Pri 4. | Projects | priority (see comments) =If(priority<12,"P3",If(priority <24,"P2","P1")) |
A series of IF statements is required. The range for priority in CA PPM is from 0-36. Green: 0-11 Yellow: 12-23 Red: 24-36 |
| Baseline Start Date | Date the original approved project was scheduled to start. | Projects | scheduleStart | |
| Project Description | A description of the project. | Projects | description | |
| Project Manager | The primary project manager responsible for the planning and execution of the project from a project management disciple perspective. | Projects | Manager displayValue | |
|
Project Type |
A more specific method for categorizing the project for analytical or other reporting purposes. Examples include: Infrastructure, New App/Service, Enhancement, Break/Fix, Migration, Retirement. |
Projects |
displayValue |
Table relationships
Labor Master Data
| Labor Master Data Field | Labor Master Data Field Description | CA PPM Object | CA PPM Field | Comments |
|---|---|---|---|---|
| Employee Type | The type of the labor resource. Apptio -Required values include: Internal Personnel, External Personnel |
Resources | employmentType displayValue | Mapping is required to correctly classify employee types. |
| Labor ID | A user-defined unique identifier for the Labor dataset. | Resources | uniqueName | |
| Labor Name | The name of the labor resource, such as John Smith. | Resources | fullName | |
| Position | The name of the employee's job position. For example: Helpdesk, support, desktop administrator, storage administrator. |
Resources | primaryRole displayValue | |
| Unique Identifier | A unique identifier or generated concatenation of columns to establish the desired granularity of cost source data for allocations and reporting. | Resources | _internalId |
Table relationships
Time Tracking Master Data
| Time Tracking Master Data Field | Time Tracking Master Data Field Description | CA PPM Object | CA PPM Field | Comments |
|---|---|---|---|---|
| Employee Name | The name of the labor resource, such as John Smith. | Timesheets | resourceName | |
| Actual Hours | The number of hours reported to a specific task or activity for the resource or role. | Timesheets | actualsTotal | |
| Employee Type | The type of the labor resource. Valid values: Internal Personnel, External Personnel. | Resources | employmentType displayValue | A lookup against Resources is required to bring this field into the Time Tracking Master
Data Set. Mapping is required to correctly classify employee types. |
| Labor ID | A user-defined unique identifier for the Labor dataset. | Timesheets | resourceId | |
| Position | The name of the employee’s job position. For example: Helpdesk, support, desktop administrator, storage administrator. | Timesheets | A lookup against Resources is required to bring this field into the Time Tracking Master Data set. | |
| Role Type | An aggregated view of roles. Apptio Recommended Values: Project Mgmt (PM), Architect (Arch), Developer (Dev), Quality Assurance (Test), Business Analyst (BA), Security (Sec), Infrastructure (Infra). |
Resources | primaryRole displayValue | A lookup against Resources is required to bring this field into the Time Tracking Master Data set. |
Table relationships for time tracking master data
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.
- Open the Datalink (Classic) Agent, click Actions next to the connector, then click View Execution History .
- 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 .