Skip Headers

Agile Product Lifecycle Management Web Services Guide Release 9.3.3 E39310-01 |
| Contents

Previous | Next |

# 1 Introduction to Agile PLM Web Services

Web services are technologies for building distributed applications. These services, which can be made available over the Internet, use a standardized XML messaging system and are not tied to specific operating systems or programming languages. Through web services, companies can encapsulate existing business processes, publish them as services, search for and subscribe to other services, and exchange information throughout and beyond the enterprise. Web services are based on universally agreed-upon specifications for structured data exchange, messaging, discovery of services, interface description, and business process design.A web service makes remote procedure calls across the internet using:HTTP/HTTPS or other protocols to transport requests and responses.Simple Object Access Protocol (SOAP) to communicate request and response information.

Oracle's Agile PLM Web Services use industry standard core technologies.

## 1.1 About Service Oriented Architecture (SOA)

Service Oriented Architecture (SOA) is a business-centric IT architecture for building enterprise applications through adaptable and re-usable business processes and services. Each service implements one action such as creating a product record, viewing a BOM table, or updating the Price and Compliance data.

Leading companies are gaining operational efficiencies and business agility through adaptable, re-usable business processes and services built on truly flexible Service-Oriented Architecture (SOA) platforms.

The guiding principles of SOA are:

- Self-contained and loosely-coupled

- Well-defined standards-based interfaces

- Right-sized interfaces

- Location-independent and inter-operable in a standards-based manner

- Implementation agnostic

One SOA implementation is the web services approach where the basic unit of communication is a message, rather than an operation. This is often referred to as "message-oriented" services. Web services make functional building-blocks that are accessible over standard internet protocols and independent of platforms and programming languages. SOA is gaining wide customer adoption because of its reliance on standards-based protocols and enabling rapid development of applications using web services. SOA and web services are supported by most major software vendors.

## 1.2 Web Services - Benefits

The key benefits provided by web services are:

- Service-Oriented Architecture (SOA) - Unlike packaged products, web services can be delivered as streams of services that allow access from any platform. Components can be isolated; only the business-level services need be exposed.

- Interoperability - Web services ensure complete interoperability between systems.

- Integration - Web services facilitate flexible integration solutions, particularly if you are connecting applications on different platforms or written in different languages.

- Modularity - Web services offer a modular approach to programming. Each business function in an application can be exposed as a separate Web service. Smaller modules reduce errors and result in more reusable components.

- Accessibility - Business services can be completely decentralized. They can be distributed over the internet and accessed by a wide variety of communications devices.

- Efficiency - Web services constructed from applications meant for internal use can be used externally without changing code. Incremental development using web services is relatively simple because web services are declared and implemented in a human readable format.

### 1.2.1 Core Technologies

Each core technology listed below is explained in detail in the topics that follow.

- Web Services Description Language on page 2

- XML and XML Schema on page 3

- Simple Object Access Protocol on page 3

#### 1.2.1.1 Web Services Description Language

Web Services Description Language (WSDL) is an XML-based format for describing the interface of a Web service. A WSDL file describes the endpoints, location, protocol binding, operations, parameters, and data types of all aspects of a Web service:

- The WSDL file that describes a Web service has the following characteristics:

  - It is published by the service provider.

  - It is used by the client to format requests and interpret responses.

  - It can be optionally submitted to a registry or service broker to advertise a service.

- Additionally, it also describes:

  - The operations that are provided by a Web service

  - The input and output message structures for each Web service operation

  - The mechanism to contact the Web service.

#### 1.2.1.2 XML and XML Schema

A WSDL file is published as an XML file. Document/Literal formatting is required as part of the WS-I interoperability standard. This standard sets the basis for modern Web service usage.

- Document - The payload for an operation, however complex, must be defined in a single XML element.

- Literal - The definition of a single XML element must be described by an XML Schema embedded in the WSDL file.

When using Document/Literal formatting, the WSDL file will contain an XML Schema definition that defines all messages and data types that are used for a particular service. The XML Schema offers an automated mechanism for validating the XML documents. The payload itself will consist entirely of XML data structures.

#### 1.2.1.3 Simple Object Access Protocol

Simple Object Access Protocol (SOAP) is a lightweight protocol intended for exchanging structured information in a decentralized, distributed environment. SOAP uses XML to define an extensible messaging framework.

SOAP messages consist of the following:

- An envelope for wrapping messages, including addressing and security information

