Skip Headers

Oracle E-Business Suite Integrated SOA Gateway Implementation Guide
Release 12.2
Part Number E20925-09
Go to Table of Contents
Contents
Go to previous page
Previous
Go to next page
Next

Administering Native Integration Interfaces and Services

Overview

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 Administrator role, hereafter referred as an integration administrator or the administrator, can manage each state of the services throughout the service life cycle as well as manage grants for them.

To better understand how to administer and manage these two types of Web services, the following topics are included in this chapter:

Administering SOAP Web Services

Interfaces Supported for SOAP Service Enablement

Oracle E-Business Suite Integrated SOA Gateway supports the following interface types for SOAP-based service enablement:

Please note that in this release Java APIs for Forms are no longer serviceable interfaces and cannot be exposed as SOAP services.

Managing SOAP Service Life Cycle Activities

The integration administrator 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

the picture is described in the document text

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 including configuring log setups and monitoring runtime SOAP activities. See:

Generating SOAP Web Services

Oracle E-Business Suite Integrated SOA Gateway allows users who have the Integration Administrator role or the Integration Developer role to transform interface definitions to SOAP services.

SOAP services can be generated with the support for synchronous or asynchronous interaction pattern, or both synchronous and asynchronous patterns. Before generating a service, the integration administrator or the integration developer must specify interaction pattern(s) for desired methods to be exposed as service operations. This can be achieved at the method level for one or more methods, or at the interface level for all methods.

Important: In this release, asynchronous operation is supported only in PL/SQL interfaces in enabling SOAP-based services.

Please note that by default, none of the interaction pattern would be selected. However, if your system is upgraded from a previous release, for backward compatibility, 'synchronous' pattern is selected for all the methods contained in a service.

For more information about synchronous and asynchronous operation patterns, see Synchronous and Asynchronous Web Services.

Generating Services

For interfaces with the support for SOAP services only, service activities are managed in the Web Service region. For interfaces with the support for both REST and SOAP services, these activities are managed in the SOAP Web Service tab of the interface details page.

Once a service is generated, the associated service artifacts are also generated for the selected methods. If only one method is selected, then only that selected method has a service artifact generated.

Note: It's important to note the following for PL/SQL based concurrent program:

After Service Generation

The Web Service region or the SOAP Web Service tab contains the following information:

Web Service Region

the picture is described in the document text

SOAP Web Service Tab

the picture is described in the document text

Note: For overloaded functions, sequence number is added to the end of the overloaded method name. Each overloaded function can be uniquely selected and generated with your desired interaction pattern.

After service generation, if the interface definition has been changed or the selected interaction pattern information has been modified before service deployment, you can regenerate the service by clicking Regenerate. However, if interface definition is not changed, then regenerating the service will not change the service definition.

Click Reset to clear up the existing service artifact and change the Web Service Status field from 'Generated' to 'Not Generated'. See: Resetting SOAP Web Services.

To deploy the generated service, the administrator must select one desired authentication type in the Authentication Type region. The selected authentication type will be used to authenticate Oracle E-Business Suite users at run time. For more information on deploying a service, see Deploying and Undeploying SOAP Web Services.

Displaying Generic XML Gateway Service Subregion for Generic XML Gateway Services

For XML Gateway interface type, if your system is upgraded from a previous release and if you have been using generic XML Gateway Web services, the generic XML Gateway service information can be displayed by setting the FND: XML Gateway Map Generic Service profile value to 'Yes'.

In the Web Service region, click the Show Generic XML Gateway Service or Hide Generic XML Gateway Service link to display or close the Generic XML Gateway Service subregion for the selected XML Gateway interface.

For more information on setting profile options, see Setting Profile Options.

In addition to setting profile options, the administrator needs to perform additional setup tasks for generic XML Gateway services. For setup information, see Installing Oracle E-Business Suite Integrated SOA Gateway, Release 12.2, My Oracle Support Knowledge Document 1311068.1 for details.

Generic XML Gateway Service Subregion

the picture is described in the document text

The Generic XML Gateway Service subregion contains the following fields:

