Various Oracle E-Business Suite application interface definitions shipped with Oracle Integration repository are referred as native integration interfaces. This chapter describes the steps to transform these interface definitions into SOAP web services or REST web services.
An Oracle E-Business Suite user who has the Integration Repository Administrator role can perform administrative tasks in managing service lifecycle activities and as well as managing security grants.
To better understand how to administer and manage both SOAP and REST services, the following topics are included in this chapter:
Interfaces Supported for SOAP Service Enablement
Oracle E-Business Suite Integrated SOA Gateway supports the following interface types for SOAP-based service enablement:
PL/SQL
XML Gateway Map (Inbound)
Note: The service for XML Gateway Map can be enabled by both Web Service Provider in release 12.0 and SOA Provider in this release. For backward compatibility, a profile option 'FND: XML Gateway Map Service Provider' is used to let you select an appropriate service provider in enabling services for XML Gateway Map interface type. For more information on service enablement for XML Gateway Map, see XML Gateway Map Web Service Region, Oracle E-Business Suite Integrated SOA Gateway User's Guide.
Concurrent Program
Important: Oracle Integration Repository supports REST service enablement for Open Interface Tables and Views. If a concurrent program is associated with an open interface table or view, this concurrent program can be viewed and displayed under the Open Interface type and can be available as a REST service.
Business Service Object
Note that Java APIs for Forms web services are desupported in Oracle E-Business Suite Release 12.2. If you are planning to use this type of interfaces as web services, you are advised to use alternate serviceable interfaces, such as PL/SQL and Business Service Objects interfaces, which can be deployed as web services. Refer to My Oracle Support Knowledge Document 966982.1 for the suggested alternatives to the existing Java APIs for Forms services.
Managing SOAP Service Lifecycle Activities
Only integration repository administrators (defined by the Integration Repository Administrator role) can perform the following administrative tasks in managing each state of SOAP services throughout the entire service life cycle:
Service Generation and Deployment Process Flow
Oracle Integration Repository provides a capability of transforming interface definitions to a machine-processable format that complies with web standards using WSDL. Once the WSDL file is generated successfully, an appropriate Web Service region becomes visible in the interface details page for XML Gateway interface.
For interfaces with the support for both REST and SOAP services, service generation is managed in the SOAP Web Service tab of the interface details page.
Deploying, Undeploying, and Redeploying SOAP Web Services
Integration repository administrators can further deploy the generated SOAP service to Oracle Application Server.
If the SOAP service is successfully deployed, the administrators can undeploy the service if the service is no longer required for integration, or redeploy the service if needed.
Subscribing to Business Events
This task allows the administrators to subscribe to selected business events and create subscriptions for the selected events.
This allows the administrators to create security grants by authorizing the access permission for a selected interface method, or a procedure or function to an appropriate user, a user group, or all users.
Viewing Generate and Deploy Time Logs for SOAP Services
This allows the administrators to view and download the logs recorded during service generation and deployment for specific services or all services that have the logging enabled at the Site level only.
Note that the administrators can also manage SOAP service lifecycle activities and create security grants using manual steps, see:
Managing SOAP Service Lifecycle Activities Using Manual Steps
This allows the administrators to generate SOAP services and perform postclone activities through backend scripts.
Managing Security Grants Using an Ant Script
This allows the administrators to create security grants through a backend script.
Managing Other Administrative Tasks for SOAP Services
Some administrative tasks are performed outside the Integration Repository user interface. These tasks are performed in the Administration tab, next to the Integration Repository tab. The Administration tab is specifically for the administrators to perform additional administrative tasks outside the Integration Repository user interface. This tab contains the following administrative and management features:
Note: All Integration Repository Administration functions are grouped under Integration Repository Administrator permission set (FND_REP_ADMIN_PERM_SET) and performed by the users with the Integration Repository Administrator role.
For more information about the Integration Repository Administrator permission set, see Role-Based Access Control (RBAC) Security.
SOA Monitor: The SOA Monitor subtab allows the administrators to monitor and audit all SOAP messages in and out through SOA Provider and view the message details.
For information about how to use SOA Monitor, see Monitoring and Managing SOAP Messages Using SOA Monitor.
Log Configuration: The Log subtab allows the administrators to configure and manage log setups.
For information about log configuration, see Logging for Web Services.
Oracle E-Business Suite Integrated SOA Gateway allows users who have the Integration Repository Administrator role to transform interface definitions to SOAP services.
To accomplish this goal, these interface definitions will be transformed to a machine-processable format that complies with web standards using Web Services Description Language (WSDL). The WSDL code contains operations or messages that can be bound to a concrete network protocol and message format to define web services.
Generating SOAP Services
For interfaces with the support for SOAP services only, such as XML Gateway maps, service activities are managed in the Web Service region. Click Generate WSDL to generate the service for a selected interface. Once the SOAP service is generated, service deployment activities are managed in the appropriate Web Service region.
Note: A composite service consists of multiple native services which have WSDL files generated already; therefore, there is no service generation button shown in the composite service details page.
XML Gateway Interface Details Page with "Generate WSDL" Button Highlighted
For interfaces with the support for both REST and SOAP services, such as PL/SQL, Concurrent Programs, and Business Service Objects, service generation and deployment activities are managed in the SOAP Web Service tab of the interface details page.
To generate the SOAP service for a selected interface, click Generate (or Generate WSDL for a Business Service Object) in the SOAP Web Service tab.
SOAP Web Service Tab with "Generate" Button Highlighted
After SOAP Service Generation
For XML Gateway interfaces with the support for SOAP services only, once the SOAP service of a selected XML Gateway interface has been successfully generated, the Web Service region appears.
Note: For XML Gateway Map interface type, you might find more than one Web Service Region available. See: Generating Web Service Region(s) for XML Gateway Map Interfaces.
For interfaces with the support for both SOAP and REST services, service generation information appears in the SOAP Web Service tab. For example, "Generated" is shown as the SOAP Service Status field in the SOAP Web Service tab.
Web Service Status (or SOAP Service Status): After a service has been generated successfully, the service status is changed from 'Not Generated' to 'Generated'.
Important: Multiple requests to generate services for an integration interface are not allowed. While a web service is getting generated, the status of the service is changed to 'Generating' and the Generate WSDL or Generate button is disabled.
View WSDL link: Click this link to view the generated WSDL code.
For more information about WSDL, see: Reviewing Web Service WSDL Source, Oracle E-Business Suite Integrated SOA Gateway User's Guide.
Authentication Type: Prior to deploying the generated service, an integration repository administrator must select at least one authentication type for the selected interface. The selected authentication type(s) will be used by SOA Provider to authenticate the users who want to access the generated SOAP service throughout the service deployment cycle.
The supported authentication types are Username Token and SAML Token (Sender Vouches). For more information, see Deploying and Undeploying Web Services.
The Deploy Button: This button appears allowing you to deploy the generated service.
Note: Composite services such as BPEL files are typically not deployed within Oracle E-Business Suite like other service enabled interface types. Instead, you need a separate BPEL PM (SOA Suite or third party BPEL PM server) to deploy the BPEL composite services. Therefore, you will not be able to find Deploy in the composite service details page.
For more information, see Deploying and Undeploying SOAP Web Services.
Regenerating the SOAP Service If the Definition is Changed
If the interface definition is changed, the administrators need to regenerate the service from the Interface Details page by clicking Regenerate WSDL in the appropriate Web Service region or Regenerate in the SOAP Web Service tab. Upon regeneration, the service definition will also change to reflect the modification in the interface. The administrators will have to modify its web service clients based on the new service definition.
If interface definition is not changed, then regenerating the service would not change the service definition. The administrators can continue to use the existing web service clients, if any, with the new service definition.
Generating Web Service Region(s) for XML Gateway Map Interfaces
In supporting the Web Service Provider-based and SOA Provider-based service enablement for XML Gateway Map, if a SOAP service is successfully generated, depending on the profile value set in the FND: XML Gateway Map Service Provider profile option, you can find one of the following Web Service regions displayed in the XML Gateway interface details page:
Web Service - Web Service Provider region
In Release 12.0, XML Gateway Map interface type is deployed by default through Web Service Provider. The administrators can find both the standard WSDL URL (http://<hostname>:<port>/webservices/AppsWSProvider/oracle/apps/fnd/XMLGateway?wsdl
) and deployed ones available in this region.
Web Service - SOA Provider region (default)
The administrators will find a WSDL file along with Deploy, Undeploy, or Redeploy.
Important: If you do not start from this release and your system is upgraded from Oracle E-Business Suite Release 12.0, then the default value should be set to 'Both' (Web Service Provider and SOA Provider). This is because Web Service Provider could have already been used in enabling services for XML Gateway Maps in the Release 12.0. To continue to support service enablement in this release using SOA Provider and to support backward compatibility, both service providers should be enabled in transforming XML Gateway Map interface definitions into web services. The Web Service - Web Service Provider region and the Web Service - SOA Provider region can both be displayed simultaneously in the interface details page if web services are available.
If you start with this release, then the default value remains the same which is SOAP (SOA Provider). Therefore, the Web Service Provider that generates the generic XML Gateway web services should be disabled at runtime.
Both the Web Service - Web Service Provider region and Web Service - SOA Provider region
To generate a web service:
Log in to Oracle E-Business Suite as a user who has the Integration Repository Administrator role. Select the Integrated SOA Gateway responsibility and the Integration Repository link.
In the Integration Repository tab, select 'Interface Type' from the View By drop-down list.
Expand an interface type node to locate your desired interface definition.
Click the interface definition name link to open the interface details page.
To generate a SOAP service for a selected interface:
If the selected interface is an XML Gateway map that can be exposed as a SOAP service only, click Generate WSDL to generate the service. Once the SOAP service is successfully generated, an appropriate Web Service region becomes available. The Web Service Status field marked as 'Generated' also appears which indicates that this selected interface has WSDL description available.
If the selected interface can be exposed as both REST and SOAP services, click Generate in the SOAP Web Service tab to generate the service.
Click the View WSDL link to view the WSDL description.
Click Regenerate WSDL or Regenerate in the SOAP Web Service tab or Web Service region to regenerate the WSDL description if necessary.
If a SOAP service has been generated successfully, the administrator has the privilege to deploy the generated service in the appropriate Web Service region or the SOAP Web Service tab if the interface can be exposed as both SOAP and REST services.
Interface Details Page with SOAP Web Service Tab
Note: Unlike native services that they are deployed through the Web Service region of an interface type detail page, composite services are typically not deployed within Oracle E-Business Suite like those of other service enabled interface types. You need a separate BPEL PM (SOA Suite or third party BPEL PM server) to deploy the BPEL composite services. For example, a composite service - BPEL type can be deployed through Oracle JDeveloper to a BPEL server in Oracle SOA Suite BPEL PM (Process Manager) or a third party BPEL PM in a J2EE environment. This deployed composite service - BPEL project can update Oracle Applications if necessary.
Deploying Web Services with Authentication Types
To secure web service content, Oracle E-Business Suite Integrated SOA Gateway supports multiple authentication types for inbound service requests. Prior to deploying or redeploying a SOAP service generated, an integration repository administrator must first select at least one of the following authentication types:
Username Token
This authentication type provides username and password information in the security header for a web service provider to use in authenticating the users who request the Oracle E-Business Suite services. It is the concept of Oracle E-Business Suite username/password (or the username/password created through the Users window in defining an application user).
SAML Token (Sender Vouches)
This authentication type is used for web services relying on sending a username only through SAML Assertion.
After you identify the preferred authentication type(s) for a web service, clicking the Deploy button deploys the web service with selected authentication type(s) from Oracle Integration Repository to Oracle Application Server. When SOA Provider receives inbound SOAP requests, the web service framework will authenticate the user who sends the SOAP request message based on the specified authentication type(s).
If no authentication type is identified for the service, then an validation error occurs requesting you to select an appropriate authentication type.
Once the web service has been successfully deployed, the Web Service Status field is changed to from "Generated" to "Deployed", along with selected authentication type check box(es). This indicates that the selected service has been successfully deployed to the application server.
For more information on supported authentication types for web service security, see Managing Web Service Security.
Reviewing Deployed WSDL
Once the web service has been successfully deployed, click the View WSDL link to view the deployed web service WSDL description. The following example shows the deployed WSDL code:
<?xml version="1.0"encoding="UTF-8" ?> <definitions name="FNDWF_MOVE_MSGS_EXCEP2NORMAL" targetNamespace="http://xmlns.oracle.com/apps/owf/soaprovider/concurrentprogram/fndwf_move_msgs_excep2normal/" xmlns:tns="http://xmlns.oracle.com/apps/owf/soaprovider/concurrentprogram/fndwf_move_msgs_excep2normal/" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns1="http://xmlns.oracle.com/apps/owf/soaprovider/concurrentprogram/fndwf_move_msgs_excep2normal/"> <types> <schema xmlns="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="http://xmlns.oracle.com/apps/owf/soaprovider/concurrentprogram/fndwf_move_msgs_excep2normal/"> <include schemaLocation="http://<hostname>:<port>/webservices/SOAProvider/concurrentprogram/fndwf_move_msgs_excep2normal/APPS_ISG_CP_REQUEST_CP_SUBMIT.xsd" /> </schema> <schema xmlns="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="http://xmlns.oracle.com/apps/owf/soaprovider/concurrentprogram/fndwf_move_msgs_excep2normal/"> <element name="SOAHeader"> <complexType> <sequence> <element name=="Responsibility" minOccurs="0" type="string"/> <element name="RespApplication" minOccurs="0" type="string"/> <element name="SecurityGroup" minOccurs="0" type="string" /> <element name="NLSLanguage" minOccurs="0" type="string" /> <element name="Org_Id" minOccurs="0" type="string" /> </sequence> </complexType> </element> </schema> </types> . . .
Additionally, the following buttons are available in the Web Service region or the SOAP Web Service tab if the interface can be exposed as both SOAP and REST services:
Redeploy: It allows the administrator to redeploy the deployed web service for the following reasons:
The service was regenerated from a new interface definition.
The original service was corrupt.
The Authentication Type field was modified for a deployed service.
Click Redeploy to update the deployed service with the current system values.
Undeploy: It allows the administrator to undeploy the web service from Oracle Application Server back to Oracle Integration Repository if necessary.
Any previously selected authentication type(s) for a service will be deselected by default.
If the administrator undeploys a native service that is not used, Oracle Integration Repository will undeploy the native service from the server.
Note: The Deploy and Redeploy buttons appear only for users who have the Integration Repository Administrator role.
To deploy, undeploy, redeploy a web service:
Log in to Oracle E-Business Suite as a user who has the Integration Repository Administrator role. Select the Integrated SOA Gateway responsibility and the Integration Repository link.
In the Integration Repository tab, select 'Interface Type' from the View By drop-down list.
Expand an interface type node to locate your desired interface definition.
Click the interface definition name link to open the interface details page.
From the SOAP Web Service tab (or Web Service region for XML Gateway interface type), select at least one of the following authentication type check boxes:
Username Token
SAML Token (Sender Vouches)
Click Deploy to deploy the service from Oracle Integration Repository to Oracle Application Server.
Note: If this selected interface definition has never been generated as a web service, generate the service first and then deploy it. For information on how to generate a SOAP service, see Generating SOAP Web Services.
Click the deployed View WSDL link to view the deployed WSDL description.
Redeploy the service if needed by clicking Redeploy.
Note: If changes are made to the Authentication Type field for a deployed web service, you must redeploy the service.
Click Undeploy to undeploy the service if necessary.
Subscribing to Business Events
For business events, users who have the Integration Repository Administrator role can find Subscribe available in the interface details page which allows the administrators to subscribe to selected business events and create subscriptions for the selected events.
Business Event Details Page
Clicking the Subscribe button lets you subscribe to the selected business event. Internally, an event subscription is automatically created for that event with WF_BPEL_QAGENT
as Out Agent. Once the event subscription has been successfully created, a confirmation message appears on the Business Event interface detail page.
To consume the business event message, you should register to dequeue the event from Advanced Queue WF_BPEL_Q
. If a business event is enabled and if there is at least one subscriber registered to listen to WF_BPEL_Q
, then the event message will be enqueued in WF_EVENT_T
structure to Advanced Queue WF_BPEL_Q
.
Unsubscribing to Business Events
The Unsubscribe button becomes available in the business event details page if the selected event has been subscribed. Clicking the Unsubscribe button removes the event subscription from WF_BPEL_Q
queue. A confirmation message also appears after the subscription has been successfully removed.
For more information on how to dequeue messages, see the Oracle Streams Advanced Queuing User's Guide and Reference.
To subscribe to a business event:
Log in to Oracle E-Business Suite as a user who has the Integration Repository Administrator role. Select the Integrated SOA Gateway responsibility and the Integration Repository link.
In the Integration Repository tab, select 'Interface Type' from the View By drop-down list.
Expand the Business Event interface type node to locate your desired event.
Click the business event interface that you want to subscribe to it to open the Interface details page for the event.
Click Subscribe to subscribe to the selected event. Internally, an event subscription is created with Out Agent as WF_BPEL_QAGENT
. A confirmation message appears after the event subscription is successfully created.
To remove the subscribed event, click Unsubscribe to remove or delete the event subscription if needed.
By leveraging Oracle User Management function security and data security, Oracle E-Business Suite Integrated SOA Gateway provides a security mechanism which only allows users who have authorized privileges to access or execute certain API methods exposed through Oracle Integration Repository. This protects application data from unauthorized access without security checks.
In this release, XML Gateway (inbound) is the only interface type that can be exposed as SOAP services only. To manage user security for XML Gateway interfaces, you need to log in to Oracle XML Gateway user interface. See Managing XML Gateway User Security in the Trading Partner User Setup Form.
Note: For interfaces that can be exposed as REST services, security grants are managed in the Grants tab of the selected interface details page. For example, PL/SQL APIs, Concurrent Programs, and Business Service Objects can be exposed as both SOAP and REST services; Java Bean Services, Application Module Services, Open Interface Tables, and Open Interface Views can be exposed as REST services only.
Note that when a method access permission is authorized to a grantee, if the selected method can be exposed as both SOAP and REST service operations, then this grants the permission to the associated SOAP and REST services simultaneously. For information on managing security grants in the Grants tab, see Managing Security Grants for SOAP and REST Web Services.
Managing XML Gateway User Security in the Trading Partner User Setup Form
For XML Gateway interfaces, user security is managed in the Oracle XML Gateway user interface through the Trading Partner User Setup form where the administrator needs to associate users with a trading partner. Only these authorized users can perform XML Gateway inbound transactions with the trading partner. Specifically, the administrator needs to:
Set the "ECX: Enable User Check for Trading Partner" profile option to "Yes" to enable the trading partner specific security feature
Associate users with a trading partner
Log in to Oracle E-Business Suite as a user who has the XML Gateway responsibility. Navigate to Setup and then select Define Trading Partners from the navigation menu. In the Define Trading Partner Setup form, click the User Setup button to access the Trading Partner User Setup form.
For more information about trading partner user security, refer to Trading Partner Setup, XML Gateway Setup chapter, Oracle XML Gateway User's Guide.
To effectively troubleshoot any issues or exceptions encountered at design time during service generation and deployment, error messages and service activity information can be logged and viewed through the Interface Details page if logging is enabled for specific services or all services at the Site level only. Administrators can find View Log displayed in the Interface Details page.
Note: Logging is supported for SOAP services only.
Note that if logging is enabled for 'All Services' at the Site level, then View Log will be shown in the Interface Details page for all interfaces that can be service enabled. If the logging is enabled at the Site level for specific operations, then there will be no log generated and you will not find View Log in the Interface Details page. Generate and Deploy time log is only available if logging is enabled for specific services or all services at the Site level.
Note: You will not find View Log available in the Interface Details page for a given service if the logging is enabled at the user level. Only site level logging configuration with specific services or all services will have the Generate and Deploy time logs captured.
For information on how to configure logging at the site level for enabling specific services, see Enabling Logging at the Service Level.
SOAP Web Service Tab with 'View Log' Highlighted
Click View Log to open the Log Details page. All logs recorded for the selected service are listed in the table. Each log contains log sequence, log timestamp, module, log level, and actual message recorded at the design time.
Note: Generate and Deploy time logs might be present for a service that has the logging enabled at the site level even if no error occurs while generating (regenerating) and deploying (redeploying or undeploying) the service. For example, if log setup is done at the log level of Statement, then statement level log messages can be written and listed in the log table.
Log Details Page
Deleting and Exporting Logs Listed in the Log Details Page
After viewing log messages retrieved for a service in the Log Details page, you can delete them if needed by clicking Delete All. A warning message appears alerting you that this will permanently delete all the logs retrieved in the page. Click Yes to confirm the action. An empty log table appears in the page after logs are successfully deleted.
Before deleting the logs, you can save a backup copy by clicking Export. This allows you to export the records listed in the Log Details page to Microsoft Excel and save them to a designated directory and use it later.
For more logging information, see Logging for Web Services. For information on how to add a new log configuration, see Adding a New Log Configuration.
At runtime during the invocation of Oracle E-Business Suite services by web service clients, if a service has the logging enabled, log messages can be viewed in SOA Monitor against that instance. For information on viewing log messages through SOA Monitor, see Viewing Service Processing Logs.
To view Generate and Deploy time log messages:
Log in to Oracle E-Business Suite as a user who has the Integration Repository Administrator role. Select the Integrated SOA Gateway responsibility and the Integration Repository link.
In the Integration Repository tab, select 'Interface Type' from the View By drop-down list.
Expand an interface type node to locate your desired interface definition.
Click the interface definition name link to open the interface details page.
If logs are available for this selected service that has logging enabled properly, you will find View Log available in the interface details page.
Click View Log to open the Log Details page where you can view the log details.
Click Delete All to delete all the logs listed in the table if needed. Click Yes to confirm the action. Click No to return back to the Log Details page.
Click Export to export log list table to Microsoft Excel and save the records.
In addition to supporting SOAP-based service generation and deployment, Oracle E-Business Suite Integrated SOA Gateway allows supported interface types to become REST-based services. REST services can be used for user-driven applications such as mobile, tablet, or handheld devices. In this release, PL/SQL APIs, Concurrent Programs, and Business Service Objects can be exposed as both SOAP and REST services; Java Bean Services and Application Module Services, Open Interface Tables, and Open Interface Views can be exposed as REST services only.
Note: Security services are also REST services; however, unlike other service-enabled interfaces, they are predefined and predeployed REST services from Oracle Application Object Library. This type of services provides security related features for mobile applications. See: Supporting Security Services - Predeployed REST Services.
REST Service Life Cycle
The administrator can perform the following tasks in the REST Web Service tab to manage the REST service life cycle:
Deploy a Service
A supported interface can be exposed as a REST service through a 'Deploy' action. This deploys a REST service to an Oracle E-Business Suite application server.
Undeploy a Service
The administrator can undeploy a deployed REST service. This action not only undeploys the REST service, but also resets the service to its initial state - 'Not Deployed'. Any existing or running service requests will be completed and no new request is honored.
Note that the administrator can also manage these REST service activities through manual steps. See: Managing REST Service Lifecycle Activities Using Manual Steps.
The administrator can manage security grants in the Grants tab of the interface details page or through a backend script. It assigns grants to specific users to access or invoke the deployed REST services. For information on managing security grants using a script, see Managing Security Grants Using An Ant Script.
Supporting Security Services - Predeployed REST Services
In addition to exposing a supported interface as a REST service, Oracle E-Business Suite Integrated SOA Gateway supports Oracle Application Object Library's Authentication and Authorization services as REST security services. Security services are used for mobile applications to validate or invalidate user credentials, initialize user sessions with applications context, and authorize users.
Unlike other service-enabled interfaces requiring administrative actions on service development, security services are a set of predeployed REST services which can be invoked by all the Oracle E-Business Suite users.
Security services support token based authentication for invoking other REST services. With token based authentication, it is possible to authenticate a user once based on username and password, and then authenticate the user in the consecutive REST requests using a security token (such as Oracle E-Business Suite user session ID). For more information about the REST service security, see REST Service Security.
To better understand each administrative task, the following topics are included in this section:
Oracle E-Business Suite Integrated SOA Gateway allows the administrator to deploy interface definitions as REST services. These interfaces are PL/SQL APIs, Concurrent Programs, Business Service Objects, Java Bean Services, Application Module Services, Open Interface Tables, and Open Interface Views. Among these interfaces, only PL/SQL APIs, Concurrent Programs, and Business Service Objects can be exposed as both SOAP and REST services.
Interface Details Page with REST Web Service Tab
Deploying REST Services in the REST Web Service Tab
Before deploying a REST service, the administrator must perform the following tasks:
Specify Service Alias
Each REST service should be associated with a unique alias name. Alias is a set of characters and is used in the service endpoint which shortens the URL for the service.
For example, 'Invoice' is entered as the service alias for an interface Create Invoice (AR_INVOICE_API_PUB) before being deployed. The alias will be displayed as the service endpoint in the WADL and schema for a selected service operation CREATE_INVOICE as follows:
href="https://<hostname>:<port>/webservices/rest/Invoice/?XSD=CREATE_INVOICE_SYNCH_TYPEDEF.xsd" />
Guidelines for Entering Service Alias
Use simple and meaningful name to represent the service, such as "person", "employee", and so on.
Do not use "rest", "soap", and "webservices" as the alias.
Do not start with a number or a special character, such as #
, $
, %
, _
, -
and more.
Do not end with a special character.
Characters such as .
, _
, and -
are allowed in a service alias.
Select Desired HTTP Verbs for Java Bean Services, Application Module Services, Business Service Objects, Open Interface Tables, and Open Interface Views
For Java Bean Services, Application Module Services, Business Service Objects, Open Interface Tables, and Open Interface Views, in addition to selecting desired methods to be exposed as REST service operations, the administrator needs to select HTTP method check boxes for the desired methods.
The following table lists the interfaces that can be exposed as REST services and their supported HTTP methods:
Interface Type | Supported HTTP Method(s) |
---|---|
PL/SQL API | POST only |
Concurrent Program | POST only |
Business Service Object | POST and GET |
Java Bean Service | POST and GET |
Application Module Service | POST and GET |
Open Interface Table (Inbound) | POST, GET, PUT, and DELETE |
Open Interface Table (Outbound) | GET only |
Open Interface View | GET only |
Note: PL/SQL APIs and Concurrent Programs can be exposed as REST services with the POST HTTP method only; therefore, there is no need to further specify the HTTP method for these two interface types.
For Java Bean Services and Application Module Services
REST Web Service Tab for Application Module Services
If the Java or Application Module method is annotated (rep:httpverb
) with a specific HTTP method, then the corresponding HTTP method check box is preselected for that method in the table.
If the GET
HTTP method is not annotated, then the GET
check box becomes inactive or disabled for further selection. This means that the Java or Application Module method will never be deployed as a REST service operation with the GET
method.
If the POST
HTTP method is not annotated, unlike the GET
method, the POST
check box is still active or enabled by default. This allows the administrator to select the POST
check box if needed for the Java or Application Module method as a REST service operation before deploying the service.
For example, if "Add Grant" method within the "REST Service Locator" is annotated only with the POST
HTTP method, then the POST
method check box is preselected for the method. The GET
method check box that is not annotated for the "Add Grant" method is shown as inactive or disabled which cannot be chosen for that method before deploying the service.
The administrator can modify the desired HTTP methods before deploying the REST service. For example, uncheck the preselected POST
check box if the "Add Grant" method will not be exposed as a REST service operation with the POST
method.
For information about the rep:httpverb
annotation, see rep:httpverb, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide. For more Java Bean Services annotation guidelines, see Annotations for Java Bean Services, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.
For more Application Module Services annotation guidelines, see Annotations for Application Module Services, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.
For example, if "Add Grant" method within the "REST Service Locator" Java Bean Service is annotated only with the POST HTTP method, then the POST method check box is preselected for the method. The GET method check box that is not annotated for the "Add Grant" method is shown as inactive or disabled which cannot be chosen for that method before deploying the service.
The administrator can modify the desired HTTP methods before deploying the REST service. For example, uncheck the preselected POST check box if the "Add Grant" method will not be exposed as a REST service operation with the POST method.
For information about the rep:httpverb
annotation, see rep:httpverb, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide. For more Java Bean Services annotation guidelines, see Annotations for Java Bean Services, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.
For more Application Module Services annotation guidelines, see Annotations for Application Module Services, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.
For Business Service Object
REST Web Service Tab for Business Service Objects with GET and POST Methods
A Business Service Object interface can be exposed as a REST service operation with the support of the GET and POST methods.
The GET check box is enabled only if input parameters of the selected interface are of simple data types (String, Number, etc.). The check box is disabled if input parameters consist of complex data object types (AccountMergeRequest, etc.).
There is no annotation required for enabling or using the GET and POST methods.
The administrator can select desired methods for an operation before deploying the Business Service Object interface as a REST service.
For Open Interface Tables and Open Interface Views
For open interface tables, the supported HTTP methods are determined by the direction of the open interfaces.
REST Web Service Tab for Open Interface Table
An open interface table with Inbound
direction
All four HTTP methods (GET
, POST
, PUT
, and DELETE
) are available for selection.
GET
- It reads or selects one or more records from the open interface table or view.
POST
- It creates or inserts one or more records to the open interface table.
PUT
- It updates or edits one or more records in the open interface table.
DELETE
- It deletes or removes one or more records from the open interface table.
An additional method called SUBMIT_CP_<internal name of the associated concurrent program>
appears as the last entry of the method table with the POST
HTTP method only.
Please note that open interface is a combination of a concurrent program and associated open interface tables. Therefore, all these components including each open interface table and the concurrent program contained in a selected open interface table should be service enabled if desired. You can submit the associated concurrent program through this SUBMIT_CP POST
service operation which is internally mapped to the "process" method of the associated concurrent program.
An open interface table with Outbound
direction
For open interface tables with Outbound
direction, only the GET
method is supported.
For open interface views which are always with Outbound
direction, only the GET
method is supported.
REST Web Service Tab for Open Interface View
All REST services are secured by HTTP Basic Authentication or Token Based Authentication at HTTP or HTTPS transport level. Either one of the authentication methods will be used in authenticating users who invoke the REST services.
HTTP Basic Authentication: This authentication is for an HTTP client application to provide username and password when making a REST request that is typically over HTTPS.
Token Based Authentication: This security method authenticates a user using a security token provided by the server. When a user tries to log on to a server, a token (such as Oracle E-Business Suite session ID) may be sent as Cookie
in HTTP header. This authentication method can be used in multiple consecutive REST invocations.
For example, an Oracle E-Business Suite user has been initially authenticated on a given username and password. After successful login, the security Login service creates an Oracle E-Business Suite user session and returns the session ID. The session ID that points to the user session will be passed to HTTP headers of all subsequent web service calls for user authentication.
Note: Login service validates the user credentials and returns an access token. It is a predeployed Java security service, and is part of the Authentication services that help validate and invalidate users, as well as initialize applications context required by the service before being invoked.
For more information on applications context in REST service, see REST Header for Applications Context, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.
For more information on supported authentication types, see Managing Web Service Security.
Click Deploy to deploy the selected service operations to an Oracle E-Business Suite application server for consumption.
After Service Deployment
Once the REST service has been successfully deployed, the REST Web Service tab has the following changes:
Service Alias: The REST alias should be displayed as a read-only text field.
REST Service Status: This field is changed from its initial state 'Not Deployed' to 'Deployed' indicating that the deployed service is ready to be invoked and to accept new requests.
View WADL: The View WADL link is displayed. Click the link to display the deployed WADL information.
It shows the physical location of the service endpoint where the service is hosted.
Verb (PL/SQL APIs and Concurrent Programs Only): This field appears only if the selected interface is a PL/SQL API or concurrent program.
'POST' appears by default because it is the only supported HTTP method for PL/SQL APIs and Concurrent Programs.
Service Operations: This table displays the list of methods (or procedures and functions) contained in the selected interface.
If the selected interface is a PL/SQL API or concurrent program, then the Included Operations column will be checked for all the methods contained in the selected interface.
By default, all methods in a PL/SQL API appear with the POST HTTP method. A concurrent program contains only one method which also appears with the POST method.
If the selected interface is an interface type of Business Service Objects, Java Bean Services, or Application Module Services, then the GET and POST columns will be displayed with the included operation marks indicating which HTTP methods have been used to assist the REST service operations.
If the selected interface is an open interface table with Inbound direction, then all four HTTP methods (GET
, POST
, PUT
, and DELETE
) will appear with the included operation marks indicating which HTTP methods have been used to assist the REST service operations.
If the selected interface is an open interface table with Outbound direction or an open interface view, then only the GET
column will appear with the included operation marks for the methods that have been exposed as REST service operations.
Click the Grant icon to view the read-only grant details for a selected method.
Reviewing Deployed WADL
To view the deployed REST service WADL, click the View WADL link.
The following example shows the deployed WADL for the selected CREATE_INVOICE service operation contained in the PL/SQL API Invoice Creation (AR_INVOICE_API_PUB
):
Note: Note that 'Invoice' highlighted here is the service alias entered earlier prior to the service deployment. After the service is deployed, the specified alias name (Invoice) becomes part of the service endpoint in the .xsd schema file.
<?xml version="1.0" encoding="UTF-8" standalone="no" ?> <application xmlns:tns="http://xmlns.oracle.com/apps/ar/soaprovider/plsql/rest/ar_invoice_api_pub/" xmlns="http://wadl.dev.java.net/2009/02" xmlns:tns1="http://xmlns.oracle.com/apps/ar/rest/ar/create_invoice/" name="AR_INVOICE_API_PUB" targetNamespace="http://xmlns.oracle.com/apps/ar/soaprovider/plsql/rest/ar_invoice_api_pub/"> <grammars> <include xmlns="http://www.w3.org/2001/XMLSchema" href="https://host01.example.com :1234/webservices/rest/Invoice/?XSD=CREATE_INVOICE_SYNCH_TYPEDEF.xsd" /> </grammars> <resources base="http://host01.example.com:1234/webservices/rest/Invoice/"> <resource path="/create_invoice/"> <method id="CREATE_INVOICE" name="POST"> <request> <representation mediaType="application/xml" type="tns1:InputParameters" /> <representation mediaType="application/json" type="tns1:InputParameters" /> </request> <response> <representation mediaType="application/xml" type="tns1:OutputParameters" /> <representation mediaType="application/json" type="tns1:OutputParameters" /> </response> </method> </resource> </resources> </application>
If the deployed REST service is an interface type of Java Bean Services or Application Module Services, then both GET and POST can be shown as the supported methods. For example, the following WADL description shows two Java methods contained in the Employee Information service. The getAllReports
operation is implemented with the GET method, and the getPersonInfo
operation is implemented with both the POST and GET HTTP methods.
<xml version="1.0" encoding="UTF-8"> <application name="EmployeeInfo" targetNamespace="http://xmlns.oracle.com/apps/per/soaprovider/pojo/employeeinfo/" xmlns:tns="http://xmlns.oracle.com/apps/per/soaprovider/pojo/employeeinfo/" xmlns="http://wadl.dev.java.net/2009/02" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:tns1="http://xmlns.oracle.com/apps/fnd/rest/empinfo/getallreports/" xmlns:tns2="http://xmlns.oracle.com/apps/fnd/rest/empinfo/getdirectreports/" xmlns:tns3="http://xmlns.oracle.com/apps/fnd/rest/empinfo/getpersoninfo/"> <grammars> ... </grammars> <resources base="http://<hostname>:<port>/webservices/rest/empinfo/"> <resource path="/getAllReports/"> <method id="getAllReports" name="GET"> <request> <param name="ctx_responsibility" type="xsd:string" style="query" required="false" /> <param name="ctx_respapplication" type="xsd:string" style="query" required="false" /> <param name="ctx_securitygroup" type="xsd:string" style="query" required="false" /> <param name="ctx_nlslanguage" type="xsd:string" style="query" required="false" /> <param name="ctx_orgid" type="xsd:int" style="query" required="false" /> </request> <response> <representation mediaType="application/xml" type="tns1:getAllReports_Output" /> <representation mediaType="application/json" type="tns1:getAllReports_Output" /> </response> </method> </resource> ... <resource path="="/getPersonInfo/ {personId}/"> <param name="personId" style="template" required="true" type="xsd:int" /> <method id="getPersonInfo" name="GET"> <request> <param name="ctx_responsibility" type="xsd:string" style="query" required="false" /> <param name="ctx_respapplication" type="xsd:string" style="query" required="false" /> <param name="ctx_securitygroup" type="xsd:string" style="query" required="false" /> <param name="ctx_nlslanguage" type="xsd:string" style="query" required="false" /> <param name="ctx_orgid" type="xsd:int" style="query" required="false" /> </request> <response> <representation mediaType="application/xml" type="tns3:getPersonInfo_Output" /> <representation mediaType="application/json" type="tns3:getPersonInfo_Output" /> </response> </method> </resource> <resource path="/getPersonInfo/"> <method id="getPersonInfo" name="POST"> <request> <representation mediaType="application/xml" type="tns3:getPersonInfo_Input" /> <representation mediaType="application/xml" type="tns3:getPersonInfo_Output" /> </request> <response> <representation mediaType="application/xml" type="tns3:getPersonInfo_Input" /> <representation mediaType="application/xml" type="tns3:getPersonInfo_Output" /> </response> </method> </resource> </resource path> </application>
If the deployed REST service is an open interface table with Inbound direction, then the service operation table displays all four HTTP methods. In the following WADL example for the AR Autoinvoice
open interface table (associated concurrent program internal name RAXMTR
), the RA_INTERFACE_LINES_ALL
operation is implemented with all four HTTP methods, and the associated concurrent program SUBMIT_CP_RAXMTR
is implemented with the POST method.
Each open interface table name contained in the selected open interface "AR Autoinvoice" is shown in one resource entry (<resource path>
) with the selected HTTP method(s). For example, table name RA_INTERFACE_LINES_ALL
in this example is shown with four selected methods (GET
, POST
, PUT
, and DELETE
) in one resource entry, and the associated concurrent program SUBMIT_CP_RAXMTR
with POST
is contained in another resource entry.
For the GET
and DELETE
methods, application context values, including Responsibility, Responsibility Application, Security Group, NLS Language, and Organization ID complex types, are passed as query strings in the RESTHeader element.
<?xml version = '1.0' encoding = 'UTF-8'?> <application name="RAXMTR" targetNamespace="http://xmlns.oracle.com/apps/ar/rest/autoinvoice" xmlns="http://wadl.dev.java.net/2009/02" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:tns1="http://xmlns.oracle.com/apps/ar/rest/autoinvoice/RA_INTERFACE_LINES_ALL"> <grammars> <include href="http://<hostname>:<port>/webservices/rest/autoinvoice/?XSD=RA_INTERFACE_LINES_ALL_post.xsd" xmlns="http://www.w3.org/2001/XMLSchema"/> <include href="http://<hostname>:<port>/webservices/rest/autoinvoice/?XSD=RA_INTERFACE_LINES_ALL_get.xsd" xmlns="http://www.w3.org/2001/XMLSchema"/> <include href="http://<hostname>:<port>/webservices/rest/autoinvoice/?XSD=RA_INTERFACE_LINES_ALL_put.xsd" xmlns="http://www.w3.org/2001/XMLSchema"/> <include href="http://<hostname>:<port>/webservices/rest/autoinvoice/?XSD=RA_INTERFACE_LINES_ALL_delete.xsd" xmlns="http://www.w3.org/2001/XMLSchema"/> <include href="http://<hostname>:<port>/webservices/rest/autoinvoice/?XSD=SUBMIT_CP_RAXMTR_post.xsd" xmlns="http://www.w3.org/2001/XMLSchema"/> </grammars> <resources base="http://<hostname>:<port>/webservices/rest/autoinvoice/"> <resource path="RA_INTERFACE_LINES_ALL/"> <method id="RA_INTERFACE_LINES_ALL_get" name="GET"> <request> <param name="ctx_responsibility" type="xsd:string" style="query" required="false"/> <param name="ctx_respapplication" type="xsd:string" style="query" required="false" /> <param name="ctx_securitygroup" type="xsd:string" style="query" required="false" /> <param name="ctx_nlslanguage" type="xsd:string" style="query" required="false" /> <param name="ctx_orgid" type="xsd:int" style="query" required="false" /> <param name="select" type="xsd:string" style="query" required="false"/> <param name="filter" type="xsd:string" style="query" required="false"/> <param name="sort" type="xsd:string" style="query" required="false"/> <param name="offset" type="xsd:string" style="query" required="false"/> <param name="limit" type="xsd:string" style="query" required="false"/> </request> <response> <representation mediaType="application/xml" type="tns1:RA_INTERFACE_LINES_ALL_Output"/> <representation mediaType="application/json" type="tns1:RA_INTERFACE_LINES_ALL_Output" /> <representation mediaType="text/csv" type="tns1:RA_INTERFACE_LINES_ALL_Output"/> </response> </method> <method id="RA_INTERFACE_LINES_ALL_post" name="POST"> <request> <representation mediaType="application/xml" type="tns1:RA_INTERFACE_LINES_ALL_Input"/> <representation mediaType="application/json" type="tns1:RA_INTERFACE_LINES_ALL_Input" /> <representation mediaType="text/csv" type="tns1:RA_INTERFACE_LINES_ALL_Input"/> </request> <response> <representation mediaType="application/xml" type="tns1:RA_INTERFACE_LINES_ALL_Output"/> <representation mediaType="application/json" type="tns1:RA_INTERFACE_LINES_ALL_Output" /> <representation mediaType="text/csv" type="tns1:RA_INTERFACE_LINES_ALL_Output"/> </response> </method> <method id="RA_INTERFACE_LINES_ALL_put" name="PUT"> <request> <representation mediaType="application/xml" type="tns1:RA_INTERFACE_LINES_ALL_Input"/> <representation mediaType="application/json" type="tns1:RA_INTERFACE_LINES_ALL_Input" /> <representation mediaType="text/csv" type="tns1:RA_INTERFACE_LINES_ALL_Input"/> </request> <response> <representation mediaType="application/xml" type="tns1:RA_INTERFACE_LINES_ALL_Output"/> <representation mediaType="application/json" type="tns1:RA_INTERFACE_LINES_ALL_Output" /> <representation mediaType="text/csv" type="tns1:RA_INTERFACE_LINES_ALL_Output"/> </response> </method> <method id="RA_INTERFACE_LINES_ALL_delete" name="DELETE"> <request> <param name="ctx_responsibility" type="xsd:string" style="query" required="false"/> <param name="ctx_respapplication" type="xsd:string" style="query" required="false" /> <param name="ctx_securitygroup" type="xsd:string" style="query" required="false" /> <param name="ctx_nlslanguage" type="xsd:string" style="query" required="false" /> <param name="ctx_orgid" type="xsd:int" style="query" required="false" /> <param name="filter" type="xsd:string" style="query" required="false"/> </request> <response> <representation mediaType="application/xml" type="tns1:RA_INTERFACE_LINES_ALL_Output"/> <representation mediaType="application/json" type="tns1:RA_INTERFACE_LINES_ALL_Output" /> <representation mediaType="text/csv" type="tns1:RA_INTERFACE_LINES_ALL_Output"/> </response> </method> </resource> <resource path="SUBMIT_CP_RAXMTR/"> <method id="SUBMIT_CP_RAXMTR_post" name="POST"> <request> <representation mediaType="application/xml" type="tns1:SUBMIT_CP_RAXMTR_Input"/> <representation mediaType="application/json" type="tns1:SUBMIT_CP_RAXMTR_Input" /> <representation mediaType="text/csv" type="tns1:SUBMIT_CP_RAXMTR_Input"/> </request> <response> <representation mediaType="application/xml" type="tns1:SUBMIT_CP_RAXMTR_Output"/> <representation mediaType="application/json" type="tns1:SUBMIT_CP_RAXMTR_Output" /> <representation mediaType="text/csv" type="tns1:SUBMIT_CP_RAXMTR_Output"/> </response> </resource> </resources> </application>
For more information about WADL description, see Reviewing WADL Element Details, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.
To deploy a REST web service:
Log in to Oracle E-Business Suite as a user who has the Integration Repository Administrator role. Select the Integrated SOA Gateway responsibility and the Integration Repository link.
In the Integration Repository tab, select 'Interface Type' from the View By drop-down list.
Expand an interface type node to locate your desired interface definition.
Click the interface definition name link to open the interface details page.
In the REST Web Service tab, specify service alias information.
If the selected interface is an interface type of Business Service Objects, Java Bean Services, Application Module Services, Open Interface Tables, or Open Interface Views, select the desired HTTP method check boxes for the desired methods to be exposed as REST service operations.
Click Deploy to deploy the service to an Oracle E-Business Suite environment.
Click the deployed View WADL link to view the deployed WADL description.
Once a REST service has been successfully deployed, the Undeploy button appears in the REST Web Service tab. This allows the administrator to undeploy the service and at the same time to bring the service back to its initial state - "Not Deployed".
Interface Details Page with a Deployed REST Service
Note that when a service is undeployed, any existing or running service requests will be completed and no new request is honored. The associated service artifact will be removed from the system.
After a successful undeployment, "Not Deployed" is shown in the REST Service Status field. The value of the service alias entered earlier now disappears which allows the administrator to enter it again before next deployment.
To undeploy a REST service:
Log in to Oracle E-Business Suite as a user who has the Integration Repository Administrator role. Select the Integrated SOA Gateway responsibility and the Integration Repository link.
In the Integration Repository tab, select "Interface Type" from the View By drop-down list.
Expand an interface type node to locate your desired interface definition.
Click the interface definition name link to open the interface details page.
In the REST Web Service tab, click Undeploy to undeploy the service.
Users who have the Integration Repository Administrator role can create grants to a specific user, users, or a group of users. Grants given to a user for specific services or operations are applicable for both SOAP and REST services.
Note: In this release, only PL/SQL APIs, Concurrent Programs, and Business Service Objects can be exposed as both SOAP and REST services. Java Bean Services, Application Module Services, Open Interface Tables, and Open Interface Views can be exposed as REST services only.
Managing Grants in the Grants Tab for PL/SQL APIs, Concurrent Programs, Business Service Objects, Java Bean Services, Application Module Services, Open Interface Tables, and Open Interface Views
With the exception of XML Gateway interfaces that the user security is managed in the XML Gateway user interface, security grants for all other interface types that can be exposed as web services are managed in the Grants tab of the interface details page. These interfaces are PL/SQL APIs, Concurrent Programs, Business Service Objects, Java Bean Services, Application Module Services, Open Interface Tables, and Open Interface Views.
For information on managing the user security for XML Gateway interfaces, see: Managing Security Grants for SOAP Web Services Only.
Interface Details Page with Grants Tab Highlighted
Creating Security Grants
The administrator can select one or more procedures and functions or methods contained in the selected interface, and then click Create Grant. The Create Grants page is displayed where the administrator can grant the selected method access permissions to a user, user group, or all users.
Once a method access permission is authorized to a grantee, it grants the permission to access the associated SOAP and REST service operations simultaneously. For example, when a user (OPERATIONS) is authorized to have access permission on a method called 'Change User Name', regardless if the method has been exposed as a SOAP or REST service operation or not, the user OPERATIONS has the permission to access the 'Change User Name' operation of BOTH service types through the same grant.
Create Grants Page with Overloaded Functions
Only users who have the Integration Repository Administrator role can create and revoke security grants.
Each overloaded function contained in an interface can be uniquely granted to a specific user, user group, or all users through the grant feature. If you select more than one overloaded function, an Overloaded column appears in the Selected Methods table with the selected overloaded functions checked.
Revoking Security Grants
The administrator can revoke security grants in the following ways:
Note: For users who are granted as members of a group, you cannot revoke their grants individually, but revoke the grant for the entire group instead. The Revoke icon is disabled for group members.
Revoking Commonly Assigned Grants to All Selected Procedures or Methods
Select more than one procedure and function or method that you want to revoke the grants created earlier, and click Revoke Grant. This opens the Revoke Grants page where you can find the existing grants that are commonly assigned to the selected methods.
For example, a selected interface has the following grants:
Method Names | Grantee |
---|---|
Change User Name | SYSADMIN OPERATIONS |
Test User Name | OPERATIONS MKTMGR BUSER |
Validate User Name | BUSER OPERATIONS |
A specific User (grantee type) 'OPERATIONS' (grantee name) is commonly authorized to all the methods contained in the selected interface. Therefore, only User 'OPERATIONS' is listed as the common grant for all the methods.
To revoke this common grant, select these three method check boxes first, and then click Revoke Grant. This revokes the common grant, User 'OPERATIONS, assigned to these selected methods.
If there is more than one common grant listed in the table, select desired common grants from the table before clicking Revoke Grant.
Revoking Grants for a Single Procedure and Function or Method
In the Grants tab of the interface details page, select a desired method and then click Revoke Grant. The Revoke Grants page displays the existing grants that have been created for the selected method.
Select the grants that you want to revoke from the table, and click Revoke Grant to revoke the selected grants.
Viewing Grant Details
Each grant contains information about grantee type, grantee name, and whether the grant is authorized through a direct grant (such as a specific user 'OPERATIONS') or other grant method (such as through a user group 'Marketing Group').
To view grant details, click the Grant icon for the method that you want to view. A pop-up window called Grants appears with the grant details.
Note: For each member, the Granted Via column displays the name of the group. For grantees who were selected directly in the Create Grants page, the value in the Granted Via column is Direct
.
In addition to the Grants tab, you can view the grant details of a desired method from the SOAP Web Service tab and the REST Web Service tab.
To create grants:
Log in to Oracle E-Business Suite as a user who has the Integration Repository Administrator role. Select the Integrated SOA Gateway responsibility and the Integration Repository link.
In the Integration Repository tab, select 'Interface Type' from the View By drop-down list.
Expand an interface type node and click an interface definition that can be exposed as a REST service or as both SOAP and REST services.
The interface details page appears.
In the Grants tab, select one or more procedure and function or method names for which you want to create grants.
Click Create Grant. The Create Grants page appears.
Select a grantee type:
Specific User
Group of Users
All Users
If you select Specific User
or Group of Users
, specify the user or group for which to create the grants in the Grantee Name field.
Click Create Grant.
The interface details page reappears.
To view or revoke grants:
You can view and revoke existing grants directly in the methods list on the interface details page.
Navigate to the selected interface that can be exposed as a REST service.
To view grant details:
In the Grants tab, the REST Web Service tab, or the SOAP Web Service tab if it appears, click the Grant icon for a given operation. A pop-up window appears allowing you to view the grant details for the selected operation.
To revoke grants in the Grants tab:
To revoke common grants for all selected methods
Select more than one method from the table and click Revoke Grant. The Revoke Grants page appears. Select one or more common grants from the table and click Revoke Grant.
To revoke grants for a single method
Select a desired method from the table and then click Revoke Grant.
Select one or more existing grants from the table and click Revoke Grant to revoke the grants.
In addition to managing service lifecycle activities and creating security grants through the Integration Repository user interface, administrators can perform these tasks through backend processing:
Managing SOAP Service Lifecycle Activities Using Manual Steps
Managing REST Service Lifecycle Activities Using Manual Steps
Oracle E-Business Suite Integrated SOA Gateway allows you to perform SOAP service design-time activities through the use of command line. This includes:
For information on setting up Oracle E-Business Suite Integrated SOA Gateway in a multinode environment, see Configuring Oracle E-Business Suite Integrated SOA Gateway Release 12.1.2 and Release 12.1.3 in a Multinode Environment, My Oracle Support Knowledge Document 1081100.1.
For more troubleshooting information, see the Oracle E-Business Suite Integrated SOA Gateway Troubleshooting Guide, Release 12, My Oracle Support Knowledge Document 726414.1.
soagenerate.sh
When you try to generate a SOAP service from the Integration Repository user interface, if the system takes too long for the service generation to complete, the following HTTP 403 exception may appear on the interface:
oracle.apps.fnd.soa.util.SOAException:SystemError:Error while sending message to server. Server returned HTTP response code: 403 for URL: http://<hostname>:<port>/webservices/SOAProvider/EbizAuth?Generate=1656&soa_ticket=xxxxxxxxxxxxxxxxx_xxxx..' when attempting to perform 'GENERATE'.
To resolve the issue, a standalone soagenerate.sh
script is created allowing you to generate WSDL services for PL/SQL, concurrent program, and XML Gateway Map interfaces through backend processing.
Prerequisites to Run soagenerate.sh:
Environment variable (like $IAS_ORACLE_HOME
) needs to be set by running .env
file in APPL_TOP of your environment.
If you have the appmgr
privileges and have the read permission on $INST_TOP/ora/10.1.3/j2ee/oafm/config/oc4j.properties
, then you can run soagenerate.sh
without any setup described in step 3.
If you do not have the read permission on $INST_TOP/ora/10.1.3/j2ee/oafm/config/oc4j.properties
, then you need to set the following properties present in JAVA_TOP/oracle/apps/fnd/soa/provider/wsdl/data/soa.properties
:
Set the following two database connection related properties in the soa.properties
file:
SOA_CREATE_DB_CONN_CONTEXT = true
JTFDBCFILE =
<Physical Location of dbc file, to which User has read access>
Set the other required properties:
SOA_SERVER_TEMP_DIRECTORY_LOCATION=
<location of $INST_TOP/soa>
SOA_SERVER_URL=<protocol://host:port of Apps Self Service URL>
SOA_ENABLE_STANDALONE_LOGGING = true
You should have the write permission on SOA_SERVER_TEMP_DIRECTORY_LOCATION
mentioned in step 3.
You should have the write permission on the directory from where you are running this script.
Usage of soagenerate.sh:
$FND_TOP/bin/soagenerate [help] irepname=<irepname> logfile=<logfile> printprops=<true|false>
Valid arguments for soagenerate
are described as follows:
irepname: (mandatory) irepname of the interface to be generated.
logfile: (optional) logfilename, if a log file is to be created in any other directory.
By default, a log file is created with name 'ServiceGenerator.log' in the directory from which soagenerate.sh
is executed. If you want to create a log file in any other directory, give the location of the file in this argument.
printprops: (optional) true|false, whether system properties should be printed in logfile
.
By default, system properties related with SOA are not printed in logfile
. If you want to print system properties in logfile
, specify printprops=true
.
Postclone.sh
You can run the following Postclone.sh
script to have deployed SOAP services created in a cloned Oracle E-Business Suite environment:
$FND_TOP/bin/postclone.sh Enter service type (SOAP/REST/BOTH) :
Enter "SOAP" as the Service Type value to clone SOAP services. To clone both SOAP and REST services, enter "BOTH" as the value.
This Postclone.sh
script writes results to the $INST_TOP/soa/SOAPPostCloneResults.txt
file. It includes postclone status and WSDL URL for each deployed interface. If the script fails to redeploy an interface, it is also mentioned in this file.
In addition to performing REST design-time activities through the Integration Repository user interface (UI), you can use command line to perform the following activities:
Deploying or Undeploying REST Services Using RestDeployer.sh
Redeploying REST Services in a Cloned Environment Using Postclone.sh
For information on setting up ISG in a multinode environment, see Configuring Oracle E-Business Suite Integrated SOA Gateway Release 12.1.2 and Release 12.1.3 in a Multinode Environment, My Oracle Support Knowledge Document 1081100.1.
Once you deploy a REST service through manual steps by running the script RestDeployer.sh
, a WADL link for the deployed REST service would be available in the Interface Details page through the Integration Repository user interface.
Perform the following steps to deploy or undeploy a REST service:
Find irep_name
of the service to be deployed.
For example, irep_name
is the 'Internal Name' of a desired PL/SQL API shown in the Interface Details page in the Integration Repository user interface.
Change directory to $FND_TOP/bin
.
Run RestDeployer.sh irepname=<irep_name>
. For example,
Deploy a PL/SQL API 'FND_GLOBAL' as a REST service with POST HTTP verb using the following command:
RestDeployer.sh irepname=FND_GLOBAL
.
Deploy the following open interface tables contained in the 'OEOIMP' open interface with Inbound
direction using one command:
RestDeployer.sh irepname=OEOIMP[{OE_HEADERS_IFACE_ALL:GET+POST+DELETE+PUT}{OE_LINES_IFACE_ALL:GET+POST}]
This deploys OE_HEADERS_IFACE_ALL table as a REST service with four supported HTTP verbs (GET, POST, DELETE, and PUT), and OE_LINES_IFACE_ALL table as a REST service with both the GET and POST HTTP verbs.
Note that the supported verb for PL/SQL APIs is POST only; the supported verbs for Java Bean Services and Application Module Services are all the annotated verbs and POST. For open interface tables with Outbound direction and open interface views, the supported verb is GET only.
When prompted, provide the following inputs:
Enter the target as deploy or undeploy:
deploy (or undeploy)
Enter the alias of the interface to be deployed:
<alias name>
Review log file ServiceGenerator.log
for details.
Follow the text after the "ServiceGenerator invoked at : <Date Time>" message in the log file. The irepName, ClassId, WADL URL and status information would be displayed. For example, the log file contains the following information for a deployed PL/SQL REST service:
irepName is : <irep_name> ClassId = <classId> Class Type = PLSQL Generating service with classId = <classId> WADL URL = https://<host>:<port>/webservices/rest/<alias name>?WADL Service Generated and Deployed.
The message "Service Generated and Deployed" indicates that the REST service is successfully deployed.
You can execute the following Postclone.sh
script to have deployed REST services created in a cloned Oracle E-Business Suite environment:
$FND_TOP/bin/postclone.sh Enter service type (SOAP/REST/BOTH) :
Enter "REST" as the Service Type value to clone REST services. To clone both SOAP and REST services, enter "BOTH" as the value.
The Postclone.sh
script writes results to the $INST_TOP/soa/RESTPostCloneResults.txt
file. It includes postclone status and WADL URL for each deployed interface. If the script fails to redeploy an interface, it is also mentioned in this file.
In addition to managing security grants through the Integration Repository user interfaces, an administrator can use the isggrant.xml
script to perform this task.
ant -f $JAVA_TOP/oracle/apps/fnd/isg/isggrant.xml -DirepNames=<interface_name[function1:function2:..]> -Dactions=<CREATE | REVOKE> -DgranteeType=< USER | GROUP | GLOBAL> -DgranteeKey= <Grantee Key>
See Using the Script with Arguments for the Grant.
Argument Description
The following arguments are specifically used in isggrant.xml
for managing security grants:
irepNames: Comma separated list of interface names.
Use either one of the following syntax for the interface name:
interface_name
interface_name[function1:function2: ... ]
actions: Comma separated list of actions to be performed. Supported operations are listed as follows:
create: It creates a security grant for a selected interface or service.
revoke: It removes a grant created earlier, including the privileges of a grantee of any type (such as user, group, or global) assigned to the grant.
granteeType: Supported values are:
USER: It grants the access privilege of a selected interface or service to a specific user only.
GROUP: It grants the access privilege of a selected interface or service to a specific group only.
GLOBAL: It grants the access privilege of a selected interface or service to all Oracle E-Business Suite users.
granteeKey: A required argument to provide a specific user or group value when granteeType is USER or GROUP. It is not required when the granteeType value is GLOBAL.
If granteeType is USER, provide user code (user name) as granteeKey.
If granteeType is GROUP, provide responsibility code as granteeKey.
Using the Script with Arguments for the Grant
The following examples explain how to use the script with arguments to create and revoke security grants:
Create a grant to a specific user "OPERATIONS" with the access privileges of CHANGE_USER_NAME and TESTUSERNAME service operations within the FND_USER_PKG interface:
Note: OPERATIONS
in the DgranteeKey
argument is the user name (user code) value for an Oracle E-Business Suite user.
ant -f $JAVA_TOP/oracle/apps/fnd/isg/isggrant.xml -DirepNames=FND_USER_PKG[CHANGE_USER_NAME:TESTUSERNAME] -Dactions=CREATE -DgranteeType=USER -DgranteeKey=OPERATIONS
Revoke the privileges from the group SYSTEM_ADMINISTRATION that has given the access of all service operations in the FND_MESSAGE interface and the CHANGE_USER_NAME operations within the FND_USER_PKG interface:
Note: FND_RESP|ICX|SYSTEM_ADMINISTRATION|STANDARD
in the DgranteeKey
argument is the responsibility code value for the System Administration responsibility.
ant -f $JAVA_TOP/oracle/apps/fnd/isg/isggrant.xml -Dactions=REVOKE -DirepNames=FND_MESSAGE,FND_USER_PKG[CHANGE_USER_NAME] -DgranteeType=GROUP -DgranteeKey=FND_RESP|ICX|SYSTEM_ADMINISTRATION|STANDARD
To understand SOAP and REST service generation and deployment status, an administrator can run an Ant script DownloadServicesList.xml
using the following command:
ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/DownloadServicesList.xml
This script generates a service descriptor file called ISGServiceDescriptor_<timestamp>.xml
in $INST_TOP/soa
. This file reports the list of APIs which are generated or deployed as SOAP services, or are deployed as REST services.
For example, the following sample service descriptor file lists the service description information:
A Business Service Object service operation findParties
contained in the interface /oracle/apps/ar/hz/service/party/DqmSearchService
(with alias name dqm
) is deployed as a REST service operation with the POST method.
A PL/SQL API HZ_CUST_ACCOUNT_V2PUB
is generated and deployed as a SOAP service with the Username Token security.
<INTEGRATION_REPOSITORY name="EBS_SID" xsd_version="2.0"> <INTERFACE> <NAME>/oracle/apps/ar/hz/service/party/DqmSearchService</NAME> <TYPE>SERVICEBEAN</TYPE> <REST_ACTIONS> <UNDEPLOY/> <DEPLOY> <ALIAS>dqm</ALIAS> <FUNCTIONS_LIST verb="POST"> <FUNCTION>findParties</FUNCTION> </FUNCTIONS_LIST> </DEPLOY> </REST_ACTIONS> </INTERFACE> <INTERFACE> <NAME>HZ_CUST_ACCOUNT_V2PUB</NAME> <TYPE>PLSQL</TYPE> <SOAP_ACTIONS> <UNDEPLOY/> <GENERATE> <ALL_FUNCTIONS/> </GENERATE> <DEPLOY> <POLICY>USERNAME_TOKEN</POLICY> </DEPLOY> </SOAP_ACTIONS> </INTERFACE> </INTEGRATION_REPOSITORY>