agile engineering collaboration platform · 2007-09-25 · agile plm 9 1-2 engineering...

Make sure you check for updates to this manual at the Agile Documentation Website

Agile Engineering Collaboration PlatformRelease 1.2 for Agile 9

Part No. TP1455-9.0B

Agile PLM 9

ii Engineering Collaboration Guide

Copyrights and TrademarksCopyright © 1995-2006 Agile Software Corporation. All rights reserved.

You shall not create any derivative works of this publication nor shall any part of this publication be copied, reproduced, distributed, published, licensed, sold, stored in a retrieval system or transmitted in any form or by any means: electronic, mechanical, photocopying, or otherwise, without the prior written consent of Agile Software Corporation, 6373 San Ignacio Avenue, San Jose, California 95119-1200 U.S.A.; Telephone 408.284.4000, Facsimile 408.284.4002, or <http://www.agile.com/>.

The material in this document is for information only and is subject to change without notice. While reasonable efforts have been made in the preparation of this document to ensure its accuracy, Agile Software Corporation assumes no liability resulting from errors or omissions in this document or from the use of the information contained herein. Agile Software Corporation reserves the right to make changes in the product design without reservation and without notification to its users.

Agile Software is a registered trademark and Agile, Agile Product Collaboration, Agile Product Cost Management, Agile Product Service & Improvement, Agile Program Execution, Agile Product Interchange, AgileMD, and the Agile Logo are trademarks of Agile Software Corporation in the U.S. and/or other countries. Guaranteed Business Results is a service mark of Agile Software Corporation. All other brands or product names are trademarks or registered trademarks of their respective holders.

Java and Solaris are registered trademarks of Sun Corporation.

Microsoft, Microsoft Windows, Microsoft Word, Microsoft Excel, Internet Explorer and SQL Server are registered trademarks of Microsoft Corporation.

Oracle and Oracle8i are registered trademarks of Oracle Corporation.

NOTICE OF RESTRICTED RIGHTS:The Software is a “commercial item,” as that term is defined at 48 C.F.R. 2.101 (OCT 1995), consisting of “commercial computer software” and “commercial computer software documentation” as such terms are used in 48 C.F.R. 12.212 (SEPT 1995) and when provided to the U. S. Government, is provided (a) for acquisition by or on behalf of civilian agencies, consistent with the policy set forth in 48 C.F.R. 12.212; or (b) for acquisition by or on behalf of units of the Department of Defense, consistent with the policies set forth in 48 C.F.R. 227.7202-1 (JUN 1995) and 227.7202-4 (JUN 1995).

October 11, 2006

REVISIONS

Revision Date Pages Affected Description

A 08/24/2006 All New release of manual for Agile EC 1.2

B 10/11/2006 2-21 - 2-23 Update of Agile PLM configuration sub-classes

iii

CHAPTER 1Introduction to Engineering

CollaborationThis introduces you to Agile’s CAD Integration product, called Engineering Collaboration. It contains the following topics:❑ Functional Overview

❑ Characteristics and Capabilities

❑ Engineering Collaboration Process

Functional OverviewAgile Engineering Collaboration (EC) is an application that provides data and process integration between CAD applications and Agile PLM 9. It allows CAD designers and engineers to capture and control the data representing a primary source of the product record. The application consists of a core Engineering Collaboration Client (known as the “EC Client” or formerly as the “CAX Client”), and individual Engineering Collaboration Connectors to the specific CAD systems (such as Pro/ENGINEER, SolidWorks, etc.). The EC Client provides a window into the Agile environment that is geared towards CAD designers and engineers. It supports searching and viewing of Agile data, and provides the user interface for all Connector operations such as saving and loading CAD data. The main features of the EC Connectors are:

❑ Save – Saves native CAD data from the current session into Agile

❑ Load – Loads native CAD data from Agile into the current CAD session

❑ Manage Change – Allows users to control checkout reservation and revisioning

❑ Update Properties – Updates property (attribute) values between the CAD files and Agile

❑ Create Viewables – Creates neutral format files, such as PDF, to be used for viewing, plotting, or manufacturing

❑ BOM Publication – Automatically creates and updates the Part BOM based on the CAD design structure, with Agile change control

CAD datasets created by the EC Connectors can be viewed using Agile Enterprise Visualization (EV) allowing anyone with access to Agile PLM to be able to view, markup, and collaborate in real time on the 3D CAD designs across the web, without needing a seat of the CAD tool.

Agile Engineering Collaboration requires Agile Product Collaboration (PC) as a base module, which provides the underlying document management, part management, and change management required to manage CAD designs.

This chapter and Chapter 4, Using the Engineering Collaboration Client, are directed to end-users.

Chapter 2, Installation and Configuration, and Chapter 3, Administration, are directed to administrators and implementers.

1-1

Agile PLM 9

Other Agile PLM DocumentationThis guide is intended to be sufficient to use Engineering Collaboration, provided Agile 9.2.1 is installed at your company. If you need to install Agile 9.0 or upgrade to Release 9.2.1, please contact your Agile representative or use appropriate installation documentation.

❑ Documentation for Agile PLM installation and upgrade:

• Agile 9.2.1 ReadMe, for Windows or Solaris

• Pre-Installation Worksheet

• Database Installation and Upgrade Guide for Oracle

• Installation Guide for Windows or Installation Guide for Solaris

The following manuals provide information about Agile PLM that is not found in this guide.

❑ Documentation for Agile PLM administration:

• Administrator Guide — complete reference to the Administrator component of Java Client

❑ Documentation for Agile PLM end-users:

• Client Handbook — this is a compendium of information about cross-platform features in Agile PLM, as wellas utility applications such as Import, Export, and FileLoad. The following are documented:

• User interfaces of Java Client and Web Client

• Agile PLM concepts and terms

• Agile business objects, particularly file folders for attachments

• Searches to find data in Agile

• Product Collaboration User Guide — this manual is central to implementing the change control process in Agile, with information about items (parts and documents) and changes, such as ECOs.

Characteristics and CapabilitiesThese are some characteristics of Agile Engineering Collaboration:

❑ Multi-platform, Java Client

❑ Centralized configuration via XML

❑ Dynamically loaded extensions support customization of the CAD Connectors’ business logic

❑ Common search and view functionality is simplified for CAD designers and engineers

❑ Manages both work-in-progress (WIP) and released CAD design data

❑ Supports concurrent engineering, enabling multiple designers to work within a common assembly

❑ Data access controlled by checkout reservation and/or timestamp

❑ Automated BOM creation process

❑ Bi-directional metadata exchange

Support for Mechanical CAD ToolsFor a complete and most up-to-date list of all officially supported Agile PLM versions for each EC release, and the supported CAD systems and versions for each EC CAD Connector, see the document “EC System and Version Support” on the Agile Documentation Web site..

1-2 Engineering Collaboration Guide

http://support.agile.com

http://support.agile.com

Chapter 1 Introduction to Engineering Collaboration

Engineering Collaboration ProcessFigure 1-1: The main use cases supported by Agile Engineering Collaboration

Save and Load CAD filesCAD designs are created within the CAD system environment, with files in a working directory (which may be local or network attached). The designer saves into Agile, which creates a Design Structure that mimics the structure of the CAD assembly. The native CAD files are attached to this Design Structure, which is used as the basis for loading and re-saving the CAD designs. Since Agile is a centralized repository, all CAD designers in the enterprise have access to these files, subject to the control of Agile roles and privileges. Individual designers can set checkout reservation in Agile when they load files into their CAD session, enabling concurrent engineering within CAD assemblies. Additional files such as viewables (PDF, HPGL, etc.) can be attached to the Design Structure.

Create BOMWhen a design or design change has been completed, the designer may use the Create Item/BOM command to create or update the Agile Part BOM, representing the true Product Structure. This function is used when there is a high correlation between the Design Structure and Product Structure, to avoid tedious manual entry of the Part BOM. This works in the context of an Agile change object, resulting in automated BOM redlining. The BOM can also be manually updated, for example to add bulk items such as paint or glue. Further automated updates from CAD will not remove the manually added items.

View CAD FilesOne reason for managing the native CAD files within Agile is that the Agile viewer can be used to view and markup the files. This works across the web, and without having the native CAD system. Advanced functionality such as digital mockup, 3D comparison, interference checking, and real-time collaboration make this an important tool to support the overall design process.

1-3

Agile PLM 9

Engineering Collaboration System ArchitectureEngineering Collaboration 1.2 is based on a new high-performance architecture, which becomes apparent mainly during installation and configuration of the Engineering Collaboration Platform.

Figure 1-2:System Architecture

The CAD Connector, the Engineering Collaboration Client and Agile 9 now communicate with each other through the PLM-API, which can be routed via a socket-based communication channel or over HTTP / Web Services. Although this is different from an installation and configuration aspect, usage of the CAD Connector(s) and Engineering Collaboration Client remains the same ! Please see the Administration Manual for further information about customizing the Engineering Collaboration Platform.