To generate a Web service:

  1. Log in to Oracle E-Business Suite as a user who has the Integration Administrator role. Select the Integrated SOA Gateway responsibility and the Integration Repository link.

  2. In the Integration Repository tab, select 'Interface Type' from the View By drop-down list.

  3. Expand an interface type node to locate your desired interface definition.

  4. Click the interface definition name link to open the interface details page.

  5. If this selected interface definition does not have service generated, specify at least one interaction pattern in the Interaction Pattern table. This can be done at the interface level or at the method level before clicking Generate in the Web Service region to generate the WSDL description.

    For interfaces that can be supported with both REST and SOAP services, Generate is located in the Service Operations region of the SOAP Web Service tab in the interface details page.

    After service generation, the interaction pattern table and the Interaction Pattern field are displayed with selected pattern information for your interface.

    The Web Service Status field marked as 'Generated' also appears which indicates that this selected interface has WSDL description available.

  6. Click the View WSDL link to view the WSDL description.

  7. Click Regenerate to regenerate the WSDL description if necessary.

Deploying and Undeploying SOAP Web Services

If a SOAP service has been generated successfully, the administrator has the privilege to deploy the generated service in the Web Service region or the SOAP Web Service tab if the interface can be exposed as both SOAP and REST services.

Deploying Web Services

the picture is described in the document text

Deploying Web Services with Authentication Types

Prior to deploying a SOAP Web service, the administrator must first select one of the following authentication types:

Deployment with Active State

Once a SOAP Web service has been successfully deployed, the newly deployed service has 'Deployed with Active' service status in Oracle SOA Suite where Oracle E-Business Suite services can be used at run time.

Web Service Region After Service Deployment

the picture is described in the document text

The Web Service region (or the SOAP Web Service tab for the interface with the support for both SOAP and REST services) has the following changes:

For more information on service generation, see Generating SOAP Web Services.

For more information on supported authentication types, see Managing Web Service Security.

Reviewing Deployed WSDL

To view the deployed Web service, click the View WSDL link. The following example shows the deployed WSDL code:

Note: Please note that the deployed WSDL shows the physical location of service endpoint where the service is hosted in the soa-infra in <soap:address location> element. Generated WSDL does not display the physical service endpoint, but with the following information:

<soap:address location="#NOT_DEPLOYED#" />

<definitions name="ECRDTLD" targetNamespace="http://xmlns.oracle.com/apps/ec/soaprovider/concurrentprogram/ecrdtld/">
<documentation> 
 <abstractWSDL>
   http://<hostname>:<port>/soa-infra/services/default/<jndi_name>_CONCURRENTPROGRAM_ECRDTLD!1/ECRDTLD_soap.wsdl
</abstractWSDL>
</documentation>
<types>
   <schema elementFormDefault="qualified" targetNamespace=http://xmlns.oracle.com/apps/ec/soaprovider/concurrentprogram/ecrdtld/">
  <include schemaLocation="http://<hostname>:<port>/soa-infra/services/default/<jndi_name>_CONCURRENTPROGRAM_ECRDTLD/ECRDTLD_Service/?XSD=APPS_ISG_CP_REQUEST_CP_SUBMIT.xsd"/> 
   </schema>
   <schema elementFormDefault="qualified" targetNamespace="http://xmlns.oracle.com/apps/ec/soaprovider/concurrentprogram/ecrdtld/"> 
  <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>
<message name="ECRDTLD_Input_Msg">
   <part name="header" element="tns1:SOAHeader"/>
   <part name="body" element="tns1:InputParameters"/>
</message>
<message name="ECRDTLD_Output_Msg">
   <part name="body" element="tns1:OutputParameters"/>
</message>
<portType name="ECRDTLD_PortType">
   <operation name="ECRDTLD">
     <input message="tns1:ECRDTLD_Input_Msg"/>
     <output message="tns1:ECRDTLD_Output_Msg"/>
   </operation>
 </portType>
