Академический Документы
Профессиональный Документы
Культура Документы
This product is intended for use only as described in this document. UGS cannot be responsible for the proper functioning of undescribed features and parameters.
Manual History
Manual Revision A B C D E F G
Teamcenter Project Version 1.0 2.0 3.0 3.2 4.0 4.1 5.0
Publication Date June 2001 December 2001 September 2002 March 2003 December 2003 May 2004 November 2004
2004 UGS All rights reserved. Produced in the United States of America. 2 Teamcenter Project API Users Guide TP00302 G
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Audience . . . . . . . . . . . . . . . . . . . . . . . . Organization . . . . . . . . . . . . . . . . . . . . . Conventions . . . . . . . . . . . . . . . . . . . . . . Submitting Comments . . . . . . . . . . . . . . . Software Copyright and Trademark Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5 5 5 6 7 7
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 Introduction to the Teamcenter Project API Objects and Operations . . . . . . . . . . . . . Communicating with Teamcenter Project . Operations Available in the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 1-2 1-3 1-4
Using the Java API Client Library to Access the API . . . . . . . . . . . . . . 3-1 Java Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Secure Communications Using SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1 3-3
Using WSDL to Access the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 C# Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Needed Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Secure Communications Using SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 4-7 4-7
Debugging the Client Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1 API Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Third-Party TCP Trace Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1 5-3
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index-1
Figures
1-1. 3-1. 3-2. 4-1. 4-2. 4-3. Communicating between the Client Server . . . . . . . . . . . . . . . . . . . Client Library Java Example . . . . SSL Sample Code . . . . . . . . . . . . Client Library C# Example . . . . . Sample Proxy . . . . . . . . . . . . . . WSDL File . . . . . . . . . . . . . . . . Application and Teamcenter .... ... .... ... .... .. .... ... .... ... .... .. .... ... .... ... .... .. .... ... .... ... .... .. .... ... .... ... .... .. .... ... .... ... .... ..
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
TP00302 G
Contents
Sample Client-Side API Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample Client Log Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample Server Log Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tables
1-1. 1-2. 1-3. 1-4. 1-5. 1-6. 1-7. 1-8. 1-9. 1-10. 2-1. 3-1. Session Service Functions . . . . . . . . . . Workplace Service Functions . . . . . . . . Task Service Functions . . . . . . . . . . . . Member Service Functions . . . . . . . . . . Security Service Functions . . . . . . . . . . Folder Service Functions . . . . . . . . . . . Document Service Functions . . . . . . . . Calendar Service Functions . . . . . . . . . Link Service Functions . . . . . . . . . . . . Outline Service Functions . . . . . . . . . . Standard Input Parameters . . . . . . . . . Choices for a Java API Client Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 1-6 1-8 1-11 1-14 1-15 1-16 1-17 1-18 1-19 2-1 3-1
TP00302 G
Preface
This manual describes the application programming interface for Teamcenter Project version 5.0. Teamcenter Project belongs to the UGS portfolio of digital product lifecycle management software and services.
Audience
This manual contains information for Teamcenter Project developers. It assumes that you are familiar product concepts, XML (Extensible Markup Language), and SOAP (Simple Object Access Protocol). For additional information regarding objects and the operations that can be performed, refer to the Teamcenter Project Users Manual.
Organization
This manual contains the following chapters: Chapter 1 Chapter 2 Chapter 3 Chapter 4 Chapter 5 Introduction contains introductory information about the Teamcenter Project application programming interface (API). Standard Input Parameters lists the standard input parameters common to all Teamcenter Project APIs. Using the Java API Client Library to Access the API describes how to pass XML formatted parameters to Teamcenter Project APIs. Using WSDL to Access the API describes how to use the Teamcenter Project API client library. Debugging the Client Application contains information about debugging the client application.
TP00302 G
Preface
Conventions
This manual uses the conventions described in the following sections.
Monospace font represents text or numbers you enter on a command line, the computers response, the contents of system files, and computer code. Capitalization and spacing are shown exactly as you must enter the characters or as the computer displays the characters.
Italic
Italic font represents text or numbers that vary. The words in italic text describe the entry. The words are shown in lowercase letters, but the varying text may include uppercase letters. When entering text, use the case required by the system. For the preceding example, you might substitute the following for system-password:
KLH3b
text-text
TP00302 G
Preface
Submitting Comments
Portions of Teamcenter software are provided by third-party vendors. Special agreements with these vendors require UGS to handle all problem reports concerning the software they provide. Please submit all comments directly to UGS. Please feel free to give us your opinion of the usability of this manual, to suggest specific improvements, and to report errors. Mail your comments to: UGS Technical Communications 4233 Lexington Avenue N., Suite 3290 Arden Hills, MN 55126-6198 U.S.A. To submit an incident report, you can use the UGS GTAC online support tools at the following URL: http://support.ugs.com
TP00302 G
Chapter
Introduction
Objects and Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Communicating with Teamcenter Project . . . . . . . . . . . . . . . . . . . . . . . . . . Operations Available in the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TP00302 G
Chapter
Introduction
TP00302 G
1-1
Chapter 1
Introduction
You can use the following general categories of operations when manipulating the objects: Query Create Update Delete
You can also manipulate security settings for workplaces, tasks, people, skill sets, folders, documents, and calendars. You could write a program, for example, that uses the API to perform these simple functions: Create a workplace. Create tasks within the workplace. Add members to the workplace. Assign members to the tasks.
1-2
TP00302 G
Introduction
These activities are handled through request messages sent to the server and response messages returned to the external program. Figure 1-1 illustrates this sequence of events.
Figure 1-1. Communicating between the Client Application and Teamcenter Server The Perform Operations step can include as many request/response pairs as necessary to accomplish what is required by the programquerying, object creation and deletion, and object manipulation.
TP00302 G
1-3
Chapter 1
Introduction
The complete list of API functions is shown in the four tables below, grouped by service. The tables describe each function along with the response expected from the server.
1-4
TP00302 G
Introduction
Table 1-1. Session Service Functions Function Name beginApiSession Description Opens an API connection to the server. Closes the API connection. Gets the Java-compatible time zone ID from the server. Expected Response The session ID assigned to this session. true. String containing the time zone ID for the server.
endApiSession getServerTimeZoneID
TP00302 G
1-5
Chapter 1
Introduction
Table 1-2. Workplace Service Functions Function Name addMembership Description Adds an existing member to a workplace. Deletes a schedule baseline. Deletes a workplace. Gets the bill rate for a workplace. Gets the available bill rates for a workplace. Gets cost for a workplace. Gets the fixed cost for a workplace. Gets launcher URL for a workplace. Gets memberships for a workplace. Gets a membership, given its OID. Gets the schedule baseline. Gets the task baselines. Gets a workplace by its OID. Gets a workplace for a given task. Creates a new schedule baseline. Creates one or more new workplaces. Removes a member from a workplace. Queries application for existing memberships. Expected Response The resulting membership.
deleteSchedule Baseline deleteWorkplace getBillRate ForWorkplace getBillRate ForWorkplaces getCostFor Workplace getFixedCost ForWorkplace getLauncherURL ForWorkplace getMembership getMembership byOid getSchedule Baseline getTask Baselines getWorkplaceByOid getWorkplaceForTask newSchedule Baseline newWorkplace
The baseline that was deleted. Success or failure response. The bill rate. Array of bill rates.
Cost bundle. The fixed cost. A string containing a launch URL for the workplace. The memberships in the workplace. The desired membership.
The baseline. The task baselines. The desired workplace. The workplace in which the task is located. The new baseline. The new workplaces.
removeMembership queryMemberships
Success or failure response. Zero or more memberships meet the query specifications.
1-6
TP00302 G
Introduction
Table 1-2. Workplace Service Functions Function Name queryWorkplaces Description Queries application for existing workplaces. Updates the bill rate for a workplace. Updates the fixed cost for a workplace. Updates a schedule baseline. Updates an existing membership. Updates an existing workplace. Expected Response Zero or more workplaces that meet the query specifications.
None.
updateWorkplace
TP00302 G
1-7
Chapter 1
Introduction
Table 1-3. Task Service Functions Function Name assignDependency Description Creates a dependency between two tasks, specifying dependency type and lag time. Makes one task a subtask Assigns a new subtask relationship between two tasks. Assigns a member to a task. Assigns a member to a task. Copies a task along with its subtasks, assignments, and outlines to the same or a different workplace. Deletes an existing task. Deletes an existing task. Expected Response Array of tasks that were affected by new dependency relationship, or else a success/failure response.
assignSubTask assignSubTaskAffected
Success or failure response. Array of tasks that were affected by new subtask relationship. Success or failure response. The task to which the member was assigned. Array of tasks, including the new top-level task plus affected tasks.
deleteTask deleteTaskAffected getCostForTask getFixedCostForTask getHomeTask getLauncherURL ForTask getLinkedTasks getMemberTask Assignments getSubTasks
Success or failure response. Array of tasks that were affected by deleting the task.
Gets cost for a task. Cost bundle. Gets the fixed cost for a task. Gets the home task for a linked task. Gets launcher URL for a task. Gets the linked tasks for a task. Gets an assignment of a task to a member. Queries server for tasks that are subtasks of the specified task. The fixed cost. The home task. A string containing a launch URL for the task. Array of tasks. The task assignment.
Array of subtasks.
1-8
TP00302 G
Introduction
Table 1-3. Task Service Functions Function Name getTaskByOid getTaskDependencies Description Gets a task by its OID. Queries server for tasks that are dependent on the specified task. Gets tasks for a member (person or skill set). Gets tasks for a member. Creates one ore more new tasks and insert them at a point in the workplace. Creates a new assignment between a member and a task. Creates one or more new tasks in a workplace. Creates one or more new tasks in a workplace. Gets the task assignments for a member. Queries application for existing tasks. Queries for OIDs of existing tasks. Recalculates schedule for one or more workplaces. Removes an existing dependency between two tasks. Expected Response The task. Array of task dependencies.
getTasksForMember
getTasksForPerson insertNewTask
newMemberTask Assignment
newTask
newTaskAffected
Array of tasks including the new task plus tasks that were affected by creation of new task. Array of task assignments.
Zero or more tasks that meet the query specifications. One or more strings, each identifying the OID of a task. Array of tasks that were affected. Success or failure response.
removeDependency
TP00302 G
1-9
Chapter 1
Introduction
Table 1-3. Task Service Functions Function Name removeMemberTask Assignment Description Removes an assignment between a member and a task. Removes the subtask relationship between two tasks. Removes the subtask relationship between two tasks. Updates the bill rate for a task. Gets the fixed cost for a task. Updates an assignment between a member and a task. Expected Response The assignment that was removed.
removeSubTask
removeSubTaskAffected
Array of tasks that were affected by removal of subtask relationship. None. The updated task. The updated assignment.
Updates an existing The updated task. task. Updates an existing Array of tasks that were task. affected by updating the task. Approves a timesheet entry Success or failure response.
Deletes a timesheet Success or failure response. entry. Creates one or more new timesheet entries. Updates the fixed cost for a task. The new timesheet entry (or entries). The updated task.
queryTimesheetEntries updateTimesheetEntry
1-10
TP00302 G
Introduction
Table 1-4. Member Service Functions Function Name deleteMember Description Deletes a member (person or skill set). Deletes a person. Deletes a skill set. Deletes a skill set membership. Gets the member who established the API session being used for this function. Expected Response Success or failure response.
Success or failure response. The deleted skill set. The deleted membership.
The member.
getDefaultSkillLevel getMemberByOid
Gets the default The default skill level. skill level. Gets member (person or skill set) by OID. Gets people and/or skill sets based on array of their OIDs. Gets person mapped to a skill set. Queries for the OIDs for people or skill sets within a specified folder. Queries for people or skill sets within a specified folder. Gets people or skill sets assigned to a task. Queries for people within a specified folder. The member.
getMembersbyOid Array
The person.
getMembers
getMembersAssigned ToTask
getPeople
TP00302 G
1-11
Chapter 1
Introduction
Table 1-4. Member Service Functions Function Name getPeopleOids Description Queries for OIDs of people within a specified folder. Gets person by the persons OID. Gets skill levels. Gets a skill set. Gets skill sets mapped a person for a workplace. Gets membership for a skill set. Maps a person to a skill set. Creates one or more new members (people or skill sets). Creates one or more new members. Creates a new skill set membership. Queries for people. Queries for skill set memberships. Expected Response Array of string containing OIDs for people in the specified folder.
getPersonByOid
The person.
Array of skill levels. The skill set. Array of members (skill sets) mapped to the person in a workplace. Array of memberships.
getSkillSetMembership
mapMemberToSkillSet newMember
newPerson
newSkillSetMembership
Array of people who meet the specified query criteria. Array of memberships.
Queries for skill Array of skill sets. sets. Removes the The person that had been mapped. mapping of a person to a skill set. Updates a person or skill set. The updated member.
updateMember
1-12
TP00302 G
Introduction
Table 1-4. Member Service Functions Function Name updatePerson updateSkillSet updateSkillSet Membership Description Updates a person. Updates a skill set. Updates a skill set membership. Expected Response The updated person. The updated skill set. The updated membership.
TP00302 G
1-13
Chapter 1
Introduction
Table 1-5. Security Service Functions Function Name deleteSpecificSecurity Setting Description Deletes the specific security setting for a member for an object. Gets the security setting for the other category of an object. Gets the security setting for the owner of an object. Gets all the security settings for an object. Gets the specific security settings for one or more members for an object. Sets the security setting for the other category for an object. Sets the security setting for the owner for an object. Sets all the security settings for an object. Sets the specific security setting for a member for an object. Expected Response XMLSecuritySetting that was deleted.
getOtherSecurity Setting
getOwnerSecurity Setting
getSecurity
getSpecificSecurity Setting
XMLSecuritySetting(s).
setOtherSecurity Setting
setOwnerSecurity Setting
setSecurity
setSpecificSecurity Setting
1-14
TP00302 G
Introduction
Table 1-6. Folder Service Functions Function Name deleteFolder getFolderByOid Description Deletes a folder. Gets a folder based on its OID. Gets the folder that contains the specified object. Gets one or more folders. Gets one or more folders based on name. Gets the OIDs of the objects contained in specified folder. Expected Response Updated copy of the parent of the deleted folder. The folder.
getFolderForObject
The folder.
getFolders getFoldersByName
Array of folders. Array of folders that match specified name. Array of strings of OIDs of objects in folder.
getObjectOids
getPath
Gets the path of Array of folders which represent path to the folder. folders leading to specified folder. Gets the root folder. Moves an object to another folder. Creates a new folder. Queries for folders. Updates an existing folder. The folder. The folder.
getRootFolder moveToFolder
Array containing new folder plus updated parent folder. Zero or more folders that meet the query specifications. The updated folder.
TP00302 G
1-15
Chapter 1
Introduction
Table 1-7. Document Service Functions Function Name deleteDocument Description Deletes a document (either specified versions or all versions). Downloads a single document version from the server. Gets metadata for documents matching a specified name. Gets launcher URL for a document. Gets the metadata for a document, based on its OID. Gets metadata for documents in a workplace. Uploads a new document. Queries for document metadata. Updates the metadata for a document. Uploads a new version of an existing document. Expected Response None, or an array of document metadata.
downloadDocument
getMetadataBy DocumentName
A string containing the launcher URL for a document. A document object containing the metadata.
Array of metadata.
updateMetadata
uploadDocument
Array of metadata.
1-16
TP00302 G
Introduction
Table 1-8. Calendar Service Functions Function Name deleteCalendar deleteCalendarEvent Description Deletes a calendar. Deletes one event for a calendar. Gets a calendar of any type. Creates a new calendar event. Queries the database for calendars. Creates or replaces a calendar. Updates an existing calendar event. Expected Response The deleted calendar. The updated calendar.
The desired calendar. The new calendar event. Zero or more calendars that meet the query specification. The calendar which has been set.
setCalendar
updateCalendarEvent
TP00302 G
1-17
Chapter 1
Introduction
Table 1-9. Link Service Functions Function Name deleteExternalLink getExternalLinks getIconURI Description Deletes an external link. Gets external links. Gets the icon URI for a type of object. Creates a new external link. Expected Response The deleted link. Array of external links. The icon URI.
newExternalLink
1-18
TP00302 G
Introduction
Table 1-10. Outline Service Functions Function Name deleteTaskNotebook Description Deletes a task notebook. Expected Response The deleted notebook. The deleted entry. The task notebook. Array of entries that were affected.
deleteTaskNotebookEntry Deletes a task notebook entry. getTaskNotebook moveTaskNotebook Entry newTaskNotebookEntry updateTaskNotebook updateTaskNotebook Entry Gets a task notebook. Moves a task notebook entry.
Adds a new task Array of entries that were affected. notebook entry. Updates a task notebook. Updates a task notebook entry. The updated notebook. The updated entry.
TP00302 G
1-19
Chapter
2-1
TP00302 G
Chapter
Each function takes a set of input parameters unique to the function. There are also several input parameters that apply to a wide range function calls. Table 2-1 lists the standard input functions.
TP00302 G
2-1
Chapter
3-1 3-3
TP00302 G
Chapter
If you are developing your client application in Java, you can use the Java client library included in the toolkit. This library, packaged as TCApiClient.jar, contains Java classes that handle the APIs SOAP message, allowing you to concentrate on your projects business logic instead of the details of SOAP. To use TCApiClient.jar, you must include it in your clients CLASSPATH, along with the other JAR files included in the toolkit (axis.jar, xmlParserAPIs.jar, xercesImpl.jar, saaj.jar, jaxrpc.jar, commons-discovery.jar, commons-logging.jar, log4j-[ver. no.].jar, mail.jar, and activation.jar). If you are not using Java, or if you do not wish to use the Java API client library, go to chapter 4, Using WSDL to Access the API, to learn how to access the API.
Java Example
While you are not required to use the Java API client library for a Java client application, there are some advantages over the alternative approach (using WSDL). See table 3-1. Table 3-1. Choices for a Java API Client Application Java API Client Library Java stubs (proxies) are already created. Enhanced support for documents, including reading/writing file on client, compression/decompression, and attachment handling. Libraries for your client application are included in the toolkit (TCPApiClient.jar, axis.jar, xmlParserAPIs.jar, xercesImpl.jar, saaj.jar, jaxrpc.jar, commons-discovery.jar, commons-logging.jar, log4j-[ver. no.].jar, mail.jar, and activation.jar). Includes client logging capability to assist in debugging. WSDL You create Java stubs (proxies) from WSDL files, using the tool of your choice. Standard support for documents.
You include soap libraries from the tool of your choice (they must be compatible with Teamcenter Projects SOAP).
TP00302 G
3-1
Chapter 3
Figure 3-1 illustrates a Java client program that: Establishes an API session. Gets a task based on its OID. Ends the API session.
import COM.inovie.teamCenter.api.client.*; import COM.inovie.teamCenter.api.xml.*; ApiConnection conn = null; try { // Create a new connection object. conn = new ApiConnection(); // Open the connection to the server. conn.open("http://127.0.0.1:8000/ApiService", "user", "pass"); // Get the task service. TaskService taskSvc = conn.getTaskService(); // Get a task. XMLTask task = taskSvc.getTaskByOid("123456789"); // Set the status to "complete". task.setStatus(XMLTask.STATUS_COMPLETE); // Update the task on the server. taskSvc.updateTask(task); // Note that the connection is closed in the "finally" block. } catch (ApiException aex) { // do something } catch (Exception ex) { // do something else } finally { // Close the connection to the server. if (conn != null) { conn.close(); }
Figure 3-1. Client Library Java Example Consult the Javadocs included in the toolkit for complete information about the use of the Java API client library. Examples for each API method are included in the Javadocs.
3-2
TP00302 G
4. 5. 6. 7.
Follow the directions provided with your web server on enabling SSL. Figure 3-2 illustrates sample code for SSL communications using JSSE through the client library.
TP00302 G
3-3
Chapter 3
import COM.inovie.teamCenter.api.client.*; import COM.inovie.teamCenter.api.xml.*; ... public static void main(String args[]) { // This example assumes the use of the JSSE (Java Secure Socket Extension) // reference implementation. SSL usage from different vendors will // vary from this example. // Specify the location of where to find key material for the default // TrustManager (this overrides jssecacerts and cacerts). // This line is necessary only if you are generating your own certificates. System.setProperty("javax.net.ssl.trustStore","D:\\myKeystore\\ clientKeystore"); // Use Suns jsse reference implementation of a URL handler for the "https" URL protocol type System.setProperty("java.protocol.handler.pkgs", "com.sun.net.ssl.internal .www.protocol"); // Dynamically register suns jsse ssl provider Security.addProvider(new com.sun.net.ssl.internal.ssl.Provider()); // Create a new connection object ApiConnection conn = new ApiConnection(); try { // Upon success opening a connection return a new sessionID String sessionID = conn.open("https://146.122.102.129:8443/ ApiService", API_LOGIN, API_PWD); // If we didnt get a sessionID back then the call failed if(sessionID.equals("")) { System.err.println("Unable to create a new session..."); // do some error handling } // Get the task service TaskService taskSvc = conn.getTaskService(); // Query for our task XMLTask task = taskSvc.getTaskByOid("1001085938985"); // (The connection will be closed in the finally block) } catch (ApiException aex) { // do some error handling } catch(Exception e) { // do some error handling } finally { // Close the connection if (conn != null) { conn.close(); } } }
3-4
TP00302 G
Chapter
TP00302 G
Chapter
If you are using a language other than Java for your client application that accesses the API, or if you prefer to generate your own Java stubs (proxies), read this section. If you are using Java and want to use the provided Java API client library, refer to chapter 3, Using the Java API Client Library to Access the API. The API toolkit includes WSDL (Web Services Definition Language) files for the services available through the API. The WSDL files include all the information you need to call the methods in the API from your client program. Generally, you can generate proxy programs from these WSDL files that you can use with your client program. The proxies help take care of the SOAP messaging for you so that you can concentrate on your projects business logic. You should determine the utilities you need to generate the proper proxies for your development environment. Microsoft, for instance, provides a utility called wsdl which generates C# or Visual Basic proxies from the WSDL files for the .NET environment. Other Java tools such as Apaches WSDL2Java create Java client files from WSDL. When you generate proxies from the WSDL, remember that the WSDL files contain default addresses for the port binding (such as http://localhost:8000/ApiService). You need to make sure your client program uses the proper IP address, port, etc. for your Teamcenter Project server installation instead of localhost:8000. With the proxies, you can write your client program to deal with the API as if it were calling local methods. Clients using WSDL to access the API must track the Session ID themselves. You must pass the Session ID as the first parameter for every function call except for beginApiSession(). So to call getTaskByOid() from a client not using the library, you would supply two arguments:
argument 1: string Session ID (the value was obtained previously as the value returned in the call to beginApiSession()) argument 2: string taskOid (the OID for the desired task)
Notice how this is done in the following C# example. The Java API Client library works differently. With the Java API Client library, to get a task by its OID, you call the appropriate method in the TaskService class. You do not need to pass the Session ID as a parameter, since the library tracks it for you:
public XMLTask getTaskByOid(String taskOid) throws ApiException;
For details on all functions, their parameters, and their returns, refer to the WSDL files and to the Javadocs. The Javadocs provide a detailed description of each function (method), plus sample source code. Remember that the sessionID is not provided for you if you are not using the Java API Client Library.
TP00302 G
4-1
Chapter 4
C# Example
Figure 4-1 illustrates a C# client program that: Establishes an API session. Gets a task based on its OID. Ends the API session.
// Allow easy reference to classes in the System namespace using System; // This "class" exists only to house the applications entry-point function class MainApp { // Static method called "Main" is applications entry point function public static void Main() { try { // Begin an API session. TCSessionService tcSessionService = new TCSessionService(); string sessionID = tcSessionService.beginApiSession("login", "password", "5.0"); // Get task and update status. TCTaskService tcTaskService = new TCTaskService(); XMLTask task = tcTaskService.getTaskByOid(sessionID, "123456789"); task.status = "Complete"; tcTaskService.updateTask(sessionID, task.tcOid, task.version, task); // End session. tcSessionService.endApiSession(sessionID); } catch (Exception ex) { // Do something } } }
Figure 4-1. Client Library C# Example Figure 4-2 shows a sample proxy for Session Services that is generated by Microsofts wsdl utility (this proxy is not included in the toolkityou must generate your own).
4-2
TP00302 G
// // This source code was auto-generated by wsdl, Version=1.0.3705.0. // using System.Diagnostics; using System.Xml.Serialization; using System; using System.Web.Services.Protocols; using System.ComponentModel; using System.Web.Services;
/// <remarks/> [System.Diagnostics.DebuggerStepThroughAttribute()] [System.ComponentModel.DesignerCategoryAttribute("code")] [System.Web.Services.WebServiceBindingAttribute(Name="TCPSessionServiceSoapBinding", Namespace="urn:TCPSessionServices")] public class TCPSessionService : System.Web.Services.Protocols.SoapHttpClientProtocol { /// <remarks/> public TCPSessionService() { this.Url = "http://localhost:8000/ApiService"; } /// <remarks/> [System.Web.Services.Protocols.SoapRpcMethodAttribute("", RequestNamespace= "urn:TCPSessionServices", ResponseNamespace="urn:TCPSessionServices")] [return: System.Xml.Serialization.SoapElementAttribute("return")] public string beginApiSession(string login, string password, string version) { object[] results = this.Invoke("beginApiSession", new object[] { login, password, version}); return ((string)(results[0])); } /// <remarks/> public System.IAsyncResult BeginbeginApiSession(string login, string password, string version, System.AsyncCallback callback, object asyncState) { return this.BeginInvoke("beginApiSession", new object[] { login, password, version}, callback, asyncState); } /// <remarks/> public string EndbeginApiSession(System.IAsyncResult asyncResult) { object[] results = this.EndInvoke(asyncResult); return ((string)(results[0])); }
(Continued)
TP00302 G
4-3
Chapter 4
/// <remarks/> [System.Web.Services.Protocols.SoapRpcMethodAttribute("", RequestNamespace="urn:TCPSessionServices", ResponseNamespace="urn: TCPSessionServices")] [return: System.Xml.Serialization.SoapElementAttribute("return")] public bool endApiSession(string sessionID) { object[] results = this.Invoke("endApiSession", new object[] { sessionID}); return ((bool)(results[0])); } /// <remarks/> public System.IAsyncResult BeginendApiSession(string sessionID, System.AsyncCallback callback, object asyncState) { return this.BeginInvoke("endApiSession", new object[] { sessionID}, callback, asyncState); } /// <remarks/> public bool EndendApiSession(System.IAsyncResult asyncResult) { object[] results = this.EndInvoke(asyncResult); return ((bool)(results[0])); } }
Figure 4-2. Sample Proxy The sample proxy was created from the WSDL file shown in figure 4-3. This file is one of the WSDL files included in the toolkit.
<?xml version="1.0" encoding="UTF-8"?> <wsdl:definitions targetNamespace="urn:TCPSessionServices" xmlns="http:// schemas.xmlsoap.org/wsdl/" xmlns:apachesoap="http://xml.apache.org/xml-soap" xmlns:impl="urn:TCPSessionServices-impl" xmlns:intf="urn:TCPSessionServices" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns1="urn: TCPApiServices" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:wsdlsoap= "http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <wsdl:types> <schema targetNamespace="urn:TCPApiServices" xmlns="http://www.w3.org/2001/XMLSchema"> <import namespace="http://schemas.xmlsoap.org/soap/encoding/"/> <complexType name="ApiException"> <sequence> <element name="faultString" nillable="true" type="soapenc:string"/> <element name="serviceName" nillable="true" type="soapenc:string"/> <element name="methodName" nillable="true" type="soapenc:string"/> <element name="errorCode" type="xsd:int"/> <element name="detailedDescription" nillable="true" type="soapenc:string"/> <element name="stackTrace" nillable="true" type="soapenc:string"/> <element name="exceptionFaultCode" nillable="true" type="soapenc:string"/> </sequence> </complexType> <element name="ApiException" nillable="true" type="tns1:ApiException"/> </schema> </wsdl:types>
(Continued)
4-4
TP00302 G
<wsdl:message name="endApiSessionResponse"> <wsdl:part name="return" type="xsd:boolean"/> </wsdl:message> <wsdl:message name="endApiSessionRequest"> <wsdl:part name="sessionID" type="soapenc:string"/> </wsdl:message> <wsdl:message name="beginApiSessionRequest"> <wsdl:part name="login" type="soapenc:string"/> <wsdl:part name="password" type="soapenc:string"/> <wsdl:part name="version" type="soapenc:string"/> </wsdl:message> <wsdl:message name="ApiException"> <wsdl:part name="fault" type="tns1:ApiException"/> </wsdl:message> <wsdl:message name="beginApiSessionResponse"> <wsdl:part name="return" type="soapenc:string"/> </wsdl:message> <wsdl:portType name="TCPSession"> <wsdl:operation name="beginApiSession" parameterOrder="login password version"> <wsdl:input message="intf:beginApiSessionRequest" name= "beginApiSessionRequest"/> <wsdl:output message="intf:beginApiSessionResponse" name= "beginApiSessionResponse"/> <wsdl:fault message="intf:ApiException" name="ApiException"/> </wsdl:operation> <wsdl:operation name="endApiSession" parameterOrder="sessionID"> <wsdl:input message="intf:endApiSessionRequest" name="endApiSessionRequest"/> <wsdl:output message="intf:endApiSessionResponse" name= "endApiSessionResponse"/>
(Continued)
TP00302 G
4-5
Chapter 4
<wsdl:fault message="intf:ApiException" name="ApiException"/> </wsdl:operation> </wsdl:portType> <wsdl:binding name="TCPSessionServiceSoapBinding" type="intf:TCPSession"> <wsdlsoap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/> <wsdl:operation name="beginApiSession"> <wsdlsoap:operation soapAction=""/> <wsdl:input name="beginApiSessionRequest"> <wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap /encoding/" namespace="urn:TCPSessionServices" use="encoded"/> </wsdl:input> <wsdl:output name="beginApiSessionResponse"> <wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap /encoding/" namespace="urn:TCPSessionServices" use="encoded"/> </wsdl:output> </wsdl:operation> <wsdl:operation name="endApiSession"> <wsdlsoap:operation soapAction=""/> <wsdl:input name="endApiSessionRequest"> <wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap /encoding/" namespace="urn:TCPSessionServices" use="encoded"/> </wsdl:input> <wsdl:output name="endApiSessionResponse"> <wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap /encoding/" namespace="urn:TCPSessionServices" use="encoded"/> </wsdl:output> </wsdl:operation> </wsdl:binding> <wsdl:service name="TCPSessionService"> <wsdl:port binding="intf:TCPSessionServiceSoapBinding" name="TCPSessionService"> <wsdlsoap:address location="http://localhost:8000/ApiService"/> </wsdl:port> </wsdl:service> </wsdl:definitions>
4-6
TP00302 G
Needed Constants
The WSDL files specify the syntax for the API services you use, but they do not specify the values of certain parameters you need in your calls to the API. Examples of some of the parameters are status values for tasks and workplaces and task dependency types. Consult the Javadocs for descriptions and literals for all constants used by the API.
TP00302 G
4-7
Chapter
API Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Server-Side API Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client-Side API Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Third-Party TCP Trace Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TP00302 G
Chapter
When you debug your client API application, you might find it useful to use the API log feature or other third-party tools. These aids are described in this chapter.
API Logging
The API can log events for both the client and the server. Separate log files can be kept on the server and on your client. When you enable logging, the API automatically logs events. You can also add your own messages on the client side. For the client, the API log is available through the Java client. For the server, you can enable the API log regardless of the client you are using.
4.
5.
TP00302 G
5-1
Chapter 5
Figure 5-1. Sample Client-Side API Logging After executing the code, the log contains entries like those shown in figure 5-2.
[Fri Apr 16 10:32:50 PDT 2004] ApiLog, began logging at Info, version 4.1.0 [Fri Apr 16 10:32:50 PDT 2004] ApiConnection.beginApiSession, strTargetURL=http://127.0.0.1:8000/ApiService, loginName=admin [Fri Apr 16 10:32:50 PDT 2004] sessionID=7327859395074513 ApiConnection.beginApiSession , , returning 7327859395074513 [Fri Apr 16 10:32:50 PDT 2004] sessionID=9871104512919878 WorkplaceService. queryWorkplaces, queryData= WHERE tcname= Test Workplace [Fri Apr 16 10:32:52 PDT 2004] sessionID=9871104512919878 WorkplaceService. queryWorkplaces, returning [0]=[tcOid=1076424576676, startDate=Tue Mar 09 04:00:00 PST 2004, deadline=Mon Mar 22 04:00:00 PST 2004, workplaceName=Test Workplace, description=, version=8, priority=Medium, status=Not Started, customerName=, customerNumber=, published=true, datesLinked=false, percentLinked=false, template=false, billcode1= <unassigned>, billcode2=<unassigned>, billcode3=<unassigned>, teamWebUrl=, customField1=, customField2=, customField3=, customField4=, customField5=, customField6=, customField7=, customField8=, customField9=, customField10=] [Fri Apr 16 10:32:52 PDT 2004] ApiLog, ended logging
5-2
TP00302 G
If you had logging enabled on the server at the same time, you see entries in the log file on the server like those shown in figure 5-3.
4/16/2004 10:33:09 (Actual Time - 4/16/2004 10:32:50) DefaultApiSessionHandler:: beginApiSession: none login=admin, locale=null, version=4.1.0 4/16/2004 10:33:09 (Actual Time - 4/16/2004 10:32:50) DefaultApiSessionHandler:: beginApiSession: none activeSessionCount on entry=1 4/16/2004 10:33:09 (Actual Time - 4/16/2004 10:32:50) DefaultApiSessionHandler:: beginApiSession: 7327859395074513 returning 7327859395074513 4/16/2004 10:33:09 (Actual Time - 4/16/2004 10:32:50) DefaultApiSessionHandler:: beginApiSession: 7327859395074513 remote address=127.0.0.1 4/16/2004 10:33:09 (Actual Time - 4/16/2004 10:32:51) DefaultApiWorkplaceHandler:: queryWorkplaces: 9871104512919878 queryData= WHERE tcname= Test Workplace 4/16/2004 10:33:09 (Actual Time - 4/16/2004 10:32:52) DefaultApiWorkplaceHandler:: queryWorkplaces: 9871104512919878 returning [0]=[tcOid=1076424576676, startDate= Tue Mar 09 04:00:00 PST 2004, deadline=Mon Mar 22 04:00:00 PST 2004, workplaceName=Test Workplace, description=, version=8, priority=Medium, status=Not Started, customerName=, customerNumber=, published=true, datesLinked=false, percentLinked=false, template=false, billcode1=<unassigned>, billcode2=<unassigned>, billcode3=<unassigned>, teamWebUrl=, customField1=, customField2=, customField3=, customField4=, customField5=, customField6=, customField7=, customField8=, customField9=, customField10=] 4/16/2004 10:33:09 (Actual Time - 4/16/2004 10:32:52) DefaultApiSessionHandler:: endApiSession: 7327859395074513 4/16/2004 10:33:09 (Actual Time - 4/16/2004 10:32:52) DefaultApiSessionHandler:: endApiSession: 7327859395074513 activeSessionCount on entry=2 4/16/2004 10:33:09 (Actual Time - 4/16/2004 10:32:52) DefaultApiSessionHandler:: endApiSession: 7327859395074513 remote address=127.0.0.1
Figure 5-3. Sample Server Log Entries By inspecting the log files and matching up events on the client and the server, you can diagnose the source of a problem. Remember, timestamps are local to the client and server machines, so they may not match perfectly.
TP00302 G
5-3
Index
A API logging Client-side logging . . . . . . . Description . . . . . . . . . . . . JDOT Server Administration Server-side logging . . . . . . B beginLogging method . . . . . . . . . . . . . . . . 5-2 C Client library, C# example . . . . Client-side API logging . . . . . . Code conventions . . . . . . . . . . Command line entry conventions Conventions Code . . . . . . . . . . . . . . . . . Command line entries . . . . . File contents . . . . . . . . . . . . Names . . . . . . . . . . . . . . . . Values . . . . . . . . . . . . . . . . D Debugging client applications . . . . . . . . . . . 5-1 E endLogging method F File contents conventions . . . . . . . . . . . . . . . J Java API client library . . . . . . . . . . . . . . . 3-1 Java example . . . . . . . . . . . . . . . . . . . . . . 3-1 L logMessage method . . . . . . . . . . . . . . . . . . 5-2 6 . . . . . . . . . . . . . . . . . 5-2 ... . ... . ... . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 5-2 . 6 . 6 . . . . . 6 6 6 6 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2 5-1 5-1 5-1
M Methods beginLogging . . . . . . . . . . . . . . . . . . . . 5-2 endLogging . . . . . . . . . . . . . . . . . . . . . 5-2 logMessage . . . . . . . . . . . . . . . . . . . . . . 5-2 N Name conventions . . . . . . . . . . . . . . . . . . . O Objects, performing operations on . . . . . . . . 1-2 S Secure Communications using SSL . . . . 3-3, 4-7 Server-side API logging . . . . . . . . . . . . . . . 5-1 Standard input parameters . . . . . . . . . . . . 2-1 T Teamcenter Project Communicating with . . . Teamcenter Project API Introduction . . . . . . . . . Operations available in . Third-party TCP trace tools U Using SSL . . . . . . . . . . . . . . . . . . . . . 3-3, 4-7 V Value conventions . . . . . . . . . . . . . . . . . . . . W Web Services Definition Language Needed constants . . . . . . . . . . . . . . . . . 4-7 Using . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 wsdl utility . . . . . . . . . . . . . . . . . . . . 4-14-2 6 . . . . . . . . . . . . 1-3 . . . . . . . . . . . . 1-1 . . . . . . . . . . . . 1-4 . . . . . . . . . . . . 5-3 6
TP00302 G
Index-1