CHAPTER 2Installation and Configuration

This presents the installation procedures for the Engineering Collaboration Client and Server components:❑ Prerequisites❑ Installing the EC Client❑ Testing the Installation❑ EC Client Preferences❑ EC Client and Server Configuration Options

PrerequisitesPrior to the installation of the Engineering Collaboration interface on the Agile 9 server, you must verify the following items:

❑ Database is operational and running

❑ Agile (see Introduction for supported versions) has been successfully installed on an accessible server (the prerequesites for Java Runtime Environment are the same as for Agile PLM Server).

Important If you are not working with a member of Agile’s Solutions Delivery Organization, you are strongly encouraged to consult the Agile Installation Worksheet and other documentation of Agile installation procedures. See Other Agile PLM Documentation.

❑ Agile File Management Server is usable and accessible

❑ A test environment is prepared

❑ A CAD systems is installed, and can be launched by the test user from the home directory

❑ Each user must locally install Java Runtime Environment (JRE) version 1.5 or higher. You can test it using the console mode.

JRE 1.5 is available at:

http://java.sun.com/j2se/1.5/download.html

❑ Login name and password of the Agile PLM test user are known in Agile PLM

❑ The test user can launch an Agile 9 session

Having fulfilled these prerequisites, it is time to install the Engineering Collaboration Client with Agile 9.

2-1

http://java.sun.com/j2se/1.4.2/download.html

Agile PLM 9

Installing the EC ClientThe Engineering Collaboration Client must be installed on the Agile PLM Server. Log in with the same user as for the Agile PLM installation.

After loading the ECP installation CD, the installation tool automatically comes up. If not, start the installation with “setup.bat” (“setup.sh” with Unix operating system).

1 Please read and confirm the license agreement and continue with NEXT.

Figure 2-1: License Agreement

2 Select the package you want to install

Figure 2-2: Choose Package

The Engineering Collaboration Platform package includes the Engineering Collaboration Client and the server side components whereas the Agile PLM API package contains the PLM API software documentation and the Agile PLM API for developers. The installation procedure differs according to the selected package.


Chapter 2 Installation and Configuration

Installation of the Engineering Collaboration Platform

Having selected the Engineering Collaboration Platform:

3 Select the server side components

Figure 2-3: Server Side Components

When selecting the EC WebService Proxy the file EcpWsProxy.jar will be stored in the directory

$agile_home\integrations\sdk\extensions. When selecting the EC Client the file ECPClient.ear will be stored in the directory $agile_home\agileDomain\applications.

4 Enter the installation location of the server side components

Figure 2-4: Installation Location of Server Side Components

2-3

Agile PLM 9

5 EC Client Variables

Figure 2-5: EC Client Variables

Having selected the EC Client, the variables for Agile PLM URL and the ECP Kernel Port are checked in the ECPClient.defaults file of the file EcpClient.war.

6 Check the pre-installation summary and continue with NEXT.

Figure 2-6: Pre-Installation Summary Review



The installation progress is indicated by the status bar.

Figure 2-7: Installation Progress

7 Click the DONE button to complete the installation.

Figure 2-8: Completed Installation

Deployment of the EC Client

Agile PLM with OAS

If you use the Oracle Application Server (OAS), the deployment of the EC Client has been done automatically with the installation.

If you want to redeploy or undeploy the EC Client manually you can use the files

$agile_home\agile_domain\bin\ReDeployEcpClient.cmd and $agile_home\agile_domain\bin\UnDeployEcpClient.cmd.

2-5

Agile PLM 9

Agile PLM with BEA Web Logic

If you use the BEA Web Logic Application Server, the deployment of the EC Client must be done manually:

1 Start the WebLogic Administration server by running the startAgile script.

2 Open the Administration console by typing the following in your browser:

http://localhost:<port_number>/console (eg. port_number=7001)

The default user login is “system” and the password is “weblogic”.

3 Click the Deployments -> Applications node

4 Select “Deploy a new Application” and change to the folder “Applications”.

5 Select “EcpClient.ear” and click “Continue”.

6 Check the values and click “Deploy”.

If the deployment was successful, the status of the EC Client will be displayed as “available” in the browser.

Configuring a Proxy Server for EC Client Web Start

If you are using a Web Proxy Server for Agile PLM you must change the configuration files to support the EC Client Web Start by the Proxy Server.

If you have installed and configured IIS as the Web Proxy Server as described in the Agile PLM installation documentation you have to adapt the following files:

For OAS you have to add the following line in the file $agile_home\AgileProxies\9ias.conf:

