| Agile Product Lifecycle Management Web Services Guide Release 9.3.6 E71166-01 |
|
 Previous |
 Next |
| Agile Product Lifecycle Management Web Services Guide Release 9.3.6 E71166-01 |
|
Previous |
Next |
A web service makes remote procedure calls across the internet using:
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.
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.
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.
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.
Each core technology listed below is explained in detail in the topics that follow.
Web Services Description Language
XML and XML Schema
Simple Object Access Protocol
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:
Operations that are provided by a Web service
Input and output message structures for each Web service operation
Mechanism to contact the Web service.
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.
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.
You can view Web services architecture in terms of roles and the protocol stack:
Web services roles:
Service provider - Provides the service by implementing it and making it available on the Internet.
Service requester - User of the service who accesses the service by opening a network connection and sends an XML request.
Service registry - 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 the message formats or network protocols that you use 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.
Implementation of Agile PLM Web Services adheres to the following principles:
Well defined standards based discoverable Interface
XML based Web Service Framework - JAX - WS
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 Appendix A, "Core Operations - Agile PLM Web Services.".
Agile PLM EC Web Services - These services support functionalities provided by Agile PLM's Engineering Services (EC) solution.
For added security, the following services can now be SAML-enabled:
AIS Web Services
Core Web Services
File Manager Web Services
Variant Management Web Services
Engineering Collaboration Web Services
Web Service Extensions
Agile PLM Core Web Services are a set of services for the following PLM functionalities:
Product Collaboration
Product Governance and Compliance
Project
User Profile
DocPublishing
Folder & Report Services
Business Object CRUD (Create, Read, Update, Delete) data services
Collaboration services
Meta data Services
Search Services
Attachment Services
Table Services
Engineering Collaboration 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 perform business object processing, searches and data editing.
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 HTTP header of a Web service request, formal authentication is performedbefore executing the application 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. It is recommended to use Basic Auth over SSL.
Agile PLM provides tools and process extensions to customize the application to meet unique user requirements, provide access to external databases, extend automation capabilities, and develop UI extensions. Listed below are tools and services; 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 application. 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 application. For information, refer to Agile PLM SDK Developer Guide.
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, like the following:
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.
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:
Log in to PLM Client.
Search and locate the document.
Check out the document (in Word).
Modify the documents (in Word).
Check in the document.
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.
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. 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.
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.
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.
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 the Appendix B, "Operations - EC Web Services."
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.
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: Using the Shared Add-in Extensibility templates, you can 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 to develop MS Office Add-in:
Evaluate Add-in type: application level versus document level.
Evaluate programming language: C#, Visual Basic.
Create a project in Microsoft Visual Studio 2005/2008.
Generate the C#/Visual Basic Stubs from Agile WSDL.
Create Windows Forms.
Bind data to UI controls.
Populate documents with data from Agile Web Services.
Build & test the Add-in.
Deploy the Add-in.
Extend Agile 9.3.6 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 the Oracle Technology Network (OTN) Web sitehttp://www.oracle.com/technetwork/indexes/samplecode/agileplm-sample-520945.html. A good source of information for developing an MS Office Add-in is the MSDN forum. |
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.6 or above) server.
Programming Languages.
Java
Steps to develop ADF applications:
Create a Project in jDeveloper.
Generate the Java Stubs from Agile WSDL.
Map XML schema to Java Classes.
Create UI forms.
Create page flow.
Bind data to UI controls.
Build and test the applications.
Deploy the applications.
Extend Agile 9.3.6 samples to meet business needs:
Document management.
Item management.
Sales RFQ.
For information on Oracle Web Center, ADF, and jDeveloper, visit the Oracle website at: http://www.oracle.com/technology/products/webcenter/index.html and http://www.oracle.com/technology/products/adf/index.html
SAML (Security Assertion Markup Language) is an XML-based method for securing web services communication. It is an open standard for exchanging authentication and authorization data between security domains. It establishes the identity of the requester (authentication) and checks the access privileges of the requester (authorization), who needs access to a protected resource. For details on how to set up and configure SAML, refer to the Agile PLM Security Guide.
Updated Project web services support additional functionality, including project summary export, calendar and timesheet management.
The web services platform is replaced with Weblogic web services using JAX-WS framework. The new framework allows for web services to be deployed on Agile Application Server. For more details, see: "WSDL and XSD Changes."
The impact of the framework changes and actions required are listed below:
Any Web Services Extension (WSX) needs to be updated to use JAX-WS. Code impact is limited to packaging, not the core logic of the WSX. For detailed instructions, see the Agile PLM SDK Developer Guide - Developing PLM Extensions.
Client samples provided now use JAX-WS. For instructions on how to build the sample web services clients with the JAX-WS framework, see "Getting Started with Agile Web Services."
Pre-existing clients connecting to Agile PLM Web Services will not be directly impacted by the change to the Web Services framework. Clients must uptake changes to WSDL and XSD.
For AXIS clients, there are WSDL changes which are not supported anymore. SAML connections require additional libraries. If you need to leverage changed functionality or SAML, it is recommended that you update clients to also leverage JAX-WS. As with WSX, changes are limited to packaging.
The jaxws:binding is required to control the output package of generated service interface. The enableAsyncMapping enables async method generation in the endpoint interface generated from a WSDL. If absent, the default value of enableAsyncMapping is False. The enableWrapperStyle is used to disable wrapper style Java method generation. If absent, the default value of enableWrapperStyle is True.
| OOTB WSDL Module | WSDL Change | XML Schema Change | Summary of the Changes |
|---|---|---|---|
| Core Services | Yes | Yes | Add Embedded jaxws:binding in WSDL.
Add Embedded jaxb:binding in XSD. Use MTOM policy in Attachment.wsdl. |
| EC services | Yes | Yes | Add Embedded jaxws:binding in WSDL.
Add Embedded jaxb:binding in XSD. |
| AIS | Yes | No | Soap encode is not supported. |
| ACS | Yes | No | Soap encode is not supported. |
| AIA | No | No | NA |
| V M Magmt | No | No | NA |
| Reference Object | No | Yes | NA |
| File Server | No | No | NA |
Example:
<jaxws:bindings xmlns:jaxws="http://java.sun.com/xml/ns/jaxws" >
<jaxws:package name="com.agile.ws.service.xxxservice.v1.jaxws"/>
<jaxws:enableWrapperStyle>true</jaxws:enableWrapperStyle>
<jaxws:enableWrapperStyle>true</jaxws:enableWrapperStyle>
</jaxws:bindings>
Impacted WSD Files:
BusinessObject.wsdl
Search.wsdl
Attachment.wsdl
Folder.wsdl
PGC.wsdl
TableService.wsdl
AdminMetadataService.wsdl
CollaborationService.wsdl
ReportService.wsdl
DocPulishingService.wsdl
UserProfile.wsdl
Project.wsdl
PC.wsdl
ECServices.wsdl
Example:
<xsd:annotation>
<xsd:appinfo>
<jaxb:schemaBindings>
<jaxb:package name="com.agile.ws.schema.xxxservice.v1.jaxws"/>
</jaxb:schemaBindings>
</xsd:appinfo>
</xsd:annotation>
Impacted XSD Files:
AttachmentSchema.xsd
BusinessObjectSchema.xsd
CollaborationSchema.xsd
AgileCommonSchema.xsd
DocPublishingSchema.xsd
ECServicesSchema.xsd
FolderSchema.xsd
AdminMetadata.xsd
PCSchema.xsd
PGCSchema.xsd
ProjectSchema.xsd
ReportSchema.xsd
SearchSchema.xsd
TableSchema.xsd
UserProfileSchema.xsd
Example:
<xsd:annotation>
<xsd:appinfo>
<jaxb:globalBindings generateElementProperty="false"/>
<jaxb:schemaBindings>
<jaxb:package name="com.agile.ws.schema.common.v1.jaxws"/>
</jaxb:schemaBindings>
</xsd:appinfo>
</xsd:annotation>
Impacted XSD Files:
AgileCommonSchema.xsd
Example:
<wsdl:definitions.
targetNamespace="http://www.agile.com/ais/import".
xmlns:ais="http://www.agile.com/ais"
xmlns:apachesoap="http://xml.apache.org/xml-soap"
xmlns:imp90="http://www.agile.com/2003/04/ais/import"
<schema.targetNamespace="http://www.agile.com/ais/import".xmlns="http:w3.org/2001/XMLSchema">
<import.namespace="http://www.agile.com/2003/04/ais/import"/>
<import.namespace="http://www.apache.org/xml-soap"/>
<import.namespace="http://www.agile.com/ais"/>
<import.namespace="http://www.agile.com/2004/01/ais/import"/>
<import.namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
<element.name="validateDataReturn".type="apachesoap:DataHandler"/>
<element.name="importDataReturn".type="apachesoap:DataHandler"/>
<element.name="importSupplierResponseReturn".type="apachesoap:DataHandler"/>
</schema>
Impacted WSDL/XSD Files:
importer.wsdl
importcontent.wsdl
export.wsdl
AcsStatusService.wsdl
PackageService.wsdl
ResponseService.wsdl
Example:
<definitions.name="AttachmentService"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap"
xmlns: attachment="http://xmlns.oracle.com/AgilleObjects/Core/Attachment/V1"
xmlns:tns="http://xmlns.oracle.com/AgileServices/Core/Attachment/V1"
targetNamespace="http://xmlns.oracle.com/AgileServices/Core/Attachment/V1"
xmlns:wssutil="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:wsp="http://www.w3.org/ns/ws-policy".xmlns:wsp1_2="http://schemas.xmlsoap.org/ws/2004/09/policy">
<wsp:UsingPolicy.wssutil:Required="true"/>
<wsp1_2:Policy.wssutil:Id="Mtom.xml">
<ns1:OptimizedMimeSerialization.xmlns:ns1="http://schemas.xmlsoap.org/ws/2004/09/policy/optmizedserialization"/>
</wsp1_2:Policy>
<wsp:Policy.wssutil:Id="AttachmentService_MTOM_Policy">
<ns2:OptimizedMimeSerialization.xmlns:ns2="http://schemas.xmlsoap.org/ws/2004/09/policy/optmizedserialization".wsp:Optional="true"/>
</wsp:Policy>
<jaxws:bindings.xmlns:jaxws="http://java.sun.com/xml/ns/jaxws".
<jaxws:package.name="com.agile.ws.service.attachment.v1.jaxws"/>
<jaxws:enableWrapperStyle>true</jaxws:enableWrapperStyle>
<jaxws:enableAsyncMapping>false</jaxws:enableAsyncMapping>
</jaxws:bindings>
<documentation>Web-service.to.handle.operations.related.to.document.management</documentation>.
<binding.name="Attachment Binding".type="tns:Attachment PortType">
<wsp:PolicyReference.URI="#AttachmentService_MTOM_Policy"/>
<wsp:PolicyReference.URI="#Mtom.xml"/>
<soap:binding.transport="http://schemas.xmlsoap.org/soap/http".style="document"/>
Impacted WSDL Files:
Attachment.wsdl
Import.erwsdl
Export.wsdl
Package.wsdl