<binding name="ECRDTLD_Binding" type="tns1:ECRDTLD_PortType">
  <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
  <operation name="ECRDTLD">
   <soap:operation soapAction="ECRDTLD"/>
     <input>
       <soap:header message="tns1:ECRDTLD_Input_Msg" part="header" use="literal"/>
       <oap:body use="literal" parts="body"/>
     </input>
     <output>
       <soap:body use="literal"/>
     </output>
   </operation>
  </binging>
  <service name="ECRDTLD_Service">
    <port name="ECRDTLD_Port" binding="tns1:ECRDTLD_Binding">
     <soap:address location="http://<hostname>:<port>/soa-infra/services/default/<jndi_name>_CONCURRENTPROGRAM_ECRDTLD/ECRDTLD_Service/"/>
   </port>
 </service>
</definitions>

To deploy or undeploy a Web service:

  1. Log in to Oracle E-Business Suite as a user who has the Integration Administrator role. Select the Integrated SOA Gateway responsibility and the Integration Repository link.

  2. In the Integration Repository tab, select 'Interface Type' from the View By drop-down list.

  3. Expand an interface type node to locate your desired interface definition.

  4. Click the interface definition name link to open the interface details page.

  5. From the Web Service region (or the SOAP Web Service tab), select one of the following authentication types:

  6. Click Deploy to deploy the service with active state to an Oracle SOA Suite WebLogic environment.

  7. Click the deployed View WSDL link to view the deployed WSDL description.

  8. Click Undeploy to undeploy the service.

  9. If a service has been deployed with active state, Retire appears lets you disable the active service so that it will no longer accept new requests.

  10. Click Reset to clear up the existing service artifact.

Resetting SOAP Web Services

Once an integration interface becomes a Web service, the associated service artifact is also generated. No matter if the generated service has been deployed or not, you can clear up the service artifact and reset the Web service status to its initial state - 'Not Generated' regardless of its current state. This action can be performed at any stage of service generation and deployment life cycle.

For example, an interface definition needs to be modified or has been changed. Instead of regenerating the service if it has not yet been deployed, or undeploying the service if it has been deployed, you can:

  1. Reset the service to clear up the existing service artifact.

  2. Modify the interface.

  3. Generate the service again.

For information on how to generate a Web service for a given interface, see Generating SOAP Web Services.

Resetting a Service After Service Deployment

the picture is described in the document text

To reset a Web service:

  1. Log in to Oracle E-Business Suite as a user who has the Integration Administrator role. Select the Integrated SOA Gateway responsibility and the Integration Repository link.

  2. Click Search to open the main Search page.

  3. Enter appropriate search information such as product family, product, interface type, or business entity.

  4. Click Show More Search Options and select 'Deployed' or 'Generated' in the Web Service Status field.

  5. Locate the interface definition that match your search criteria from the result table.

  6. Click the interface definition name link to open the interface details page.

  7. In the Web Service region (or the SOAP Web Service tab for the interface with the support for both SOAP and REST services), click Reset to clear up existing service artifact for the selected service. The service status is changed to 'Not Generated'.

Retiring SOAP Web Services

When a service has been successfully deployed to Oracle SOA Suite with active state, Retire appears allowing you to change the state of the deployed service from 'Active' to 'Retired'.

Note: This action also ensures that current running requests are finished while retiring the service.

Service with 'Retired' state means that the deployed service is no longer active for service invocation and will not accept new SOAP requests.

Web Service Region After Service Deployment

the picture is described in the document text

Please note that a service with 'Retire' state, the selected interaction pattern and authentication type information remains the same.

After retiring a deployed service, the Web Service region (or the SOAP Web Service tab for the interface with the support for both SOAP and REST services) has the following changes:

To retire a Web service:

  1. Log in to Oracle E-Business Suite as a user who has the Integration Administrator role. Select the Integrated SOA Gateway responsibility and the Integration Repository link.

  2. Click Search to open the main Search page.

  3. Enter appropriate search information such as product family, product, interface type, or business entity.

  4. Click Show More Search Options and select 'Deployed' for the Web Service Status field.

  5. Locate the interface definition that match your search criteria from the result table.

  6. Click the interface definition name link to open the interface details page.

  7. In the Web Service region (or the SOAP Web Service tab for the interface with the support for both SOAP and REST services), click Retire if needed to retire the active deployed service.