- A set of serialized rules for encoding data types in XML

- Conventions for a procedure call and/or response.

### 1.2.2 Web Services Architecture

You can view Web services architecture in terms of roles and the protocol stack:

- Web services roles:

  - Service provider - This provides the service by implementing it and making it available on the Internet.

  - Service requester - This is the user of the service who accesses the service by opening a network connection and sending an XML request.

  - Service registry - This is a centralized directory of services where developers can publish new services or find existing ones.

- Web services protocol stack:

  - Service transport layer - This layer uses the HTTP protocol to transport messages between applications.

  - XML messaging layer - This layer encodes messages in XML format using SOAP to exchange information between computers. It defines an envelope specification for encapsulated data that is transferred, the data encoding rules, and remote procedure call (RPC) conventions.

  - Service description layer - This layer describes the public interface to a specific Web service using the WSDL protocol. With WSDL, it defines an XML grammar to describe network services. The operations and messages are described abstractly, and then bound to a network protocol and message format. WSDL allows description of endpoints and their messages regardless of what message formats or network protocols are used to communicate.

  - Service discovery layer - This layer centralizes services into a common registry using the Universal Description, Discovery, and Integration (UDDI) protocol. UDDI is a platform-independent, XML-based registry for businesses worldwide to list themselves on the Internet.

## 1.3 About Agile PLM Web Services

Implementation of Agile PLM Web Services adheres to the following principles:

- Well defined standards based discoverable Interface

- XML based Web Service Framework - Apache Axis 1.4

- Modularized PLM Schema (XSD) and WSDL for easy maintenance

- Standards-based WSDL to ensure compatibility across various clients (.NET, and Java, and BPEL)

- Batch APIs wherever applicable for better performance

- Web Service versioning for backward compatibility

Agile PLM Web Services exposes all key PLM functionalities in the following services.

- Agile PLM Core Web Services - These services support functionalities provided by PLM solutions such as PC, PQM, PCM, PPM, PG&C. See Core Operations - Agile PLM Web Services on page 135.

- Agile PLM EC Web Services - These services support functionalities provided by Agile PLM's Engineering Services (EC) solution.I

### 1.3.1 Agile PLM Core Web Services

Agile PLM Core Web Services are a set of services for the following PLM functionalities:

- Business Object CRUD (Create, Read, Update, Delete) data services

- Collaboration services

- Meta data Services

- Search Services

- Attachment Services

- Table Services

### 1.3.2 Agile PLM EC Services

Agile PLM Engineering Collaboration (EC) Services are a set of business services that supplement PLM's Core Web Services for CAD use cases. Customers and partners can build next generation MCAD and ECAD connectors utilizing Agile PLM Web Services and Engineering Collaboration Services.

Some of the benefits are:

- Significantly improves WAN performance for CAD connectors because the bulk of the logic is deployed to the server

- Makes it easier for development partners and customers to implement CAD connectors

- Provides the unique and interface friendly API name field to access PLM metadata.

### 1.3.3 Agile Recipe & Material Workspace Web Services

The Recipe & Material Workspace module in Agile application caters to the needs product lifecycle management of the pharmaceutical development industry. It is made up of several dimensions such as Recipe (Instructions), Equipment, Material, Analytical (Test and Assays), Environment, Standards and People. These dimensions enable drug manufacturers to conduct the preparation, execution and analysis necessary during the scale-up life cycle of a substance across multiple pilot plants, located in disparate geographic locations. It also helps scale up material production in a systematic and reproducible manner.

The RMW Web Services are a set of business services that supplement Agile PLM's Core Web Services for Pharmaceutical industry use cases. They also offer a set of higher level BPEL orchestration services. Customers and partners can build next generation applications to carry out business object processing, searches and data editing.

### 1.3.4 Agile PLM Web Service Authentication and Performance

In implementations where scalability is critical, a lightweight context management facility for authentication is available and its use is recommended. With this facility, authentication is managed using a combination of user credentials and a sessionID token:

- When user credentials are presented in the SOAP header of a Web service request, formal authentication is performed prior to the application execution of the Web service operation. If the authentication succeeds, the operation proceeds and a special SessionID token are placed in the SOAP header of the Web service reply.

