Integration Adaptor Release 14.2.00
This Documentation, which includes embedded help systems and electronically distributed materials (hereinafter referred to as the Documentation ), is for your informational purposes only and is subject to change or withdrawal by CA at any time. This Documentation is proprietary information of CA and may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without the prior written consent of CA. If you are a licensed user of the software product(s) addressed in the Documentation, you may print or otherwise make available a reasonable number of copies of the Documentation for internal use by you and your employees in connection with that software, provided that all CA copyright notices and legends are affixed to each reproduced copy. The right to print or otherwise make available copies of the Documentation is limited to the period during which the applicable license for such software remains in full force and effect. Should the license terminate for any reason, it is your responsibility to certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed. TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION AS IS WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE. The use of any software product referenced in the Documentation is governed by the applicable license agreement and such license agreement is not modified in any way by the terms of this notice. The manufacturer of this Documentation is CA. Provided with Restricted Rights. Use, duplication or disclosure by the United States Government is subject to the restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-7014(b)(3), as applicable, or their successors. Copyright 2015 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.
Contact CA Technologies Contact CA Support For your convenience, CA Technologies provides one site where you can access the information that you need for your Home Office, Small Business, and Enterprise CA Technologies products. At http://ca.com/support, you can access the following resources: Online and telephone contact information for technical assistance and customer services Information about user communities and forums Product and documentation downloads CA Support policies and guidelines Other helpful resources appropriate for your product Providing Feedback About Product Documentation If you have comments or questions about CA Technologies product documentation, you can send a message to techpubs@ca.com. To provide feedback about CA Technologies product documentation, complete our short customer survey which is available on the CA Support website at http://ca.com/docs.
Contents Chapter 1: Getting Started 7 Integration Adaptor Overview... 7 Integration Adaptor Prerequisites... 8 Chapter 2: Prepare the Input File 9 What You Can and Cannot Import Using the Integration Adaptor... 9 Primary Resource Attributes... 10 Resource Management Attributes... 12 Resource Contact Attributes... 13 Resource Custom Attributes... 14 Resource OBS Associations... 14 How to Set Up a Delimited File for the Integration Adaptor... 15 Delimiters and Text Quotes for the Integration Adaptor... 17 Extended Characters for the Integration Adaptor... 17 Date Formats for the Integration Adaptor... 18 Chapter 3: Import the File 19 Load the File and Run the Integration Data Loader Job... 19 Verify the Uploaded Data... 21 Contents 5
Chapter 1: Getting Started This section contains the following topics: Integration Adaptor Overview (see page 7) Integration Adaptor Prerequisites (see page 8) Integration Adaptor Overview The Integration Adaptor lets you import resource information using a CA Clarity PPM job. The Integration Adaptor is available automatically after a new installation or upgrade. You can verify that it is available by viewing the list of add-ins. To view the add-in list, open the Administration menu, and from Studio, click Content Add-ins. The following steps outline the process for uploading resource information. 1. Create and format a delimited file. 2. Upload the file to your secure FTP directory. 3. Run the Integration Data Loader job. 4. To verify that your data was updated, view the error messages and logs. Important: You can add new resources and update information for existing resources. Updating existing resource information updates all attributes fields the delimited file contains. Because all fields in the file are updated in CA Clarity PPM, you can overwrite existing information. When you update existing resource information, consider limiting the fields in the file to only those fields you want to update in CA Clarity PPM. Chapter 1: Getting Started 7
Integration Adaptor Prerequisites Integration Adaptor Prerequisites To use the Integration Adaptor, complete the following tasks: Work with CA On Demand Support Services to ensure that you have access to your secure FTP folders. When you can access the secure FTP site, the following folders are available: iad completed error input processing Assign the following access right to the administrator who runs the Integration Data Loader job: Jobs - Access Allows you to access to jobs pages. Type: Global Job - Run - Integration Data Loader Job Allows you to run the Integration Data Loader job. Type: Instance Resource - XOG Access Allows you to import and export resource information using the XML Open Gateway (XOG) interface. The Integration Data Loader job uses the XOG interface which verifies that the user running the job has the appropriate resource access rights. Type: Global 8 Integration Adaptor
Chapter 2: Prepare the Input File This section contains the following topics: What You Can and Cannot Import Using the Integration Adaptor (see page 9) How to Set Up a Delimited File for the Integration Adaptor (see page 15) Delimiters and Text Quotes for the Integration Adaptor (see page 17) Extended Characters for the Integration Adaptor (see page 17) Date Formats for the Integration Adaptor (see page 18) What You Can and Cannot Import Using the Integration Adaptor You can use the Integration Adaptor to import the following resource information for new and existing resources: Primary resource attributes, including user name, resource ID, employment type, and other basic setup information Management information such as availability and primary role Contact information Custom resource attributes OBS information for OBS structures that is available for the resource You cannot import the following resource information: Skills Allocations Document Manager Calendar Custom subobjects defined on the Resource object Multivalued lookups Time-sliced values Attachment data types Chapter 2: Prepare the Input File 9
What You Can and Cannot Import Using the Integration Adaptor Primary Resource Attributes The following attributes that provide primary information about a resource can be imported using the Integration Adaptor: username Resolves to the username as seen on the resource administration page. Data type: String. Size: 32. resourceid Resolves to the Resource ID field. ID: unique_name. Data type: String. Size: 32. employmenttype Resolves to the Person Type field through the lookup SRM_RESOURCE_TYPE. ID: person_type. Values: Employee, Contractor. bookingmanagerusername Resolves to the Booking Manager field through the associated lookup. ID: book_manager_id. Values: A valid, pre-existing user name. resourcetype Resolves to the Resource Type field through the lookup RESOURCE_TYPE. ID: resource_type. Values: Labor, Material, Equipment, Expense. The value defaults to Labor if the field is included but the value is left blank. hiredate Resolves to the Date of Hire field. ID: date_of_hire. Data Type: Date. terminationdate Resolves to the Date of Termination field. ID: date_of_termination. Data Type: Date. 10 Integration Adaptor
What You Can and Cannot Import Using the Integration Adaptor managerusername isactive Resolves to the Manager field through the lookup LOOKUP_SEC_RESMGR. ID: manager_id. Values: A valid, pre-existing user name. Resolves to the Active field. ID: is_active. Data Type: Boolean. Values: true, false. isexternal Resolves to the External field. ID: is_external. Data Type: Boolean. Values: true, false. includeindatamart Resolves to the Include in Datamart field. ID: include_flag. Values: true, false. displayname Resolves to the name fields for nonlabor resources. This field cannot be edited in the user interface for labor resources. ID: full_name. Note: If you are importing nonlabor resources, this field must be included with a value; the import fails otherwise. Data Type: String. Size: 100. emailaddress Resolves to the Email Address field. ID: email. Data Type: String. Size: 255. firstname Resolves to the First Name field. ID: first_name. Data Type: String. Size: 32. Chapter 2: Prepare the Input File 11
What You Can and Cannot Import Using the Integration Adaptor lastname Resolves to the Last Name field. ID: last_name. Data Type: String. Size: 32. Resource Management Attributes The following fields that provide resource management information about a resource can be imported using the Integration Adaptor: openfortimeentry Resolves to the Open for Time Entry field. ID: prisopen. Values: true, false. availability category Resolves to the Availability Rate field. ID: availability. Data Type: Float. Resolves to the Category field. ID: prcategory. Data Type: String. Size: 32. primaryroleid Resolves to the Primary Role field through the lookup PRIMARY_ROLE_HIER_BROWSE. ID: prprimaryroleid. Value: An ID of a pre-existing role. trackmode Resolves to the Track Mode field through the lookup prtrackmode. The value defaults to Clarity if the field is left blank. ID: prtrackmode. Values: Clarity, Other, None. 12 Integration Adaptor
What You Can and Cannot Import Using the Integration Adaptor inputtypecode Resolves to the Input Type Code field through the lookup LOOKUP_INPUT_TYPES. ID: prtypecodeid. Value: A pre-existing ID of a Type Code. userflag1 Resolves to the User Flag 1 field. ID: pruserflag1. Values: true, false. userflag2 Resolves to the User Flag 2 field. ID: pruserflag2. Values: true, false. Resource Contact Attributes The following fields that provide contact information about a resource can be imported using the Integration Adaptor. All of the fields resolve to the contact fields on the Resource record. mobilephone jobtitle state Data Type: String. Size: 20. Data Type: String. Size: 32. Data Type: String. Size: 40. webaddress Data Type: String. Size: 80. workphone pager Data Type: String. Size: 20. Data Type: String. Size: 20. postalcode Data Type: String. Size: 30. Chapter 2: Prepare the Input File 13
What You Can and Cannot Import Using the Integration Adaptor address1 Data Type: String. Size: 80. address2 Data Type: String. Size: 80. address3 Data Type: String. Size: 80. fax Data Type: String. Size: 20. city Data Type: String. Size: 40. country Values: A valid country ID. homephone Data Type: String. Size: 20. Resource Custom Attributes You can import custom attribute information except for multivalued look-ups, time-scaled values, and attachment data types. To import a custom attribute value, add the following prefix to the attribute ID: ~cust_. For example, to import data for the resource object attribute mycustomstring, include ~cust_mycustomstring in the header row for that column. To associate a currency type with a custom money attribute, include the currency attribute in addition to your money attribute. For example, ~cust_mymoney defines the header row for the money attribute, and ~cust_mymoney_currency defines the header row for the currency attribute. To specify a custom partition, include ~cust_partition_code as the header attribute. Resource OBS Associations Organization Breakdown Structure (OBS) associations are supported for any OBS that is available to the resource object. To associate a resource instance to an OBS, add the following prefix to the ID of the target OBS: ~OBSAssoc_. 14 Integration Adaptor
How to Set Up a Delimited File for the Integration Adaptor For example, if your resource OBS has an ID of my_resource_obs, the header row attribute is ~OBSAssoc_my_resource_obs. To create the value for an association, use forward slashes (/) to start and separate the units.the value for the association is the full path of the target unit using the name values of the OBS units. For example: /Top Unit Name/Next Level Unit Name/Target Unit Name. How to Set Up a Delimited File for the Integration Adaptor This topic shows the basic requirements for creating a delimited file for the Integration Adaptor: A Header Row is Required The header row contains the attributes that define the columns for the data being imported. For information about the attributes available for the header row, see the previous section. Important! The attributes that you enter on the header row are case-sensitive. They must be entered exactly as they appear in the preceding sections. For example, to import the resource ID, first name, last name, and email address (Primary Resource attributes), create the header row this way: resourceid firstname lastname emailaddress The following table shows the header row with attributes and a row of data with a value for each attribute. resourceid firstname lastname emailaddress resource0001 Gwendolyn Fitzpatrik fitgw@mycompany.com Required Attributes The following attributes are required for any import and must appear in the header row: resourceid firstname lastname emailaddress Chapter 2: Prepare the Input File 15
A How to Set Up a Delimited File for the Integration Adaptor File Must Be Delimited The file must be in a delimited format. The following examples show the different types of information you can include and the format. The first row in each example is a header row. Example 1: An extra attribute added to the required set To set the availability of the resource, include the availability attribute. resourceid firstname lastname emailaddress availability resource0001 Gwendolyn Fitzpatrik fitgw@mycompany.com 7.2 Example 2: A custom attribute added To add a custom attribute with the ID resourceextension, add the ~cust_ prefix. resourceid firstname lastname emailaddress ~cust_resourceextension resource0001 Gwendolyn Fitzpatrik fitgw@mycompany.com x3022 Example 3: An OBS association added To add an OBS association with the ID res.obs.id, add the ~OBSAssoc_ prefix. resourceid firstname lastname emailaddress ~OBSAssoc_res.obs.id resource0001 Gwendolyn Fitzpatrik fitgw@mycompany.com /IT/Development/Dublin Note: The preceding examples show delimited files as they would appear in Microsoft Excel. However, the files must be stored in delimited format. When viewed with a text editor, a file would look like this example: resourceid,firstname,lastname,emailaddress,~obsassoc_res.obs.it resource0001,gwendolyn,fitzpatrik,fitgw@mycompany.com,/it/development/dublin 16 Integration Adaptor
Delimiters and Text Quotes for the Integration Adaptor Delimiters and Text Quotes for the Integration Adaptor The following delimiters can be used to separate items in the file: Comma Semi-colon Colon Vertical bar or pipe ( ) Space Tab The following example shows a file that is delimited using vertical bars (pipes). resourceid firstname lastname emailaddress ~OBSAssoc_res.obs.id resource0001 Gwendolyn Fitzpatrik fitgw@mycompany.com /IT/Development/Dublin If a field value contains the chosen delimiter, the field can be enclosed in quote symbols to avoid errors. Either double quotes or single quotes can be used. The following comma-delimited example has a custom string attribute named myimpression that has a field value with a comma. Because the delimiter is a comma, having a comma in the field value introduces errors. Double quotes are placed around the field value. The field value is then read as a single value rather than two values that a comma separates. resourceid,firstname,lastname,emailaddress,~cust_myimpression resource0001,gwendolyn,fitzpatrik,fitgw@mycompany.com,"overall, I had a great time" Note: You can add new values to the delimiters and text quotes lookups. For more information about how to manage lookups, see the Administration Guide. The name of the delimiter lookup is Integration Data Loader Delimiters. The name of the text quote symbol lookup is Integration Data Loader Quote Symbols. Extended Characters for the Integration Adaptor If your data has multi-byte data or uses non-ansi characters, ensure that you are using an editor that can interpret these characters and save your file using UTF-8 encoding. For example, note the accent characters in the name fields: resourceid,firstname,lastname,emailaddress resource0003,amérigo,cástor,ameca@mycompany.com Chapter 2: Prepare the Input File 17
Date Formats for the Integration Adaptor If the file is not saved in UTF-8 format, the extended characters do not get saved properly. The result is that the data is imported with incorrect formatting. For example, the first and last names would be imported incorrectly as shown here: resourceid,firstname,lastname,emailaddress resource0003,amã rigo,cã stor,ameca@mycompany.com Date Formats for the Integration Adaptor The following date formats are available for selection from the Date Format field when you run the job. The format determines how the job processes date attributes. yyyy-mm-dd (default) dd-mmm-yyyy dd/mm/yyyy MM-dd-yyyy MM/dd/yyyy If your delimited file has a different date format, you can add a format to the Date Format lookup. The name of the lookup is Integration Data Loader Date Formats. For information about how to manage lookups, see the Administration Guide. Note: Before adding a new date format to the lookup, carefully review the Simple Date Format topic available in the Oracle web site documentation section. The format characters are case-sensitive so you must be exact. For example, M = month, but m = minute. 18 Integration Adaptor
Chapter 3: Import the File This section contains the following topics: Load the File and Run the Integration Data Loader Job (see page 19) Verify the Uploaded Data (see page 21) Load the File and Run the Integration Data Loader Job When the information in the delimited file is complete, you are ready to run the Integration Data Loader job to update resources. Note: Review the Integration Adaptor Prerequisites. You are only able to see and select the job if you have the appropriate access rights. Important! You cannot run this job while the Time Slice job is running. A large import file creates and updates so many records that system performance can be affected. We recommend running the Integration Data Loader job in off hours. Follow these steps: 1. Place the delimited file in your secure FTP iad/input folder. 2. In CA Clarity PPM, open Home, and click Reports and Jobs. 3. Click Jobs. Chapter 3: Import the File 19
Load the File and Run the Integration Data Loader Job 4. In the Job Type column, locate and open the Integration Data Loader job. 5. Complete the required fields in the Parameters section and click Save Parameters. The following fields require explanation: File Name Specifies the name of the delimited file to be imported. Type the file name exactly as it is stored in the input folder, including the file extension. For example: resourcesinput.csv Delimiter Specifies the character to separate data in the file. Text Quote Symbol Specifies the character to escape instances where a delimiter appears in text. Date Format Specifies the date format to be used for date attributes. Resources Represents the object data (resources) that is being imported. The field is selected and read-only. 6. Schedule the job by completing the fields in the When section. 7. Select any groups or individuals that you want notified on job completion or job failure in the Notify section. Note: Any individuals you select require access rights to this job and the secure FTP site. 8. Click Submit. Note: You can monitor the progress of the job by clicking the down arrow on the Jobs tab and clicking Log in the menu that appears. To see information about the number of records that are processed, warnings, and errors, navigate to the job in the list and click the name. 20 Integration Adaptor
Verify the Uploaded Data Verify the Uploaded Data When the Integration Data Loader job completes, review the logs to ensure that your data loaded correctly. The following illustration shows how the input file is stored after processing. H ow the Input File Is S tored in the Folders System Adm inistrator The job starts from the Input folder The file m oves to the Processing folder Com pletes with W arnings Errors Occur The adm inistrator corrects the file and reruns the job The file m oves to the Com pleted folder File m oves to the Error folder Chapter 3: Import the File 21
Verify the Uploaded Data As the job processes, the input file is moved from the Input folder into the Processing folder. When the job finishes, the file is moved to one of the following folders: Error folder If there are errors, the processing was not successful. In this case, the input file is renamed and prefaced with the job name and run ID. The file is copied to the Error folder. The error log is also placed in the Error folder. You can edit the file to correct any problems, place the corrected file back into the Input folder, and rerun the job. Here are some examples of file names in the Error folder: Integration_Data_Loader_5000024_error.log Integration_Data_Loader_5000024_resourcesOOTBNoDates.csv Completed folder If the processing was successful, a completed job log and the input file are stored in the Completed folder. Examine the log file. If there are warnings in the job log, some data can require correction in CA Clarity PPM. A warning can also indicate data that was not imported due to a failure; however, the failure was not enough to stop the import. You can correct any data issues and can rerun the job. Here are some examples of file names in the Completed folder: Integration_Data_Loader_5003730.log Integration_Data_Loader_5003730_resourcesInsert1.csv Note: As a precaution, save and store any files from the Error and Completed folders that you want to keep indefinitely. Data in these folders is retained based on an On Demand schedule for secure FTP folder data. 22 Integration Adaptor