Activating SOAP Web Services

After a service has been deployed with 'Retired' state, it is not available to participate in any Web service activities at run time. To bring it back to work and to be invoked by Web service clients, you must change the 'Retired' state to 'Active'. This can be achieved by clicking Activate to take the retired service back to an active state again.

SOAP Web Service Tab After Service Deployment for a PL/SQL API

the picture is described in the document text

Please note that activating a service will not change its service definition. This means that the selected interaction pattern and authentication type information remains the same as it was before.

After activating a service, the following fields are changed in the Web Service region (or the SOAP Web Service tab for the interface with the support for both SOAP and REST services):

To activate a retired Web service:

  1. Log in to Oracle E-Business Suite as a user who has the Integration Administrator role. Select the Integrated SOA Gateway responsibility and the Integration Repository link.

  2. Click Search to open the main Search page.

  3. Enter appropriate search information such as product family, product, interface type, or business entity.

  4. Click Show More Search Options and select 'Deployed' for the Web Service Status field.

  5. Locate the interface definition that match your search criteria from the result table.

  6. Click the interface definition name link to open the interface details page.

  7. In the Web Service region (or the SOAP Web Service tab), click Activate if available to activate the retired service.

Subscribing to Business Events

An integration administrator can find Subscribe in the business event interface details page which allows the administrator to subscribe to a selected business event and create an event subscription for that selected event.

Subscribing to a Business Event

the picture is described in the document text

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 the WF_BPEL_Q queue, then the event message will be enqueued in WF_EVENT_T structure to Advanced Queue WF_BPEL_Q.

Unsubscribing to Business Events

Once an event subscription has been successfully created, Unsubscribe appears instead. Clicking Unsubscribe removes the event subscription from the 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.

For more information about business events, see Managing Business Events, Oracle Workflow Developer's Guide.

To subscribe to a business event:

  1. Log in to Oracle E-Business Suite as a user who has the Integration Administrator role. Select the Integrated SOA Gateway responsibility and the Integration Repository link.

  2. In the Integration Repository tab, select 'Interface Type' from the View By drop-down list.

  3. Expand the Business Event interface type node to locate your desired event.

  4. Click the business event interface that you want to subscribe to it to open the Interface details page for the event.

  5. 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.

    Remove the subscribed event by clicking Unsubscribe to remove or delete the event subscription if needed.

Managing Security Grants for SOAP Web Services Only

To protect application data from unauthorized access, Oracle E-Business Suite Integrated SOA Gateway provides security grant feature allowing only authorized users to execute certain methods in an API through Integration Repository.

Managing Grants in the Methods Region

For interfaces that can be exposed as SOAP services only, security grants are managed in the Methods region.

Managing Grants in the Methods Region

the picture is described in the document text

Note: In this release, only PL/SQL interfaces can be exposed as both SOAP and REST services. For this type of interfaces, security grants are managed in the Grants tab instead. Once a PL/SQL API method access permission is authorized to a grantee, it grants the permission to the associated SOAP and REST services simultaneously. For information on how to manage security grants for PL/SQL interfaces, see Managing Security Grants for SOAP and REST Web Services.

Creating Security Grants

In the interface details page, an integration administrator can select appropriate method name check boxes in the Methods region. Click Create Grant to open the Create Grants page where the administrator can grant the selected method access permissions to a user, user group, or all users.

Select one of the following values as the grantee type:

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.

Viewing Grant Details

To view the grant details, click the Show link for a given method in the Methods region. If you specified a group of users as the grantee, then all members within the group (i.e. 'Jackson, Lou' and 'Payment, John'), plus the group name itself (i.e. 'OIC Payment Analyst Manger Group') are listed as a grantee.

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.

Revoking Security Grants

In the Methods region, click the Show link for a given method. Click the Revoke icon to revoke a grant for a specific grantee. A confirmation page appears, where you can click Apply or Cancel to execute or cancel the action.

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.