oproxy.<servername>.urlrule=/EcpClient/*

For BEA WebLogic you have to adapt the following line in $agile_home\AgileProxies\iisproxy.ini:

WlForwardPath=/Agile,/JavaClient,/EcpClient



Installation of the Agile PLM-API and API Documentation

Note It is not required to install the Agile PLM-API and API documentation if you only want to use the Engineering Collaboration Client. You only have to install this package if you want to develop a new integration.

Having selected the PLM-API package:

3 Install the PLM-API and API Documentation

Figure 2-9: PLM-API

Having selected the Agile PLM API Java component, the following files will be stored in the directory indicated in Figure 2-10: plm-api-java-1.0.0.tar.gz and plm-api-java-doc-1.0.0.tar.gz.

Having selected the Agile PLM API C++ component, the following files will be stored in that directory:

plm-api-cpp-1.0.0.tar.gz and plm-api-cpp-doc-1.0.0.tar.gz.

4 Specify the installation location of PLM-API

Figure 2-10: Installation Location

5 Check the pre-installation summary and continue with NEXT.

2-7

Agile PLM 9

Figure 2-11: Installation Summary Review

The installation progress is indicated by the status bar.

Figure 2-12: Installation Progress

6 Click the DONE button to complete the installation.



Figure 2-13: Complete Installation

Testing the InstallationTo test if the EC Client is installed properly, please enter the following URL into a web browser: http://<host>:<port>/EcpClient/start.html.

Make sure to enter the correct values for <host> and <port>.

Figure 2-14: EC Client Launch Page

If you click the LAUNCH button, the EC Client software is installed on client side with WebStart.

To test if the EC WebService Proxy is installed properly, please enter the following URL into a web browser: http://<host>:<port>/Agile/integration/ws/EcpWebService?wsdl.

You may need to enter a valid Agile PLM user name and password to access this page. If the EC WebService Proxy was installed properly, the following xml file will be displayed:

2-9

Agile PLM 9

Figure 2-15: EC Web Service



EC Client PreferencesClick on the Preferences button in order to modify the preferences settings inside the EC Client.

Figure 2-16: Preferences Button

Figure 2-17: Agile Engineering Collaboration Screen

2-11

Agile PLM 9

General/Miscellaneous

Figure 2-18: Miscellaneous

Parameters:

Proxy server: Not used in the EC client

Encoding: Not used in the EC client

Language: Language setting for the EC client

Use the drag feature: Not used in the EC Client

Use the drop feature: Not used in the EC Client



General/Appearance

Figure 2-19: Appearance

Parameters:

Show ToolTips: Enables/disables the display of tooltips

Text in toolbars: Enables/disables the display of text below toolbar icons

Extended file selector: Use Java's file selector

Scrollable desktop: Enables/disables the display of scrollbars for the desktop

Show window contents when dragging: Shows window contents when dragging

Look & Feel: Selection of the look & feel function for the EC Client

Background picture: Not used in the EC Client

2-13

Agile PLM 9

Log Settings

Figure 2-20: Log Settings

Parameters:

Package or class (0): Name of package or class to log (number active for logging)

Trace (0): Trace log level (number active for trace level)

Debug (0): Debug log level (number active for debug level)

Show log: Enable/disable a terminal window with log messages

Add button: Adds a new package or class for logging

Always log exceptions: Enable/disable logging of exceptions regardless of log settings

Display milliseconds: Enable/disable the display milliseconds in log dates

Load profile: Loads a log setting from an external file



Log Settings/Log4j

Figure 2-21: Log4j

Parameters:

Use Log4j for logging: Enables/disables logging with log4j

Priority: Log level

Log messages in the console window: Enables/disables logging to the console

Log messages in a file: Enables/disables logging to a file

Path and file name: Full path of log file

Number of backups: Number of backup before rotation of the log file

Maximal file size: Maximum file size before rotation of the log file

2-15

Agile PLM 9

Plug-Ins

Figure 2-22: Plug-Ins

Parameters:

ID: ID of plug-in

Name: Name of plug-in

Version: Version of plug-in

Load: Flag if plug-in is loaded (grayed when not changeable)



Plug-Ins/CAD Receiver Plug-In

Figure 2-23: CAD Receiver Plug-In

Parameter:

Port: Socket port for receiving calls from the CAD Connector

Plug-Ins/ECP Kernel Plug-In

Figure 2-24: ECP Kernel Plug-In

2-17

Agile PLM 9

Parameters:

Kernel host: Host name for receiving calls from the CAD Connector (should always be “localhost”)

Kernel port: Port for receiving calls from the CAD Connector

Protocol: Protocol for connecting to the EC Proxy (always Web service)

PLM Server URL: URL of Agile PLM Server Web Service Extensions

Partner ID: Type of connection to Agile PLM Server (always SdkConnector)

EC Client and Server Configuration OptionsIn order for the EC Client and server side components to work correctly, some configurations can be made after initial installation and deployment. Some of these configuration files apply to the EC Client (for example, defining the attributes displayed in object forms in the UI), and some of the configuration files can be used to configure the server side components like the PLM-API Web-Service. If you are not using the EC Client, but connecting to the PLM-API Web-Service from a 3rd party application, other configuration files apply.

For a full description of configuration options, see “EC Client and Server Configuration” in the Administration chapter.

Agile Data Model Configuration

In order to use the EC Client with Agile PLM, it is necessary to configure certain object sub-classes. These sub-classes are:

❑ Document - for storing CAD data in the generic Document sub-class, with CAD attributes on Page Two

❑ CAD Model - for storing CAD data in the specific CAD Model sub-class, with CAD attributes on Page Three (recommended)

❑ Part - for publishing Part BOM structures based on CAD data

❑ File folder - for saving CAD files, which are then attached to Documents or CAD Models

You should configure either Document or CAD Model, plus Part and File folder. Table 2-1 shows how the mapping is performed from the PLM API and the CAD connectors, to these specific object sub-classes. Tables 2-2 to 2-5 show the specific tabs and attributes that should be configured using the Agile Administrator client. The steps you need to perform are:

1 Make sure all listed tabs are turned on, for the specific sub-class

2 Using the name in the Default Attribute column (and the value in the BaseID column), find the attribute and change its name to the value in the Attribute Name column. Also make sure the attribute is turned on.

3 As noted in Table 2-2, not every attribute needs to be turned on. Attributes that are used are somewhat CAD Connector dependent. If you receive errors from your CAD Connector, you might need to check to make sure you have all necessary attributes enabled.

Note These steps can also be performed using the Agile Configuration Propagation Tool, rather than performing them manually.



Table 2-1: PLM API Definition (plm-api.xml)

PLM API Definition (plm-api.xml) CAD ConnectorNaming

Entity/Relation Attribute Type Attribute Use Symbolic Name

document creating-system Text Creating System CAX_CRE_SYSTEM

file-name Text File Name CAX_FIL_NAME

old-file-name Text Old Filename CAX_FIL_OLD_NAME

timestamp Text Timestamp for CAD CAX_TIMESTAMP

cad-type Text CAD Object Type CAX_TYPE

cad-sub-type Text CAD Object Subtype CAX_SUBTYPE

cad-family Text Part Family attribute CAX_FAM

variant Text Part Variant CAX_VAR

drawing-name Text Drawing name CAX_DWG_NAME

frame-id Text Drawing frame ID CAX_FRAME_ID

cad-name Text Prooject Name format CAX_NAM_FMT

project-name Text Project name CAX_PROJECT

local-flag Text Local flag CAX_LOCAL

file-path MultiText CAD File Path CAX_FIL_PATH

old-file-path MultiText CAD Old File Path CAX_FIL_OLD_PATH

cax-01 Text additional fields CAX_01




documentrelation cad-file-name MultiText File Name CAX_FILENAME

cad-transform MultiText As-saved Revision CAX_TRANSFORM

cad-ident Text Identifier CAX_IDENT

cad-component Text Component Code CAX_COMPONENT

cad-reference Text Reference code CAX_REFERENCE

cad-config Text Configuration code CAX_CONFIG

itemwhereused cad-filename MultiText File Name CAX_FILENAME



cad-component Text Component code CAX_COMPONENT



2-19

Agile PLM 9

part creating-system Text Creating System CAX_CRE_SYSTEM

file-name Text File Name CAX_FIL_NAME

old-file-name Text Old Filenmae CAX_FIL_OLD_NAME

timestamp Text Timestamp for CAD CAX_TIMESTAMP

cad-type Text CAD Object Type CAX_TYPE

cad-sub-type Text CAD Object Subtype CAX_SUBTYPE

cad-family Text Part Family attribute CAX_FAM

variant Text Part Variant CAX_VAR

drawing-name Text Drawing name CAX_DWG_NAME

frame-id Text Drawing frame ID CAX_FRAME_ID

cad-name Text Project Name format CAX_NAM_FMT

project-name Text Project name CAX_PROJECT

local-flag Text Local flag CAX_LOCAL

file-path MultiText CAD File Path CAX_FIL_PATH

old-file-path MultiText CAD Old File Path CAX_FIL_OLD_PATH





partpartrelation cad-file-name MultiText File Name CAX_FILENAME






itemwhereused cad-filename MultiText File Name CAX_FILENAME






documentfilerelation cad-last-view-date Date Timestamp CAX_TIMESTAMP

PLM API Definition (plm-api.xml) CAD ConnectorNaming



Table 2-2: Agile PLM configuration of Document sub-class

Subclass Tab Default Attribute Attribute Name BaseID Comment

Document PageTwo PAGE_TWO.TEXT11 CAD System 1301

PAGE_TWO.TEXT12 CAD Filename 1302

PAGE_TWO.TEXT13 CAD Old Filename 1303

PAGE_TWO.TEXT14 CAD Timestamp 1304 Legacy, not used any more

PAGE_TWO.TEXT15 CAD Type 1305

PAGE_TWO.TEXT16 CAD Subtype 1306

PAGE_TWO.TEXT17 CAD Family 1307

PAGE_TWO.TEXT18 CAD Variant 1308

PAGE_TWO.TEXT19 CAD Drawing Name

1309

PAGE_TWO.TEXT20 CAD Frame Id 1310

PAGE_TWO.TEXT21 CAd Name Format 1311

PAGE_TWO.TEXT22 CAD Project Name 1312

PAGE_TWO.TEXT23 CAD Local Flag 1313

PAGE_TWO.MULTITEXT31 CAD Filepath 1331

PAGE_TWO.MULTITEXT32 CAD Old Filepath 1332

PAGE_TWO.TEXT01 2007 Not necessary to configure




BOM BOM.MULTITEXT30 CAD Filename 1341

BOM.MULTITEXT31 CAD Revision 1342

BOM.TEXT01 CAD Ident 2175

BOM.TEXT02 CAD Component 2176

BOM.TEXT03 CAD Reference 2177

BOM.TEXT04 CAD Config 2178

WhereUsed BOM.MULTITEXT30 CAD Filename 1413






Attachments ATTACHMENT_MAP.ATTACHMENTTYPE

Attachment Type 4681 Add these list values:

SOURCE

VIEWABLE

BASELINE

2-21

Agile PLM 9

Table 2-3: Agile PLM configuration of CAD Model sub-class


CAD Model PageThree PAGE_THREE.TEXT11 CAD System 1585

PAGE_THREE.TEXT12 CAD Filename 1586

PAGE_THREE.TEXT13 CAD Old Filename 1587

PAGE_THREE.TEXT14 CAD Timestamp 1588 Legacy, not used any more

PAGE_THREE.TEXT15 CAD Type 1589

PAGE_THREE.TEXT16 CAD Subtype 1590

PAGE_THREE.TEXT17 CAD Family 1591

PAGE_THREE.TEXT18 CAD Variant 1592

PAGE_THREE.TEXT19 CAD Drawing Name

1593

PAGE_THREE.TEXT20 CAD Frame Id 1594

PAGE_THREE.TEXT21 CAD Name Format 1595

PAGE_THREE.TEXT22 CAD Project Name 1596

PAGE_THREE.TEXT23 CAD Local Flag 1597

PAGE_TWO.MULTITEXT31 CAD Filepath 1570

PAGE_TWO.MULTITEXT.32 CAD Old Filepath 1571

PAGE_THREE.TEXT01 1575 Not necessary to configure
















Attachments ATTACHMENT_MAP.ATTACHMENTTYPE

Attachment Type 4681 Add these list values:

SOURCE

VIEWABLE

BASELINE



Table 2-4: Agile PLM configuration of Part sub-class

EC Client Log File

The default log file name for the EC 1.2 client is ecp-client.log and is created in the user’s temp folder. This file can be used to see what is happening during the client session. Users can change the location and name of the file by setting it in the EC client preferences. Note that in the preferences you can also turn on the log display interactively, while working in the EC client.


Part PageTwo PAGE_TWO.TEXT11 1301 Page Two attributes onParts are generally notnecessary to configure inAgile Admin

PAGE_TWO.TEXT12 1302












PAGE_TWO.MULTITEXT31 1331

PAGE_TWO.MULTITEXT32 1332

















File folders Files VERSION_FILE_MAP.DATE01

CAD Timestamp 6151

2-23

Agile PLM 9

Agile Roles and Privileges

Agile roles and privileges is too extensive an area of Agile to be covered in detail here; for more information, see the Administrator Guide. However, some aspects are critical to proper operation of the EC Client.

Create a role or roles for those CAD users who will create objects in Agile through the Engineering Cooperation Client. They should have privileges to modify objects from any Document subclass(es) that you have created – for example, a subclass called CAD Model – to be used to store CAD data. Other users should not have Modify privileges to these subclasses.

Privileges required to access and change Document objects include:

❑ Modify object in a preliminary state

❑ Modify redlined BOM

❑ Check in object in a preliminary state

❑ Check out object in a preliminary state

Checkin and Checkout should be specifically excluded when the object has left the preliminary state, otherwise it will be possible to modify data that is in Released status through the EC Client, as well as Java Client or Web Client.


CHAPTER 3Administration

This presents basic concepts and capabilities for administration of the CAD Connectors. The chapter contains the following topic:❑ EC Client and Server Extensions❑ EC Client and Server Configuration

EC Client and Server ExtensionsBy using the extension mechanism, it is possible to enhance the EC Client and also the EC Server. Both the EC client and the EC Server support the PLM-API, which supports a certain set of operations and parameters.

The PLM-API is used for communicating with the EC Client in order to create and modify PLM objects, check-in and check-out files or simply just display data on the EC Client screen. The communication from the CAD Connector to the EC Client (through the PLM-API) is handled via Socket-mechanism.

Although the EC Client and the EC Server (Web Service) also “talk” via the PLM-API, they employ a different communication mechanism, which is via http (Web Service call). The PLM-API being used between the EC Client and the EC Server is almost identical to the CAD-Connector to EC Client API.

The EC Client framework allows to add additional operation calls, which are normally called from the CAD Connector. The EC Server can also be enhanced by adding additional operations, which can be called through Web Service. Those operations are normally called by the EC Client, but can also be called by other 3rd party applications, which is not covered in this document.

3-1

Agile PLM 9

Figure 3-1: System Architecture

EC Client Extensions

The EC Client employs the Callable concept which means that for every operation, which is called from the CAD Connector, a respective Java-based Callable exists inside the EC Client framework. When you want to provide additional operations in the EC Client, you would need to write new Callables and embed them in the EC Client.

In general, you have to go through following steps for providing new operations inside EC Client:

❑ Develop a new Plug-in for the Client. To do this, you should either extend the class com.agile.ecp.client.AbstractClientPlugIn or the class com.agile.ecp.client.AbstractClientUIPlugIn. These two classes provide the basis to implement a client’s plug-in with the difference that the second one can override actions intended to be handled by the UI, this is, those which are marked as ui=”true” in the actions configuration file. Compile the plug-in class against following libraries: ecp-action.jar, ecp-client.jar, agile-share.jar, ep-jacc.jar. Please see an example of a Plug-in in the PLM API Java Documentation in com.agile.ecp.plugin.sample.callable.UsernamePrefixPlugin.

❑ Develop a new ActionCallable, which implements the interface class com.agile.ecp.action.ActionCallable. Optionally, you could extend the class com.agile.ecp.action.impl.AbstractActionCallable. Compile this callable against following libraries: ecp-action.jar, agile-share.jar, ecp-plm-api.jar. Please see an example in the PLM API Java Documentation in com.agile.ecp.plugin.sample.callable.UsernamePrefixCallable.

❑ Create your own Java JAR file, which contains the class files of above Plug-in and ActionCallable, and any other classes required by the new plug-in. Do not include in this JAR file the JAR files against which it was compiled mentioned in the two previous steps.

❑ Sign the JAR file using your own keystore and key.

❑ Put the JAR file in the lib directory of the ECP Client deployment directory. This is normally of the type <oas_install_path>/j2ee/home/applications/EcpClient/lib. Please keep in mind that this location might be different depending on the used application server.

❑ Create a new JNLP file to describe the customization component. The new JNLP file should have, at least, the following entries:

<?xml version="1.0" encoding="utf-8"?><jnlp spec="1.0+" codebase="$$codebase" href="custom_plugin.jnlp"><information><title>Your Title</title><vendor>Your Vendor</vendor>

</information><security><all-permissions/>

</security>


Chapter 3 Administration

<resources><jar href="lib/your-jar.jar"/></resources>

<component-desc/></jnlp>

Give this JNLP file a meaningful name and place it in the ECP Client deployment directory, next to the file ecp-client.jnlp.

Please make also sure to replace the words in italics with meaningful values.

❑ Modify the file ecp-client.jnlp to include a line that reads:

<extension name="Your Customization Component Name" href="your-jnlp.jnlp" part="main"/>

within the ‘resources’ node, where your-jnlp is the name given to the JNLP file.

❑ Activate the client’s plug-in by modifying the file ecp-client.defaults. In this file, add the following entries:

Plugin.{plug-in-name}={full-plug-in-class-name}Plugin.{plug-in-name}.load=true

where {plug-in-name} is any name to be given to the plug-in and the full-plug-in-class-name should point to the Plug-In class and include the package name.

❑ Modify the action nodes in the XML configuration file as follows: Locate the “function” node of the function you want to override, which should be under “ecp-acm-functions”. If the new action callable provides support for a new function, then you need to create a new function node under “ecp-acm-functions”. Under this node, modify or create a parameters node if parameters will be used in the function, and modify or create an action-map node including an action node which specifies the action to be executed by the new ActionCallable. As an example, consider the plug-in: UsennamePrefixPlugin, which is a sample plug-in for the customization of the ECP client, which prefixes the file names assigned by the server with the operating system username of the currently logged in user. Since this affects the createObject function, a new atomic action should be included after the original one has completed successfully. So the createObject function ends-up like this:

<function name="createObject"><parameters/><action-map><action name="createObject" ui="true"/><action name="prefixFiles" ui="true" conditional="true" status="=S"/>

</action-map></function>

❑ Relaunch the EC Client. Please consider that some browsers cache the JNLP file, so you might need to make sure that the JNLP file is refreshed.

Now you are able to call this new Callable from the CAD Connector. It is recommended to validate the Callable by using the Test Framework, which is available from Agile for testing the PLM API.

3-3

Agile PLM 9

EC Server Extensions

Note The explanation below describes the current status where support for the action configuration file is not yet implemented in the server side

The EC Server employs a concept similar to the EC Client, where the action calls for one entity are grouped into a class implementing the interface PlmObjectHandler, which maps those web-service PLM API calls into Agile 9 specific SDK calls.

In general, you have to go through following steps for providing new operations inside EC Server:

❑ Develop a new handler, which implements following Interface: com.agile.ecp.plm.connector.handler.PlmObjectHandler. Compile this handler against following libraries: ecp-connector.java, ecp-plm-api.jar, ecp-action.jar.

Please see an example in the PLM API Java Documentation in the package com.agile.ecp.samples.server.handler.CustomDocument.

❑ Alternatively you can extend one of the existing handlers, if the intention is to provide custom functionality for one of the out-of-the-box entities. In this case, you can review the connector configuration file to identify the appropriate handler to extend and include the appropriate library (ecp-connector-sdk.jar or ecp-connector-eci.jar) when compiling the new handler.

❑ Package the handler in a JAR file and put the JAR File in following directory on the Agile 9 Server: <a9_install_path>/agileDomain/integration/sdk/extensions, which is the same location where the EC WebService Proxy JAR file (EcpWsProxy.jar) is located.

❑ Activate the object handler by adding a reference to it in the appropriate connector configuration file, for example, the SdkConnector uses the ecp-plm-sdk.xml configuration file. Within this file, locate or create the object node for the entity you want to handle with the new handler, which should be under ecp-plm/configuration/object-mapping. Replace the value for the handler attribute with the full class name of the new handler. This file is included within the EC WebService Proxy JAR file (EcpWsProxy.jar), so in order to edit it, it needs to be extracted from the JAR file and once edited, it should be added back to the JAR file. There is no need to sign this JAR file as it is not loaded via WebStart.

Now you are able to call this new Callable from the EC Client. It is recommended to validate the Callable by using the Test Framework, which is available from Agile for testing the PLM API.

EC Client and Server ConfigurationThe Engineering Collaboration Platform is designed to be extensible both on the server side and the client side. This may be required when adding or modifying attributes or entities in the Agile 9 server. Table 3-1 and Figure 3-2 summarize all the configuration files, and then you will find a listing of the specific options contained in each file. Finally, the section on typical use cases describes how to configure the files in some example cases.

Table 3-1: Configuration files

File Name Content Location after deployment

ecp-cax.xml Definition for the CAX Receiver for calls coming through the old Socket API

EC Client

ecp-client.defaults General EC Client configuration EC Client

ecp-client.xml EC Client User-Interface configuration and attribute mapping to a key (for localization)

EC Client

ecp-client.properties (ecp-client_de.properties)

Localization files for EC Client. EC Client

ecp-kernel.xml Definition of the EC Client callables (methods) EC Client



Note Since the plm-api.xml file defines what entities, attributes and options are available for the EC Client, any other configuration file needs to adhere to this definition. So either the client configuration file or the server connector configuration file have to refer to entities, attributes and options which are valid according to the definition stated in plm-api.xml.

Note With EC 1.2 a new subclass “CAD Model” for the administration of CAD data was introduced in order to enable a better separation from different document types.

Figure 3-2: Configuration Files

EC Client Configuration - Typical Use Cases1 Change the CAD model subclass (e.g. from “CAD Model” to “Model”)

• Extract the file ecp-plm-sdk.xml from the file EcpWsProxy.jar and modify the subclass nodes of the node given by the following XPath:

• /ecp-plm/configuration/subclasses/object[@name="document"]

• The subclasses associated to the ‘document’ entity by default are “CAD Model” (the default) and “Document”, so these nodes need to be modified to match the deployment. Note that the subclasses are referenced by name and not by id, so no need to look for the subclass id.

plm-api.xml Definition of the objects, attributes and operations to be used from the PLM-API client (CAD Connector or 3rd party PLM-API Client)

EC Client, Server-side, CAD Connector or 3rd party PLM-API Client

plm-api.properties

(plm-api_de.properties)

Localization files for PLM API (entities and attributes) EC Client, Server-side, CAD Connector or 3rd party PLM-API Client

ecp-log.properties PLM-API client-side log properties EC Client, Server-side, CAD Connector or 3rd party PLM-API Client

ecp-plm-sdk.xml Mapping of EC Client (PLM-API) attributes to Agile 9 specific attributes, which are used for the local SDK calls, in so-called Handlers.

Server-side

ecp-plm-eci.xml Mapping of EC Client (PLM-API) attributes to Agile e6 specific attributes. THIS IS CURRENTLY NOT USED.

Server-side

Table 3-1: Configuration files

File Name Content Location after deployment

3-5

Agile PLM 9

• Reinsert ecp-plm-sdk.xml into the jar file.

• Note that the default attribute is used on the server side, to determine which subclass to use when creating a new object in the server, when the subclass to use is not specified, so setting the default attribute for one of the subclasses doesn’t guarantee that this subclass will appear as the default in the EC Client dialogs.

2 Turn off a Page Three attribute, if you know it’s not needed

• In the Agile admin client, change the “Visible” flag for the specific attribute to “No”

• Extract the file ecp-plm-sdk.xml from the file EcpWsProyx.jar and look for the mapping to this field, based on the field’s id. Comment out this mapping.


• With these three steps, the attribute will still show up in the EC client, but will never have a value. To remove this attribute from the client (in the object form or the properties form), then the process is: Locate the file ecp-client.xml file in the client deployment (this would be normally within the EcpClient.war file or, if this war file has been expanded in the deployment, then directly under the directory structure within agileDomain/applications/EcpClient). In this file, comment the entries related to the attribute which is not in use) and, if necessary, reinsert it into the WAR file.

• Alternatively to the four steps above, if you only execute the fourth step, the attribute can still be used by the CAD integration but will never be visible to the user within the EC client.

3 Change the base ID of a Page Three attribute, for example because the default one is already used

• In the Agile admin client, pick a different attribute of the correct attribute type, and turn on visibility. You can set the Name field as well; this affects the Agile web client but not the EC client.

• Extract the file ecp-plm-sdk.xml from the file EcpWsProxy.jar and modify the mapping for the corresponding attribute by replacing the id of the default attribute with the id of the attribute selected in the step above.


4 Turn on a Page Three attribute, to use it for additional data exchange with the CAD system (e.g. “Drawn By”)

• In the Agile admin client, pick a desired attribute, edit the Name value, and turn on visibility.

• Extract the files plm-api.xml and ecp-plm-sdk.xml from the file EcpWsProxy.jar

• Modify the file plm-api.xml to add a new attribute node for the document entity definition node (/plm-api/objects/object[@name="document"]), the attribute node would be similar to the other attributes, something like:

• <attribute name="drawn-by" type="string" value="" required="false"/>

• Modify the file ecp-plm-sdk.xml to add a new mapping node for the new attribute. Since this is a P3 attribute, the mapping needs to be done at a subclass level, so the node will be added to the appropriate subclass mapping node (/ecp-plm/configuration/attribute-mappings/object[@name="document"]/subclass-mappings/subclass[@name="CAD Model"] where “CAD Model” needs to be replaced by the corresponding subclass in the deployment). The added node would be similar to the others, something like:

• <mapping source="drawn-by" destination="xxxx"/> where xxxx needs to be replaced with the base ID of the new P3 attribute.

• Reinsert these two files into the jar file.

• Locate the plm-api.xml file in the client deployment structure and overwrite it with the same new version that was reinserted into the jar file in the step above (this is required as the PLM API definition needs to be in sync between client and server sides).



• To show this attribute in the EC client, follow these steps:

a Locate the file plm-api.properties within the client deployment structure and edit it to add an entry to configure the name of the new attribute when it’s displayed in the EC client, something like:

• attribute.drawn-by.name=Drawn by

b Locate the file ecp-client.xml within the client deployment structure and edit it according to the following steps:

• To show the attribute in one of the tabs of the document object form: Locate the desired tab’s definition node (for Page Three it will be: /ecp-client/objects/object[@name="document"]/tabbed-display/tabs/tab[@name="Page Three"]) and add a new attribute entry to it, which will look similar to the other attribute entries, something like:

<attribute name="drawn-by" label-key="Drawn By" display="true" order="20"/>

• To show the attribute in the lower section of the interactive Save dialog, locate the node that defines the document entity for this dialog (/ecp-client/form-specific/form[@name="ECPPropertiesDialog"]/objects/object[@name="document"]) and add a new attribute entry to it, which will look similar to the other attribute entries, something like:

<attribute name="drawn-by" display="true" read-only="false" order="6"/>

c If necessary reinsert the files plm-api.properties and ecp-client.xml to the file EcpClient.war.

5 Turn a tab of an object form on or off (e.g. turn on the BOM tab for the CAD Model subclass)

• You can decide if you want to show or hide any tab for any entity, as well as which attributes to include in each tab. For all use cases described above, since the BOM tab for the document entity is already defined in the file ecp-client.xml, you can toggle its visibility by following the steps below:

• Locate the file ecp-client.xml within the client deployment structure and change the value of the display attribute to “true” or “false” of the tabbed display configuration node for the document entity (/ecp-client/objects/object[@name="document"]/tabbed-display/tabs/tab[@name="BOM"])

• If necessary reinsert the file ecp-client.xml to the file EcpClient.war.

PLM API❑ Extract the file plm-api.xml from the JAR file EcpWsProxy.jar (from <a9_install_path>/agileDomain/

integration/sdk/extensions).

❑ Open the file plm-api.xml and find the object that you want to modify. If you added or changed a subclass in the Agile 9 server, you need to create a new object section in the plm-api.xml file. The easiest way to do that is to copy an existing object definition and modify it to your needs.

❑ For the changed attributes in Agile 9, you need to create attributes names. Please note the field ID along with the attribute name as you will need it later.

❑ Please check the attribute type with the type of the field in Agile 9, especially for date/time values (datetime) and when only a predefined list of values are allowed (single-selection). The old-name value is for backward compatibility with EC 1.1 only and should not be changed.

❑ If you need to change the localization of attributes, change the files plm-api.properties (English) and plm-api_de.properties.

❑ Put the modified files back into the JAR file EcpWsProxy.jar.

❑ Deploy these files also in the EC Client’s web application directory (for OAS: <oas_install_path>/j2ee/home/applications/EcpClient/EcpClient).

3-7

Agile PLM 9

Table 3-2: Description of the XML nodes in the file plm-api.xml

Configuration Description

plm-api The top-level node of the PLM API definition file.

objects Node that groups the definition of each entity defined in the PLM API. Each ‘object’ node underneath this one represents the definition of one entity.

object Definition of one entity. Two attributes of the this XML node are required for each object specified, which are shown below, the rest if the attributes are used to specify the options that are available for the entity, accessible through the methods:

PlmObject.getOptions(),

PlmObject.setOptionValue(…) , and

PlmObject.getOptionValue(…).

name Specifies the name of the entity.

id Must be set to xsd:ID and it allows each instance of this entity to be uniquely identified in the XML representation of the PlmData of a request or response.

attributes Groups the attributes defined for the entity. Only those attributes contained within this node are available for the entity and accessible through the methods:

PlmObject.getAttributes(),

PlmObject.getAttributeValue(…), and

PlmObject.setAttributeValue(…).

attribute Defines one single attribute for the corresponding entity. This node has XML attributes which configure the PlmAttribute and are shown below.

name The name of the attribute.

type The type of the attribute. Valid values are specified in plm-api.xsd and include: string, integer, float, datetime, single-selection and multiple-selection.

value Specifies an initial or default value of the attribute.

required Can have the values ‘true’ or ‘false’. If set to ‘true’, then the attribute must be specified for each object of this entity before including the object in a request.

send-back This attribute was implemented for backwards compatibility with EC 1.1 and is no longer used in EC 1.2.

old-name This is an optional attribute, and is used by the CAD Connector adapter for the socket communication to locate attributes using the EC 1.1 naming schema. The value of this XML attribute should match the field name as known by EC 1.1.

relations Node that groups the definition of each relation defined in the PLM API. Each ‘relation node underneath this one represents the definition of one relation between two entities.

relation Definition of one relation. The three attributes shown below can be used for the XML node for specific purposes within the definition of the relation, however, the ‘name’ attribute must be present, the rest if the attributes are used to specify the options that are available for the entity, accessible through the methods:

PlmRelation.getOptions(),

PlmRelation.setOptionValue(…) , and

PlmRelation.getOptionValue(…).

name Specifies the name of the relation.



EC Server (WebService)❑ Extract the file plm-api-sdk.xml from the JAR file EcpWsProxy.jar (from <a9_install_path>/agileDomain/

integration/sdk/extensions).

❑ Open the file plm-api-sdk.xml and find the attribute mapping section for the object you want to change. The objects names are defined in the file plm-api.xml (see section PLM API).

❑ Add or change the attribute(s) according to the changes in the Agile 9 server. Please make sure that the destination value matches the field ID in Agile 9.

❑ Put the file plm-api-sdk.xml back in the JAR file EcpWsProxy.jar.

Table 3-3: Description of the XML nodes in the file ecp-plm-sdk.xml

id If used, must be set to xsd:ID and it allows each instance of this relation to be uniquely identified in the XML representation of the PlmData of a request or response.

child-id Should always be set to xsd:IDREF and it ensures that the child object of this relation is uniquely identified in the XML representation of the PlmData of a request or response. Since this is normally the case, the use of this XML attribute is optional.

attributes Groups the attributes defined for the relation. Only those attributes contained within this node are available for the relation and handled through the methods:

PlmRelation.getAttributes(),

PlmRelation.getAttributeValue(…), and

PlmRelation.setAttributeValue(…).

attribute Defines one single attribute for the corresponding relation. This node has XML attributes which configure the PlmAttribute and are shown below.

name The name of the attribute.

type The type of the attribute. Valid values are specified in plm-api.xsd and include: string, integer, float, datetime, single-selection and multiple-selection.

value Specifies an initial or default value of the attribute.

required Can have the values ‘true’ or ‘false’. If set to ‘true’, then the attribute must be specified for each object of this entity before including the object in a request.

send-back This attribute was implemented for backwards compatibility with EC 1.1 and is no longer used in EC 1.2.

old-name This is an optional attribute, and is used by the CAD Connector adapter for the socket communication to locate attributes using the EC 1.1 naming schema. The value of this XML attribute should match the field name as known by EC 1.1.


ecp-plm The parent node of the server side mapping configuration file.

configuration Is the parent node of all the configuration of the server side’s mappings for entities, relations and their attributes.

object-mapping Groups the object mapping nodes, that is, the nodes which specify what Java class of the server side implementation is going to handle the functions related to each entity defined in the PLM API.


3-9

Agile PLM 9

object Each object node represents the mapping of one entity to the class that is going to handle its functions. Two XML attributes of this node are used for this purpose, as described below.

name The name of the entity, as defined in the PLM API configuration file.

handler The fully qualified name of the Java class in the server side Proxy implementation that will handle the entity’s functions.

table-mapping Groups the table mapping nodes, that is, the nodes which describe the mapping between tables of the objects in the A9 server to relations defined in the PLM API.

table Each table node represents a mapping between one table of an object in the A9 server and one relationship. Four XML attributes of the node are used to describe the mapping, as described below.

id The id of the table in the a9 server.

relation-type The name of the relation to be used to represent rows of this table, as defined in the PLM API definition file.

child-entity The entity to use for the child object of the relation.

comment Optional, is used simply to add additional information to the mapping, it’s not used by the server implementation.

subclasses Groups the subclass mapping nodes, that is, the nodes which specify which subclasses of objects in the a9 server will be mapped to an entity defined in the PLM API.

object Each object node represents an entity as defined in the PLM API. Each entity might be mapped to one or more subclasses, which will be represented by the subclass nodes underneath this one. Only one XML attribute exists for this node, as described next.

name The name of the entity.

subclass Each subclass node represents a subclass in the a9 server, to which the encompassing entity is mapped. Two attributes are used to configure the subclass node:

name The name of the subclass, exactly as defined in the a9 server.

default Optional, if set equal to ‘true’ specifies that the corresponding subclass should be used by default to create objects of this entity in the a9 server. If more than one subclass node has the default attribute equal to ‘true’, then the last one read will become the default subclass.

attribute-mappings Groups the mapping of attributes and relations to fields in the a9 server of the corresponding objects. These mappings can be general, that is, they apply to all subclasses mapped to the entity or relation, or specific for one of the mapped subclasses, as described below.

object Each object tab represents one entity or relation as defined in the PLM API and groups all the mappings for this entity or relation, both general and subclass specific. This XML node has only one attribute:

name The name of the entity or relation.

mappings Groups the general attribute mappings, that is, the mappings which apply to all subclasses.

mapping Defines the mapping of one attribute of the corresponding entity to one field in the a9 server. Three XML attributes of this node are used to configure the mapping as described below.

source The name of the entity’s or relation’s attribute as defined in the PLM API definition file.

destination The id of the field in the a9 server, to which the attribute in the PLM API should be mapped.




EC Client❑ Open the file ecp-client.xml from the EC Client’s web application directory (for OAS: <oas_install_path>/j2ee/

home/applications/EcpClient/EcpClient).

❑ Search for the changed attribute or a related one if you added a new attribute. Please check and/or modify the values of the attributes. For more information on the configuration values, please refer to the table below.

❑ If you need to change the localization of attributes, edit the files ecp-client.properties (English) and ecp-client_de.properties (German).

❑ The modified files will be used by each EC Client that is started after the changes are applied to the files.


subclass-mappings Groups all the subclass specific mappings for all subclasses associated with the entity.

subclass Each subclass node groups all the subclass specific mappings that apply to one single subclass. There is only one attribute for this node:

name The name of the subclass, as defined in the a9 server.

mappings Groups the attribute mappings for the corresponding entity and subclass.

mapping Defines the mapping of one attribute of the corresponding entity and subclass to one field in the a9 server. Three XML attributes of this node are used to configure the mapping as described below.

source The name of the entity’s or relation’s attribute as defined in the PLM API definition file.

destination The id of the field in the a9 server, to which the attribute in the PLM API should be mapped.


Table 3-4: Description of the XML nodes in the file ecp-client.xml:


ecp-client The parent node of the EC client configuration file.

default-document-entity Is used by the client to determine which entity type to use when preparing a document object representation. This value is set to ‘document’ and normally it shouldn’t be changed.

default-part-entity Similar to the configuration node above, this entry determines what entity to use by default for Parts. Default value is ‘part’.

default-change-entity Similar as the two entries above to specify entity to use to represent changes. Default value is ‘change’.

home-folder-filter-info This is a legacy configuration entry from EC 1.1, which allows the user to specify which user folders to filter.

search-entities Determines which entities to use for quick search and advanced search.

file-operation-settings This node groups all the configuration entries related to handling file operations. They are described in the following lines:

autoCheckout Whether to mark the checkout flag by default if it’s not specified.

keepCheckedOut Whether to mark the keep-checked-out flag by default if it’s not specified.

autoCheckin Whether to mark the check in flag by default if it’s not specified.


3-11

Agile PLM 9

saveOption Value of the save option flag. See EC documentation for a description of the possible values and their meaning.

viewable The name to use for description in the attachment row for files of type viewable.

source The name to use for description in the attachment row for files of type source.

baseline The name to use in the description of baselines.

viewables The extensions of files that are considered viewable files.

objects Node that groups the client side configuration of each entity defined in the PLM API. Each ‘object’ node underneath this one represents the configuration of one entity.

object Client side configuration of one entity. The attributes of each ‘object’ node allows to specify certain client option, as described below:

name The name of the entity. Must match exactly the entity name as specified in plm-api.xml.

leaf-icon-resource Determines what icon to use to represent objects of this type in a tree table when the object doesn’t have child relationships shown in the table.

expanded-icon-resource Determines what icon to use to represent objects of this type in a tree table when the object has child relationships being shown in the table and is shown expanded.

collapsed-icon-resource Determines what icon to use to represent objects of this type in a tree table when the object has child relationships being shown in the table and is shown collapsed.

options/attributes These nodes, when used directly underneath the ‘object’ node, represent the options and attributes to be shown by default in forms, that is, when the specific form configuration is not found.

tabbed-display Configures the way that attributes of objects are arranged and display in tabs within the EC client when displaying the object form. This configuration is done based on the entity’s name. The attributes of the tabbed-display node are used to configure the functionality that is common to all tabs, as described below:

show-revision-list If set to true, the object frame shows a dropdown of the object’s revisions.

show-add-file If set to true, then to command button to add a file to the object is shown above the tabs.

show-send-to-cad If set to true, then the ‘Send to CAD’ button is shown above the tabs.

show-site-list If set to true, then a dropdown with all sites is shown above the tabs.

icon-resource Determines what icon to use on the object’s frame window.

show-comment-actions If set to true, then the buttons related to the ‘comment’ action are shown above the tabs.

show-route-actions If set to true, then the buttons to route the object are shown on top of the tabs.

show-approve-actions If set to true, then the buttons related to the approve or reject actions are shown above the tabs.

tabs This node groups the ‘tab’ nodes, where each tab node configures one of the tabs to be displayed in the object frame for the corresponding entity.

tab Configures one of the tabs to be displayed for the form. The attributes of this node help define how the tab will behave as well as the type of information that will be show in it. They are described below.

name The name of the tab, this is only used internally.





order The numeric order of this tab in the object form.

label-key The key to the localizable string containing the tab’s name to be displayed in the EC client.

is-relation If set to true, then the tab will be used to display rows of certain relation types of the object. When a tab is set to be relational, then the tab will display either a table or a tree-table.

is-multi-level If set to true, then the tab will display the relations as a tree-table, recursing into lower levels.

display If set to false, then the tab will be hidden.

attributes This node groups the attributes that will be shown within the tab, both for relational and non-relational tabs.

attribute Defines a single attribute that will be displayed in a tab. The node’s attributes are used to configure the attribute to be shown as described below.

name Name of the attribute, this must correspond to an attribute or an option of the entity, as defined in PLM API.

label-key Defines the key of the localizable string to be used to display the attribute’s name.

order Defines the place relative to other attributes in which the attribute will be shown.

display If set to false, then the attribute will be hidden.

name-aliases This node is used to group name aliases for other entities, that is, when a tab of the main entity may contain rows referring to different entities, the attribute name might not be the same for each possible entity, which is why a name alias may be specified if needed.

name-alias This node defines a single name-alias for an attribute and an entity, which are specified through the node’s attributes, as described below:

entity The entity to which the name-alias applies.

name The name of the attribute to use when a row refers to an entity of the specified entity.

form-specific This node groups the configuration of entities based on forms, that is, the specific information of how to display objects of the corresponding entity in a given form.

form Each ‘form’ node defines the configuration of one single form. Within this node, the ‘objects’ node will contain the configuration for the entities. The only attribute applicable for the form node is ‘name’, which specifies the internal name of the form.

objects Groups the configuration of the entities.

object Contains the configuration of one single entity in the given form. The only attribute of this node, ‘name’ is used to specify the name of the entity to which the configuration corresponds.

attributes Groups the attributes of the entity to be displayed in the form.

attribute Defines how to display one attribute of the entity within the form. The attributes of the XML node are used to specify the attribute, identically as when configuring an attribute to be shown in a tab, as described above. The only additional attribute for this node is ‘component’, which is described next.

component Specifies the name of a UI component in the form, which will be used to display and edit the attribute’s value.

options Groups the options of the object to be displayed in the form.



3-13

Agile PLM 9

Table 3-5: Description of the XML nodes in the file ecp-kernel.xml

option Defines how to display one option of the entity within the form. The attributes of the XML node are used to configure the option, just as with attributes described above.

table-models Groups the definition of the model to display objects in tables which are part of the UI. The configuration aims at defining which columns a table has and which attribute’s value or option’s value is shown in each column.

table-model Each ‘table-model’ node defines the configuration of a single table. The only attribute for this node is name, which is used to specify the internal name of the table.

columns Groups the definition of the columns to be shown in the table.

column Configures a single column. The attributes of the XML node are used to configure the column, as described below:

name The name of the attribute or option to display in this column.

label-key The key of the localizable string to use to display the column’s name.

tool-tip-key The key to the localizable string for the text to display as tool-tip for the column.

order The order of this column in the table, relative to the other columns.

display If set to false, then the column is hidden.

read-only If set to true, then the column’s value cannot be edited.

column-width Specifies the width of the column in points.

name-aliases Used to specify name-aliases for the column’s attribute or option for specific entities. This is handled identically as will tab’s attributes’ name aliases, as described above.


ecp-kernel The parent node of the EC client’s kernel configuration file.

ecp-acm-functions Groups the definition of the functions to be recognized by the Action Call Manager.

function Defines one single function to be recognized and controlled by the Action Call Manager. There is only one XML attribute for this node:

name The name of the function.

parameters Groups all the parameters defined for the function. This node is optional and can be omitted if no parameters are defined for the function.

parameter Each parameter node defines one single parameter for the function. Two XML attributes are used to configure the parameter.

name The name of the parameter.

default-value Optional, allows to specify a default value for the parameter if it’s not specified.

action-map Groups the sequence of atomic actions that should be executed when the function is called. This node is optional and can be omitted if the only atomic action to be executed as part of this function call has the same name as the function itself.

action Each action node specifies one single atomic action to be executed when calling this function. The atomic actions are executed one after another in the same order that they appear in the XML file, eventually depending on the result of the previous action’s result. The following attributes are used to configure the atomic action:





name The name of the atomic action, exactly as the Action Call Manager should use it to execute the atomic action.

ui Optional. If set to ‘true’ then the atomic action is sent to the UI CallableManager and handled by any class registered to handle it within this manager. If omitted or set to ‘false’, the atomic action is handled by the EC Client Platform’s CallableManager.

conditional Optional. If set to ‘true’ then the execution of this atomic action depends on a condition which is related to the result of the previous atomic action. If this attribute is set to ‘true’ for the first atomic action in the sequence it’s ignored.

status Optional. Allows to specify the condition to execute this atomic action based on a comparison to the status of the result of the previous atomic action. The value for this attribute can be specified using the operators ‘=’ (equal) and != (not equal), so for example, a value of “=S” will mean that this atomic action will only be executed if the status of the previous atomic action’s execution equals ‘S’ (success).

code Optional. Allows to specify the condition to execute this atomic action based on a comparison to the code of the result of the previous atomic action. The value for this attribute can be specified using the operators ‘=’ (equal) and != (not equal), so for example, a value of “=0” will mean that this atomic action will only be executed if the code of the previous atomic action’s execution equals ‘0’.

data-size Optional. Allows to specify the condition to execute this atomic action based on the size of the PlmData (that is, the number of PlmObjects in it) of the result of the previous atomic action. The value for this attribute can be specified using the operators =,>,<,>=,<=, so for example, a value of “>0” will mean that this atomic action will only be executed if the number of objects returned by the previous atomic action call is greater than zero.


3-15

CHAPTER 4Using Engineering Collaboration

ClientThis presents the steps for using your installed Engineering Collaboration Client. It is intended for the end-user of Agile Engineering Collaboration Client and CAD Connectors. Attachments and searches are fully documented in Product Collaboration Client Handbook. This chapter contains the following topics:❑ Starting the Client and connecting to Agile❑ Disconnecting from Agile and closing the Engineering Collaboration Client❑ Using the Engineering Collaboration Client

Agile Engineering Collaboration Platform provides integration between CAD systems and the Agile PLM software, to allow you to manage your CAD data and processes. It consists of a core Engineering Collaboration Client (formerly also known as the “CAX Client”), and individual Engineering Collaboration Connectors to the specific CAD systems (such as Pro/ENGINEER, SolidWorks, etc.). Since most of the operation of Engineering Collaboration Platform (EC Platform) is common between all the supported CAD systems, this User Guide is written to cover the user operations in a common way. Where differences between CAD systems do exist, they are clearly identified in the documentation.

Starting the Client and connecting to AgileWhen the user first starts the CAD system, the Agile menu is available but a connection to Agile has not yet been established. The first task is to start the EC Client, which is done using the Start Client command (note: In the Pro/E Connector this happens automatically). Once the client has been started, you will then need to log in to Agile. There are different ways to do this, depending on your preference:

In practice, the third method, although less obvious, is typically used since it requires less user input.

Note The SolidWorks Connector for EC 1.2 launches the web browser with the URL to the login page from where the EC Client can be started.

Table 4-1: Connecting methods

Connect Method Approach

Login from EC Client From the EC Client window, pick the Login icon or the File > Login… command.

Login using Agile > Connect From within CAD, pick the Agile > Connect command

Login using any Agile menu command From within CAD, pick any Agile menu command that will force a login (such as Save, Load, etc.)

4-1

Agile PLM 9

After using one of these login methods, an Agile login screen will appear as shown in Figure 4-1. The user logs in to Agile, just as if they were logging in to a regular Agile client, and then the connector’s connection to Agile will be established. After this point, the connector can communicate with Agile as needed until the user exits from CAD, or executes the Disconnect command.

Figure 4-1: User Login to Agile

The Server URL field in the Login dialog is set by your system administrator, you would normally not need to change this. Just enter the desired user name and password to log in. Checking the Remember Password box will save your login parameters for future use.

Disconnecting from Agile and closing the Engineering Collaboration ClientYou may disconnect (i.e. Logout) from the EC Client without closing the client window or the CAD system. There are two ways to do this:

Once you are disconnected, you are no longer using an Agile PC license. You may continue to work with your CAD model locally, without being connected to Agile. You may re-connect to Agile at a later time, and it is OK to just leave the EC Client window active, without being connected. To close the EC Client window, use the File > Exit command (from the EC Client window, not from CAD!), or just click the “X” icon in the corner of the window. It is always best to disconnect from Agile before closing the client window.

Using the Engineering Collaboration ClientUser operations that require interaction with Agile are performed using the EC Client, a separate window that runs in combination with the CAD system. Much of the use of the EC Client is controlled by the commands that you run from the Agile menu in your CAD system. For example, picking the Save command will bring the EC Client to the front, and bring up the save dialogs shown in Figure 4-2. These commands will be discussed later in this document, but first it is important to understand the basic functioning of the EC Client.

Table 4-2: Disconnecting methods from the EC Client

Disconnect Method Approach

Logout from EC Client From the EC Client window, pick the Logout icon or the File > Logout… command. (Note that the Login and Logout icons and commands just switch with each other, depending on what state you’re in)

Logout using Agile > Disconnect From within CAD, pick the Agile > Disconnect command


Chapter 4 Using Engineering Collaboration Client

Figure 4-2: EC Client - example of Save dialogs

The EC Client is designed for Agile operations commonly done by Engineers and Designers. Some of the breadth of capability from the standard Agile client has been removed in order to make it simple to use. Standard functions that can be performed from the EC Client include searching data in Agile, and viewing forms of objects such as Documents and Parts.

Table 4-3: Menu functions in the EC Client

Menu Commands

File • Logout (or Login) -Allows you to connect or disconnect from Agile·

• Recent Visits… - Shows a window listing Agile objects recently visited (see “Recent Visits” on page 4-7).

• Exit - Closes the EC Client window

4-3

Agile PLM 9

Figure 4-3: EC Client Menus and Toolbars

❑ Simple Search - The most basic search capability

❑ Load Option - Determines what revisions are loaded from Agile into CAD (see “Loading from Agile” on page 4-10 in the “CAD Connectors for Agile Engineering Collaboration” documentation).

Docking and undocking a window in the EC Client

Using the docking function of the EC Client will dock the window in the tabbed docking area at the bottom of the client window. To initiate the Dock function, right-click in the greyed area of the window header and pick the Dock function.

Figure 4-4: Dock Function

Tools • Quick Search… - Provides basic search capability (see “Quick Search” on page 4-5).

• Advanced Search… - Provide more advanced search capability (see “Advanced Search” on page 4-6).

• Saved Searches… - Displays a list of saved searches (see “Saved Searches” on page 4-6).

Window • This menu provides standard window-management capability. EC Client windows can be cascaded, tiled, docked and undocked.

Help • About Agile EC… - Provides information about the release level of the EC Client

Table 4-3: Menu functions in the EC Client

Menu Commands



The Recent Visits window will now be displayed as an additional tab of the message window.

Figure 4-5: Tabbed docking area

To undock the Recent Visits window (tab), right-click the greyed area of the tab and then click on the Undock function that shows up.

Engineering Collaboration Client - Search

Much of the basic EC Client capability is focused on searching, so that you can find your data in Agile. There are five types of functions geared towards searching, which are Simple Search, Quick Search, Advanced Search, Saved Searches, and Recent Visits. All of these are similar to equivalent capabilities found in the other Agile clients. One main difference is that the EC Client is limited to a sub-set of Agile object types that can be searched. This is configurable by your administrator, but by default consists of Items (including Documents and Parts), File Folders, and Changes. These “EC Objects” are the object types that are used by the CAD Connectors.

A basic overview of the search functions is provided below. However, due to the similarity with standard Agile client capability, please refer to the “Client Handbook” in the User Manuals section of the Agile Documentation Web site for further details (for example, to see the allowable wildcard characters).

Simple Search

To perform a simple search, just type in your search text in the box that initially says “Search Text”, then click the icon to the right, or just hit the Enter key. A results list will appear, which will contain any EC Objects whose Number or Description fields match the search text. See Figure 4-6 for an example.

Figure 4-6: Simple Search

Quick Search

The only difference between Simple Search and Quick Search is that Quick Search allows you to control which of the EC Objects will be searched. There is an additional dialog to set the desired object types, shown in Figure 4-7. The results list generated by the Quick Search looks the same as for Simple Search.

4-5

Agile PLM 9

Figure 4-7: Quick Search Dialog

Advanced Search

The Advanced Search dialog allows you to create more detailed searches, which can better narrow in on the desired search results. For example, Figure 4-8 illustrates a search based on both a Project identifier and the type of CAD system. You can add multiple search criteria, combining them with “And” and “Or” operators. Once you have built an advanced search, you can execute it directly using the Search button, or you can save it using the Save icon at the top. This creates a Saved Search, which is a common way to use the Advanced Search function. See below for more about Saved Searches.

Figure 4-8: Advanced Search

Saved Searches

Saved Searches is an Agile capability which allows you to define useful searches and easily re-execute them. Saved Searches are stored in a tree structure, which is displayed when you pick the Saved Searches menu pick or toolbar icon. See Figure 4-9 for an example of this display.



Figure 4-9: Saved Searches Display

Saved Searches are created using the Advanced Search capability, and then using the Save command. Note that Saved Searches are structured within folders – at the top level there are Global Searches and Personal Searches. If you have the necessary privileges in Agile, you can create saved searches within Global Searches, so that all users may use them. Otherwise you can create Personal Searches for your own use. When you save a search, you will be prompted to identify the folder to put it in. The Saved Searches display window also allows you to create folders, delete searches or folders, and rename searches or folders.

To use a Saved Search, just double-click on the name and it will bring up the corresponding Advanced Search form. Then click Search to see the results.

Since the standard Agile Web and Java clients have somewhat more capability in defining Advanced and Saved Searches, you may want to create your searches in a standard client, and then simply access them from the EC Client. One aspect of this is that in a standard Agile client, you can define which attributes should be visible in the results list. While this cannot be defined in the EC Client, the results will display correctly in the EC Client. In Figure 4-8, the “Project” and “CAD System” attributes were specially chosen to display in the results list.

Recent Visits

If you pick the Recent Visits menu pick or toolbar icon, the Recent Visits window will appear. This window keeps a running list of the 10 most recently visited object in Agile, with the most recent listed first. This enables you to easily get back to objects that you’ve worked with before. This list is updated by both the standard Agile clients, and the EC Client. However, in the EC Client only the objects that you Save or Load are added to the list.

Figure 4-10: Recent Visits

4-7

Agile PLM 9

Agile Forms

Beside searches, the other main basic function of the EC Client is to display forms of Agile objects. From any search results list, or from the Recent Visits list, double-clicking on the name of an object will bring up its Form. This is where you can see the detailed information about an object, including its attributes, relationships, and files. Figure 4-11 shows an example of an Agile Form for a CAD Model, which is a special sub-class of a Document used by the CAD Connectors.

Figure 4-11: New Item Form Capabilities

A. Send button for sending notifications. See Agile PC documentation for details on the operation.

B. Tabs for Pending Changes, Change History, and History.

Note The Pending Changes and Change History tabs are displayed as a single Changes tab in the other clients.

C. The “Send to CAD” button is only displayed while the Load command is in effect. This helps users to understand when they are able to load.

Every object type has its own unique layout, and may be customized at your site. However, it is useful to understand some of the basic layout of these Agile forms. Standard tabs for an Agile Item (a Document or Part) are these:

Table 4-4: Form Tabs

Tab Name Purpose

Title Block Contains primary attributes, such as Number and Description

Page Two Contains supplemental attributes, typically customized

Page Three Contains additional attributes for the specific sub-class, such as CAD Model

BOM Shows the item structure below the current object (looking down the tree) – see Figure 4-12

WhereUsed Shows all items that the current object belongs to (looking up the tree)

Attachments Shows attached files – see Figure 4-13

Pending Changes Displays the changes created on the object that are yet to be released

Change History Displays the changes created on the object that are already released

History Displays history of actions performed on the object



Figure 4-12: BOM Tab

Figure 4-13: Attachments Tab

Tip: The Agile > Show Agile Form command will pop up the EC Client with the form of the active object in CAD.

Table 4-5: Additional Functions

Function Purpose

Revision Selector Selects which revision of the current object to view, or to load into CAD

Load Button When the Agile > Load command is active, this will load the current object (and objects in its structure) into CAD

Add File Allows you to add files to the current object

Site Allows filtering by Site

4-9