- Whenever the sessionID is included by the client in subsequent Web service requests, that sessionID will be used to restore cached session information, thus bypassing the substantially more expensive process of re-executing the authentication. Note that, when presented with both the sessionID and a valid set of user credentials, an attempt will be made to use the sessionID before resorting to the user credentials and re-authentication. As expected, the session that is being tracked by the sessionID is subject to expiration and other security checks.

The facility is a distinct alternative to the basic authentication standard described by WS-Security. Using the UserName token as provided in WS-Security, while fully supported as part of Agile PLM's WSI Basic Profile compliance, will not yield the same benefit as using the higher-performance session optimization facility provided by the Agile PLM implementation.

### 1.3.5 Impact on Existing Agile PLM Extensions and Services

Agile PLM provides tools and process extensions to customize the Agile PLM to meet unique user requirements, provide access to external databases, extend automation capabilities, and develop UI extensions. These tools and services are listed below. Agile PLM Web Services implementation has no impact on these capabilities; they are in addition to the existing services.

- Agile SDK - The SDK is a set of Java APIs that enable building custom applications to access or extend the Agile PLM server functionalities. For information, refer to Agile PLM SDK Developer Guide.

- Agile Integration Services (AIS) - AIS is a collection of predefined Web Services in the Agile Integration framework that enable communication between PLM server and disparate database. For information, refer to Agile PLM AIS Developer Guide.

- Agile Content Services (ACS) - ACS is a process for transferring data to other Agile PLM solutions or to any other external system. For information, refer to Agile PLM ACS User Guide.

- Process Extensions (PX) - PX is a framework for extending the functionalities of the Agile PLM system. The functionality can be server-side extensions such as custom automations, or client-side functionality such as new commands added to the Java/Web Client's Actions or Tools menus. For information, refer to Agile PLM SDK Developer Guide.

- Web Service Extensions (WSX) - WSX is a Web service engine that enables communication between Agile PLM and internal and external systems. For information, refer to Agile PLM SDK Developer Guide.

- Dashboard Management Extensions (DX) - Similar to PX, DX extends the functionalities of the Agile PLM system. For information, refer to Agile PLM SDK Developer Guide.

## 1.4 Casual User Interface Integration Examples

Agile Web Client and Agile Java Client are targeted towards those who use the more complex product lifecycle management features of Agile PLM on a daily basis to perform assigned tasks and duties. There is also another set of users who use the auxiliary capabilities of Agile PLM to perform lightweight tasks such as document management, importing compliance and price data, or approving ECO and Sales RFQ.

The tools of choice for these users are the popular desktop products provided by Microsoft Office or Adobe Acrobat, Mobile devices. They prefer simple user-friendly interfaces, for example:

- Microsoft Word and Acrobat for document management

- Microsoft Excel to import price and compliance data

- Oracle WebCenter and Oracle Application Development Framework (ADF) for simple document management tasks

- Oracle WebCenter and ADF for simple item management tasks

- Mobile devices to access sales RFQ

- Mobile devices to access ECO Approval

- Microsoft Sharepoint for simple document management tasks

### 1.4.1 User Interface Integration - MS Word

This example demonstrates document management capabilities of PLM's Web Services. Currently, when casual users want to view or update a document in Agile PLM, they do so by logging in to the Web Client to retrieve and view the Word document. The steps are:

1. Log in to PLM Client

2. Search and locate the document

3. Check out the document (in Word)

4. Modify the documents (in Word)

5. Check in the document

6. Log out

Using Agile PLM's Web Services, the casual user directly accesses Agile PLM documents from MS Word. This simple UI encourages and accelerates greater user participation. Agile PLM is transparent to this class of users which eliminates training and exposure in PLM Web Client.

### 1.4.2 User Interface Integration - MS Excel

This is similar to MS - Word integration. In this case, the casual user is one of your partners and suppliers. Using PLM's Web Services, you can provide a simple UI in Excel template for suppliers and partners. Then when necessary, suppliers import information such as compliance and price data directly into PLM system from Excel. Benefits include greater and more convenient supplier participation in the PLM process with no training in Agile PLM Web Client.

### 1.4.3 User Interface Integration - Portals and Agile Web Client

Before PLM Web Services, the practice was to create custom Web applications using Agile PLM SDK with various tools and technologies. With Web Services, you can build rich Web applications in Oracle Web Center (and ADF) by taking advantage of Web 2.0 UI and mobile services.

Once you develop the custom UI Web application for casual users, you can also integrate the custom UI with Agile Web Client using Agile PLM's URL Process Extensions (refer to Agile PLM SDK Developer Guide) and Smart URL features.