To create grants:

  1. Log in to Oracle E-Business Suite as a user who has the Integration Administrator role. Select the Integrated SOA Gateway responsibility and the Integration Repository link.

  2. In the Integration Repository tab, select 'Interface Type' from the View By drop-down list.

  3. Expand an interface type node and click an interface definition name link you want to open the interface details page.

  4. Select one or multiple method names for which you want to create grants.

  5. Click Create Grant. The Create Grants page appears.

  6. Select a grantee type from the list of values.

  7. If you selected Specific User or Group of Users, specify the user or group for which to create the grants in the Grantee Name field.

  8. Click Apply.

    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.

  1. Navigate to the interface details page that you want to view or revoke the grants.

  2. In the Methods region, click Show for a given method to view its grant details in a table.

  3. You can revoke a grant by clicking the Revoke icon. Click Apply to confirm your action.

Enabling Design-Time Log Configuration

To troubleshoot any issues or exceptions encountered during service generation and deployment life cycle, users with the Integration Administrator role can enable design-time log setting for a selected interface.

If the design-time log is enabled for the selected interface, 'Enabled' is displayed as the Log Configuration value in the header section of the interface details page. Otherwise, 'Disabled' is displayed instead.

To change the existing design-time log configuration for the selected interface, click Configure next to the Log Configuration field. The Log & Audit Setup Details page is displayed with the selected interface where the administrator can add a new log configuration or update existing configurations.

Note: The Log & Audit Setup Details page can also be accessed by selecting the Administration > Configuration from the navigation menu.

Please note that this feature applies to an interface with the support for SOAP services only.

Viewing Generate and Deploy Time Logs

To effectively troubleshoot any issues or exceptions encountered at design time during each stage of service generation and deployment life cycle including generating, deploying, retiring, resetting, and activating services, error messages and activity information can be logged and viewed through the interface details page.

Note: Logging is supported for SOAP services only.

For information on how to enable the design-time log for an interface, see Adding a New Configuration.

the picture is described in the document text

Viewing Error and Log Details from the View Log Button

If an interface has the design-time log enabled, View Log appears in the interface details page allowing you to access the Log & Error Details page.

The Log & Error Details page contains the following regions:

Viewing Error Details from the View Error Button

If the selected interface does not have the design-time log enabled, and if any errors occurred during design-time activities, View Error appears instead allowing you to view only the error or exception messages displayed in the Error Details region.

For example, if the administrator receives errors or exceptions while trying to perform any actions at design time such as Generate, Deploy, Activate, Retire, or Reset for an interface, these errors are recorded and displayed in the Error Details region even if the design-time log is not configured for the interface.

For error messages, error codes, and possible solutions, see Error Messages.

The Log Details region will not appear in this page because the design-time log is not configured for the selected interface.

For more logging information, see Logging for Web Services. For information on how to add a new configuration, see Adding a New Configuration.

At run time during the invocation of Oracle E-Business Suite services by Web service clients, if a service has the runtime log enabled, log messages can be viewed in Service Monitor against that instance. For information on viewing log messages through Service Monitor, see Viewing Service Processing Logs.

To view service development log messages:

  1. Log in to Oracle E-Business Suite as a user who has the Integration Administrator role. Select the Integrated SOA Gateway responsibility and the Integration Repository link.

  2. In the Integration Repository tab, select 'Interface Type' from the View By drop-down list.

  3. Expand an interface type node to locate your desired interface definition.

  4. Click the interface definition name link to open the interface details page.

  5. If the selected interface does not have the design-time log enabled, View Error appears instead in the interface details page if errors occurred during the design-time activities.

    Click View Error to view the error details that occurred during design time.

  6. If the selected interface has the design-time log enabled, View Log appears in the interface details page.

    Click View Log to view the log and error details.

    Click Delete Log to delete all the logs listed in the table if needed.

    Click Export to export log list table to Microsoft Excel and save the records.

Managing SOAP Service Life Cycle Activities Using An Ant Script

An Ant script $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml is used to execute the design-time activities for SOAP services such as generate, regenerate, deploy, undeploy, activate, retire, and reset services as well as to upgrade or postclone services from command line.

