| Oracle Agile Engineering Data Management Web Services Guide for Agile Release e6.2.0.0 E52562-01 |
|
 Previous |
 Next |
| Oracle Agile Engineering Data Management Web Services Guide for Agile Release e6.2.0.0 E52562-01 |
|
Previous |
Next |
Agile e6 Web Services are deployed on an Agile e6 WebLogic application domain.
To use the Agile e6 Web Services framework for inbound and outbound Web Services based on business data transaction, you are required to ensure the following:
Operational environment is set:
Agile e6.2.0.0 is installed.
WebLogic Server is installed
Web Services framework is configured for the following:
Authentication provider in WebLogic
Web Service Security
Test the inbound Web Services
You can now call available core services or implement your own outbound Web Service wrappers.
| Agile e6 Application | Release e6.2.0.0 or higher |
|---|---|
| Default Web Services engine | Oracle WebLogic server 12c or higher
Note: The version of this server is the one that is released with the Agile e6 application. |
| Java 2 Platform Standard Edition Development Kit | 7.0 |
All application server vendors, such as Oracle, have built-in Web Services infrastructure solutions that are integrated with their application servers. For non-Web Services integrated applications, there are stand-alone products, such as AXIS from Apache, which provide Web Services infrastructure that can be integrated with different application servers.
The Web Service framework works with WebLogic 12c platforms. Additionally, in a Distributed File Management (DFM) environment, a subset of the Web Service will be available on the DFM client side. In addition to the WebLogic 12c platform, Tomcat or Metro runtime systems can be used as Web Service engines.
Both platforms provide support for MTOM, and for Fileservice operations, the need for MTOM with Streaming SOAP attachments.
The Agile e6 Web Services framework works on the following Web Service engines:
Oracle Apps Server Web Service Infrastructure
Oracle SOA Suite
WebLogic Web Service Infrastructure
Axis version 2.0 to support JAX-WS features, especially the MTOM
The Agile e6 Web Services are implemented in compliance with the following standards:
| Standard | Location |
|---|---|
| Simple Object Access Protocol (SOAP) 1.1/1.2 | http://www.w3.org/TR/2000/NOTE-SOAP-20000508/ |
| Web Service Description Language (WSDL) 1.2 | http://www.w3.org/TR/2001/NOTE-wsdl-20010315 |
| WS-I Basic Profile 1.1 | http://www.ws-i.org/Profiles/BasicProfile-1.1-2004-08-24.html |
| XML Schema 1.1 | http://www.w3.org/XML/Schema |
| SOAP Message Transmission Optimization Mechanism (MTOM) | http://www.w3.org/TR/soap12-mtom/ |
| JAX-WS 2.0/2.1/2.2 (JSR 224) | http://java.sun.com/developer/technicalArticles/J2SE/jax_ws_2/ |
| JAXB 2.0/2.1/2.2 (JSR-222) | http://jaxb.java.net/ |
In the 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 - the standard HTTP session ID maintained by the web container:
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 is placed in the SOAP header of the Web Service reply.
Whenever the sessionID is included by the client in subsequent Web Service requests, this sessionID is used to restore cached session information, thus bypassing the substantially more time consuming process of re-executing the authentication.
|
Note: 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 Web Services security. Using the UserName token as provided in Web Service security, while fully supported as part of Agile e6 WS-I Basic Profile compliance, does not yield the same benefit as using the higher performance session optimization facility provided by the Agile e6 implementation.
|
Note: For information about Web Service single sign-on please refer to the Security Guide for Agile e6.2.0.0 |
Every call of an Agile e6 core Web Service needs an EDM Server instance. It is very important to limit the number of EDM Server instances to reduce the resource loading on the server. This is handled by the following mechanisms:
HTTP Session
First, the Web Service tries to find an EDM Server instance assigned to the HTTP session of the current Web Service call. If it is found, the Web Service call uses the existing EDM Server instance.
PLM Ticket - A PLM ticket is returned in the response of a core Web Service operation. This ticket can be used to access the same EDM Server instance that created the ticket.
While authenticating a Web Service call, if a ticket is passed instead of the password, the session manager uses the EDM Server instance, even if no EDM Server is assigned to the HTTP session.
The PLM ticket mechanism is the only way to let the calls to different core Web Services, such as metadata, or Business Object Web Services use the same EDM Server instance.
A Web Service client must use the PLM ticket as soon as it has called the first operation.
This is the only way to share an Agile e6 session between two different core services.
To free an EDM Server instance assigned to a Web Service session, the client calls one of the closeSession operations (every core Web Service provides this function) with the PLM ticket as the password. This shuts down the EDM Server instance and frees up the server resources.
The Agile e6 PLM Session Manager lets you manage the PLM session objects which are used to keep the existing connections and user contexts to the EDM Server.
The key to an existing PLM session object is the session ID, which is generated by PLM Session Manager.
The PLM session provides connection to EDM Server.
To retrieve a PLM session, a PLM Ticket is provided. When a new PLM Session is created, the PLM Ticket is set to the EDM Server instance, which is then set into the SOAP message to the client side.
The life cycle of a PLM session is the same as the given HTTP session.
Timeout
The configuration parameter "timeout-secs" for the element "session-descriptor" within <weblogic-web-app></weblogic-web-app> tag is used to set the time in seconds before the WebLogic is timing out a session. This value is visible in WebLogic configuration panel. The default value is 3600 seconds. E.g.:
<weblogic-web-app>
<session-descriptor>
<timeout-secs>3600</timeout-secs>
</session-descriptor>
On busy sites, you can tune your application by adjusting the timeout of sessions. While you want to give a browser client every opportunity to finish a session, you do not want to tie up the server needlessly if the user has left the site or otherwise abandoned the session.
This element can be overridden by the session-timeout element defined in minutes in web.xml. E.g.:
<session-config> <session-timeout><time-in-minutes></session-timeout> </session-config>
A Response contains a string that can be used in subsequent calls. This string is called the PLM Ticket. The ticket gives the caller access to the same EDM Server instance that was used in the last request. The ticket remains valid only as long as the EDM Server instance is running. After obtaining a ticket, the client code needs to configure the port by setting the ticket string as password. See BindingProvider in the example given under Authenticating a Web Service Client.
The PLM Ticket improves the Web Services performance and simplifies the session management. If different Web Services are used in a use case flow, which is very likely, the ticket returned by the response(s) of one service operation (e.g. Configuration.setUserContext) is used as a password when the client makes a call for another service operation (e.g. BusinessObject.getObjects).
The ticket sharing among different client ports eliminates the need for the server to start new Agile e6 sessions, which would result in new EDM Servers being started.
In the Agile e6 Web Services framework, each operation has its own request data type, which is inherited from RequestHeaderType. The RequestHeaderType for all the requests has only the following elements:
messageID (String, optional):
Default value for the ID is the current system time in milliseconds.
messageName (String, optional):
Default value for the message name is the simple class name.
You can obtain the basic Agile e6 metadata through Agile e6 Java Client. Look for the data model of the Agile e6 application.
To obtain Agile e6 metadata through a Web Services operation, use the metadata service. This service requires an entity name and a mask name.
For further information see section Configuration Parameter.
The ResponseHeaderType has the following members:
| messageId (String, required) | Default value for the ID is the current system time in milliseconds. |
| messageName (String, required) | Default value for the message name is the simple class name. |
| statusCode (ResponseStatusCode, required) | Default value for the status code is SUCCESS. |
| exceptions (List<PlmExceptionType>, optional): warnings (List<PlmWarningType>, optional) | |
| ticket (String, optional) | |
The response obtained from every Web Service call contains a response statusCode, which indicates the success or failure of a Web Service operation.
These response status codes are of four types:
| SUCCESS | Indicates that all Web Services in the batch were executed successfully and that all operations worked as intended. |
| FAILURE | Indicates that all Web Services in the batch failed during execution, indicating the intended operations were not performed. |
| WARNING | Indicates that while Web Services in the batch were successfully executed, however certain warnings were also encountered during the execution. These warnings need to be analyzed by the client to verify that all operations worked as intended. |
| PARTIAL_SUCCESS | Indicates a partial success in the execution of batch Web Services when one or more but not all batch requests have failed. Even if a single Web Service fails among a batch of Web Services, the response status code indicates PARTIAL_SUCCESS. |
To ensure that only the masks designed for the access of Web Services are used, all the mask names are checked against a Whitelist that is maintained by the administrator of the Agile e6 installation.
|
Note: Please be aware that the configuration parameter EDB-WSI need to be created first. |
A configuration rubric named EDB-WSI-MASKS is used. It contains sub-parameters such as EDB-ARTICLE-WSI and each of these sub-parameters contain a mask name rule pattern. All rules for an entity are checked for an operation that involves an item as an entity (or as parent entity in case of a relation).
|
Caution: It is recommended to implement special masks designed for Web Services, instead of only adding the standard masks like EDB-ART-SLI (or "*") to the Whitelist. |
Adding standard masks can have certain implications due to the following:
Standard masks may expose sensitive data.
To be able to access invisible fields, you are required to make them visible. This must be done as they are not opened to the customer.
Performance suffers as the standard masks contain too many fields.
|
Note: For all fields located on sub-forms that are part of a combined form, the pre-field userexit will not be executed. Thus, we recommend using lists instead of combined forms |
The Configuration Parameters are entered as shown in the image below.
The rule pattern consists of valid mask name characters and may contain one or more asterisks (*) to indicate one or more mask name characters.
The Web Service session reads these configuration rules and checks each combination of entity and mask name passed by a client against the rules for the respective entity. If one of the rules accepts the mask name, access is granted, If not, the access to the mask is denied and an IllegalAccessException is thrown and marshaled back to the client.
The rules are cached by the session so that the subsequent operations do not have the overhead of reading the rules again. The rules can also be cached in the Business Service, this provides a domain wide cache, instead of a session based cache.
The Agile e6 framework throws an exception (WebFault) only if a severe technical problem occurs, for instance, in an event of a connection loss to the EDM Server. When an operation is not successful, the system throws an exception or a warning.
In case of FAILURE, an exception is issued, while a warning may be issued.
In case of WARNING, only a warning is issued.
When the status is WARNING, the outcome of the operation is unknown. You are manually required to check if the operation was successful.
A count request is indicated by the flag countOnly in the query request object. The service then executes a count, which ignores the mask limit, and returns a pseudo PlmObject with a COUNT attribute and a RECORD_LIMIT attribute.
The value of the COUNT attribute is an Integer with the number of objects matching the query, and the value of the RECORD_LIMIT attribute is the record limit of the mask used for the count operation.