### 1.4.4 User Interface Integration - Mobile ADF

One of the key demands in Agile PLM installations is mobile access for management and executive personnel. One such example is ECO Approval by the senior or management staff using mobile devices. PLM's Web Services enable developing simple ECO Approval applications for users of mobile devices.

The following illustrations depict a sales RFQ implementation from a sales manager's perspective:

Using the mobile device's browser, the sales manager launches the Mobile application built using Agile Web Services. The first screen is the Search RFQ screen. The second is the RFQ Details screen and the third, the Send RFQ screen.

### 1.4.5 CAD Integration through EC Services

Customers and partners can build next generation MCAD and ECAD connectors with the aid of Agile PLM Core and Engineering Collaboration Web Services. The benefits are summarized in Agile PLM EC Services on page 4.

Some of the EC services are orchestrated using Business Process Execution Language (BPEL). BPEL, short for Web Services Business Process Execution Language, is an executable language for specifying interactions with web services. Processes in Business Process Execution Language export and import information by using web service interfaces exclusively.

The CAD integration and the role of BPEL server is shown in the following illustration.

## 1.5 Building Casual User Interfaces

The following paragraphs describe the tools and the steps in developing some the UI integration examples in MS Office and Oracle Web Center (and ADF) environments.

### 1.5.1 Developing User Interfaces for MS Office

Microsoft supports building UI integration interfaces by providing the Microsoft Office Add-in (a piece of code) for this purpose. MS Office Add-in supports integration at application level and document level.

To develop the MS Word Add-in with PLM, the following tools and applications are necessary:

- Application software

  - Microsoft Visual Studio 2005/2008

  - Dot NET framework 3.5

  - Agile PLM (v9.3 or above) server

  - Microsoft Word 2003/2007

- Programming languages

  - C#

  - Visual Basic for .NET

  - Microsoft Visual C++/ATL

- Plug-in templates

  - Shared Add-in Extensibility template

Note: The Shared Add-in Extensibility templates are used to deploy a single add-in onto multiple Microsoft Office applications (common add-ins across Word, Excel, and other office applications). This Add-in is always installed only at the application-level.

- Office 2003/2007 Add-in template

Steps in developing an MS Office Add-in:

1. Evaluate Add-in type: application level versus document level

2. Evaluate programming language: C#, Visual Basic

3. Create a project in Microsoft Visual Studio 2005/2008

4. Generate the C#/Visual Basic Stubs from Agile WSDL

   For information on Stubs, see Generating and Initializing the Stubs on page 14.

5. Create Windows Forms

6. Bind data to UI controls

   - Populate documents with data from Agile Web Services

7. Build & test the Add-in

8. Deploy the Add-in

9. Extend Agile 9.3.3 samples to fit your business needs:

   - MS Word Document Management - Application Level Add-In

   - MS Excel - Import BOM/Price/ Compliance - document Level Add-in

   Note: The source code for these two MS Office Add-ins is available for download from Oracle Technology Network (OTN) Web site `http://www.oracle.com/technetwork/documentation/agile-085940.html`. A good source of information for developing an MS Office Add-in is the MSDN forum.

### 1.5.2 Developing User Interfaces for Oracle WebCenter and ADF

This section provides basic information to develop the following UIs in Oracle Web Center and ADF environments.

- Document Management UI in Oracle WebCenter (and ADF 10g)

- Item Management UI in Oracle WebCenter (and ADF 11g)

- Sales RFQ UI in Mobile device

- ECO Approval UI in Mobile device

You need the following tools and applications to develop the Oracle WebCenter (and ADF) with PLM:

- Software

  - Oracle jDeveloper 10g/11g

  - Agile PLM (v9.3.3 or above) server

- Programming Languages

  - Java

Steps in developing ADF applications

1. Create a Project in jDeveloper

2. Generate the Java Stubs from Agile WSDL

3. Map XML schema to Java Classes

4. Create UI forms

5. Create page flow

6. Bind data to UI controls

7. Build and test the applications

8. Deploy the applications

9. Extend Agile 9.3.3 samples to meet business needs:

   - Document management

   - Item management

   - Sales RFQ

For information on Oracle Web Center, ADF, and jDeveloper, visit Oracle website at: `http://www.oracle.com/technology/products/webcenter/index.html` and `http://www.oracle.com/technology/products/adf/index.html`