Please note that $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml is a multipurpose script. It can also be used to run the diagnostic tests or download the configuration file from the instance. The configuration file is the present state of instance in the view of Oracle E-Business Suite Integrated SOA Gateway context. The same configuration file is sometimes referred as service descriptor file.

Note: When services are generated from command line, the settings selected from the Integration Repository user interface will take effect while generating the service artifacts. For example, if 'Asynchronous' interaction pattern is selected for a method contained in a PL/SQL interface, no matter if the service is generated from the UI or command line, only that selected single method has the associated artifact generated for asynchronous operation.

Usage of $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml:

ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml usage

Note: Script creates log file at the script location; hence, it is suggested to copy isgDesigner.xml to some <TEMP_DIRECTORY> and then use the script present in <TEMP_DIRECTORY>.

Usage Related to Design Activities

  1. Enter ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml. It will prompt for the arguments.

    Note: Do not enclose any input between double quotes.

  2. Enter the arguments in the following ways:

Argument Description

Valid arguments for isgDesigner.xml are described as follows:

Usage Examples

Other Usages

In addition to performing design time activities, this $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml script can be used for the following purposes:

Deploying Generic XML Gateway Services

To deploy a generic XML Gateway service for the current environment, invoke this script with target deployGenericXMLG

ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml deployGenericXMLG

For more information on deploying generic XML Gateway services, see Installing Oracle E-Business Suite Integrated SOA Gateway, Release 12.2, My Oracle Support Knowledge Document 1311068.1 for details.

Obtaining Argument irepNames Usage Information

To know how to pass argument irepNames, invoke this script with target irepNamehelp

ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml irepNamehelp

This prints the following information on console window:

Each interface name for the irepNames argument should be given in one of the following way:

Usage Example: FND_USER_PKG [{TESTUSERNAME:SYNC}{CHANGE_USER_NAME:ASYNC}],FND_GLOBAL

Note: Patterns supported here are described in the following:

interface_name[{function1:pattern1}{function2:pattern2}]

interface_name

All functions of the interface interface_name will be generated with old pattern. If the interface is a new API or has been reset, then all the functions will be generated with SYNC interaction pattern.

Running Diagnostic Tests

Oracle E-Business Suite Integrated SOA Gateway provides a suite of diagnostic tests to help determine specific causes or issues with installation steps. When a test suite is run, multiple tests would be executed on both Oracle E-Business Suite and Oracle SOA Suite environments for diagnosing issues on various categories.

To know how to run different diagnostic tests, invoke this script with diagnosticshelp

ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml diagnosticshelp

Additionally, you can run different diagnostics through the backend script with different targets. For more information on how to run these diagnostic tests, see Oracle E-Business Suite Integrated SOA Gateway Diagnostic Tests.

Administering REST Web Services

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 can be exposed as both SOAP and REST services; Java Bean Services 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 services support only synchronous (request-response and request-only) interaction pattern and have a simplified service life cycle.

Simplified Service Life Cycle

REST services have a simplified service life cycle. The administrator can perform the following tasks in the REST Web Service tab to manage the REST service life cycle:

The administrator can manage security grants in the Grants tab of the interface details page. It assigns grants to specific users to access or invoke the deployed REST services.

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.

REST services can be deployed and undeployed from the Integration Repository user interface and from the Ant script $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml.

To better understand each administrative task, the following topics are included in this section:

Deploying REST Web Services

Oracle E-Business Suite Integrated SOA Gateway allows the administrator to deploy interface definitions as REST services. These interfaces can be PL/SQL APIs and Java Bean Services.

Please note that PL/SQL APIs can be exposed as both SOAP and REST services; Java Bean Services can be exposed as REST services only.

Deploying Web Services

the picture is described in the document text

Deploying REST Services in the REST Web Service Tab

Before deploying a REST service, the administrator must perform the following tasks:

REST Service Security

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.

Click Deploy to deploy the selected service operations to an Oracle E-Business Suite managed server for consumption.

After Service Deployment

Once the REST service has been successfully deployed, the REST Web Service tab has the following changes:

REST Web Service Tab After Service Deployment

the picture is described in the document text

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: Please 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, 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 GET method, and the getPersonInfo operation is implemented with both 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>

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:

  1. Log in to Oracle E-Business Suite as a user who has the Integration Administrator role. Select the Integrated SOA Gateway responsibility and the Integration Repository link.

  2. In the Integration Repository tab, select 'Interface Type' from the View By drop-down list.

  3. Expand an interface type node to locate your desired interface definition.

  4. Click the interface definition name link to open the interface details page.

  5. In the REST Web Service tab, enter the following information:

  6. Click Deploy to deploy the service to an Oracle E-Business Suite environment.

  7. Click the deployed View WADL link to view the deployed WADL description.

Undeploying REST Web Services

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'.

Undeploying REST Services

the picture is described in the document text

Please 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.

REST Web Service Tab After Service Undeployment

the picture is described in the document text

To undeploy a REST Web service:

  1. Log in to Oracle E-Business Suite as a user who has the Integration Administrator role. Select the Integrated SOA Gateway responsibility and the Integration Repository link.

  2. In the Integration Repository tab, select 'Interface Type' from the View By drop-down list.

  3. Expand an interface type node to locate your desired interface definition.

  4. Click the interface definition name link to open the interface details page.

  5. In the REST Web Service tab, click Undeploy to undeploy the service.

Managing Grants for Interfaces with Support for SOAP and REST Web Services

Users who have the Integration 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 can be exposed as both SOAP and REST services. Java Bean Services can be exposed as REST services only.

Managing Grants in the Grants Tab for PL/SQL APIs and Java Bean Services

Security grants for PL/SQL APIs and Java Bean Services are managed in the Grants tab of the interface details page.

Managing Grants in the Grants Tab

the picture is described in the document text

For interfaces with the support for SOAP services only, security grants are managed in the Methods region instead. See: Managing Security Grants for SOAP Web Services Only.

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.

Revoking Security Grants

The administrator can revoke security grants in the following ways:

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 appears with the grant details.

In addition to the Grants tab, you can view the grant details for a desired method from the SOAP Web Service tab and the REST Web Service tab.

To create grants:

  1. Log in to Oracle E-Business Suite as a user who has the Integration Administrator role. Select the Integrated SOA Gateway responsibility and the Integration Repository link.

  2. In the Integration Repository tab, select 'Interface Type' from the View By drop-down list.

  3. Expand an interface type node and click an interface definition (such as a PL/SQL API) that can be exposed as both SOAP and REST services.

    The interface details page appears.

  4. In the Grants tab, select one or more procedure and function or method names for which you want to create grants.

  5. Click Create Grant. The Create Grants page appears.

  6. Select a grantee type:

  7. 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.

  8. 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.

  1. Navigate to the selected interface that can be exposed as REST services.

  2. To view grant details:

    In the Grants tab, the SOAP Web Service tab, or the REST Web Service tab, click the Grant icon for a given operation. A pop-up window appears allowing you to view the grant details for the selected operation.

  3. To revoke grants in the Grants tab:

Managing REST Service Life Cycle Activities Using An Ant Script

Similar to SOAP services, the administrator can use an Ant script $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml to execute the design-time activities for REST services such as deploy and undeploy services from command line.

Usage of $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml:

ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml usage

Note: Script creates log file at the script location; hence, it is suggested to copy isgDesigner.xml to some <TEMP_DIRECTORY> and then use the script present in <TEMP_DIRECTORY>.

Usage Related to Design Activities

  1. Enter ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml. It will prompt for the arguments.

    Note: Do not enclose any input between double quotes.

  2. Enter the arguments in the following ways:

Argument Description

Valid arguments for isgDesigner.xml are described as follows:

Usage Examples

Please note that $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml is a multipurpose script. It can be used to manage life cycle activities for SOAP services. See: Managing SOAP Service Life Cycle Activities Using An Ant Script.

You can also use this script to run the diagnostic tests or download the configuration file from the instance.