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 how to transform these interface definitions into SOAP and REST web services through the user interface, and how to manage service lifecycle activities using a script.

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

• Administering SOAP Web Services Through Integration Repository

• Administering REST Web Services Through Integration Repository

• Managing Service Life Cycle and Security Grants Using an Ant Script

Administering SOAP Web Services Through Integration Repository

Interfaces Supported for SOAP Service Enablement

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

Important: For interfaces that can be exposed as SOAP services, if the setup tasks for SOAP services are not performed, when viewing these interfaces through the Integration Repository, you may find a message indicating that Oracle E-Business Suite Integrated SOA Gateway is not configured for SOAP services and refer to My Oracle Support Knowledge Document 1311068.1 for configuration details.

Integration Repository Page with Information About Configuring Oracle E-Business Suite Integrated SOA Gateway

• PL/SQL

• XML Gateway Map (Inbound)

• Concurrent Program

  Important: Oracle Integration Repository supports REST service enablement for open interface tables and open interface views. If a concurrent program is associated with an open interface table or an open interface 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

In this release Java APIs for Forms are no longer serviceable interfaces and cannot be exposed as SOAP services. 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

The integration administrators can perform the following administrative tasks in managing each state of SOAP services throughout the entire service life cycle from the Integration Repository user interface:

Service Generation and Deployment Process Flow

• Generating SOAP Web Services

• Deploying and Undeploying SOAP Web Services

• Resetting SOAP Web Services

• Retiring SOAP Web Services

• Activating SOAP Web Services

• Subscribing to Business Events

• Managing Security Grants for SOAP Web Services Only

• Enabling Design-Time Log Configuration for SOAP Services

• Viewing Design-Time Logs for SOAP Services

Note that the administrators can also manage SOAP service lifecycle activities and create security grants using an Ant script, see:

• Managing SOAP Service Lifecycle Activities Using an Ant Script

• Managing Security Grants Using an Ant 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 including configuring log setups, and monitoring runtime inbound and outbound SOAP service invocations. See:

• Logging for Web Services

• Monitoring and Managing Inbound Service Invocation Messages Using Service Monitor

• Monitoring and Managing Outbound Service Invocation Messages Using Service Invocation Monitor

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.

• For XML Gateway and Concurrent Program interface types

  Each interface contains only one method and it can only be service enabled synchronously by default; therefore, the Interaction Pattern table is neither displayed in the Web Service region for XML Gateway interfaces nor the SOAP Web Service tab for Concurrent Program interfaces.

• For Business Service Object interface type

  Each interface may contain more than one method; therefore, only the Synchronous column is displayed in the Interaction Pattern table for method selection.

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, such as XML Gateway maps, service activities are managed in the Web Service region. For interfaces with the support for both REST and SOAP services, such as PL/SQL, Concurrent Programs, and Business Service Objects, 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:

• Although at a PL/SQL layer, any concurrent programs can be submitted by FND_REQUEST API, Oracle E-Business Suite Integrated SOA Gateway supports calling of different concurrent programs through separate concurrent program services.

• There may be PL/SQL based APIs exposed through the Integration Repository that are not consistent with the synchronous, auto-committed transaction state of the Web Service Framework in Oracle E-Business Suite Integrated SOA Gateway.

• The WSDL generated by Oracle E-Business Suite Integrated SOA Gateway marks schema elements (parameters) and its related schemas as optional or mandatory, based on the method signature of the underlying API. However, runtime behavior may vary based on API internal implementation.

Service Generation in the SOAP Web Service Tab with Overloaded Methods Highlighted

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

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

• Interaction Pattern Table: Selected method names with desired interaction patterns are displayed in the table.

  Note: This table is not displayed if the generated service is an XML Gateway map or a concurrent program.

  If changes on the table are required for a generated service:

  • If the generated service has not yet been deployed, after the modification you must regenerate the service. Upon regeneration, the service definition will be changed to reflect the changes made in the table. You need to modify its web service clients based on the new service definition.

  • If the generated service has already been deployed, you must first undeploy the service, modify the pattern selection, regenerate the service, and then deploy the service again.

    For information on service deployment, see Deploying and Undeploying SOAP Web Services.

• SOAP Service Status (or Web Service Status): After a service has been generated successfully, the service status is changed from 'Not Generated' to 'Generated'.

  Important: Multiple requests to generate web services for an integration interface are not allowed. If service generation is still in progress, then 'Generating' is displayed as the service status and the Generate button is disabled.

• Interaction Pattern: 'Synchronous' is displayed by default in the Web Service region or the SOAP Web Service tab if the selected interface is not a PL/SQL API.

• View WSDL Link: Click this link to view the generated WSDL description for the selected interface.

  If a method is exposed as a serviceable operation with the support of asynchronous pattern, then ASYNCH appears in the WSDL for that method to distinguish it from the rest of the operations generated synchronously. For example, if 'Asynchronous' is selected specifically for the 'CREATE_INVOICE' method within the Invoice Creation API (AR_INVOICE_API_PUB) interface, after service generation, the ASYNCH appears in the CREATE_INVOICE operation for both input and output messages as well as binding.

  ...
  <portType name="AR_INVOICE_API_PUB_PortType">
     <operation name="CREATE_INVOICE_ASYNCH">
       <input name="tns:CREATE_INVOICE_Input_Msg"/>
     </operation>
  </portType>
  <portType name="AR_INVOICE_API_PUB_Callback_PortType">
     <operation name="CREATE_INVOICE_ASYNCH_RESPONSE">
       <input name="tns:CREATE_INVOICE_Output_Msg"/>
     </operation>
  </portType>
  ...
  
  <binding name="AR_INVOICE_API_PUB_Binding" type="tns:AR_INVOICE_API_PUB_PortType">
     <operation name="CREATE_INVOICE_ASYNCH">
       <soap:operation soapAction="CREATE_INVOICE_ASYNCH" /> 
         <input>
           <soap:header message="tns:CREATE_INVOICE_Input_Msg" part="header" use="literal" /> 
           <soap:body use="literal" parts="body" /> 
         </input>
       </operation>
  </binding>
  <binding name="AR_INVOICE_API_PUB_CallBack_Binding" type="tns:AR_INVOICE_API_PUB_CallBack_PortType">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
      <operation name="CREATE_INVOICE_ASYNCH_RESPONSE">
        <soap:operation soapAction="CREATE_INVOICE_ASYNCH_RESPONSE" /> 
          <input>
           ...
          </input>
      </operation>
   </binding>

  For more information about WSDL, see: Reviewing SOAP Service WSDL Source, Oracle E-Business Suite Integrated SOA Gateway User's Guide.

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

Web Service Region with the Generic XML Gateway Service Subregion Highlighted

The Generic XML Gateway Service subregion contains the following fields:

• Web Service Status: This field indicates the current state of the selected XML Gateway interface.

  If the setup is not configured for the generic XML Gateway service, the Web Service Status field is displayed as 'Not Deployed'.

• View Generic WSDL: Click the View Generic WSDL link to display the deployed generic WSDL URL for the selected XML Gateway interface.

  The deployed generic WSDL URL has the following syntax:

  http://<SOA server host>:<SOA Suite managed server port>/soa-infra/services/default/XMLGatewayService!<version chosen while deploying>XMLGateway?WSDL

  • <SOA Suite managed server port>: It is the port of the server where SOA composite is deployed.

  • <version chosen while deploying>: At the time of deployment, deployement version will be asked. Default version value is 1.0.

    For example, http://<SOA server host>:<SOA Suite managed server port>/soa-infra/services/default/XMLGatewayService!1.0/XMLGateway?WSDL.

  After the upgrade to Oracle E-Business Suite Release 12.2, the deployed WSDL URL information has been changed from an earlier release. Therefore, you may have to replace it with the new WSDL URL and service location or address accordingly in web service clients while invoking the generic XML Gateway service.

  The updated WSDL URL is also populated in the ISG: Generic Service WSDL URL for XMLG profile option by default if the setup tasks for generic XML Gateway services are configured properly.

• Interaction Pattern: 'Synchronous' is displayed by default in read-only mode.

• Authentication Type: 'Username Token' is displayed by default in read-only mode.

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

XML Gateway Details Page with Web Service Region Highlighted

Deploying Web Services with Authentication Types

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

• Username Token

  This authentication type provides user name and password in the security header for a web service provider to use in authenticating the users. It is the concept of Oracle E-Business Suite user name/password (or the user name/password created through the Users window in defining an application user).

• SAML Token (Sender Vouches)

  This type is used to authenticate web services relying on sending a user name only through SAML Assertion.

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

SOAP Web Service Tab with Deployed and Active Status Highlighted

The SOAP Web Service tab or the Web Service region for an XML Gateway interface has the following changes:

• The service status is changed from 'Generated' to 'Deployed' with 'Active' state indicating that the deployed service is ready to be invoked and accept new SOAP requests.

• The selected authentication type is displayed.

• Click the View WSDL link to display the deployed WSDL information. It shows the physical location of service endpoint where the service is hosted in soa-infra.

• The following buttons appear if the service has been successfully deployed with 'Active' state:

  • Retire: It disables the active service. The service status is changed to 'Deployed' with 'Retired' state indicating that this deployed service will no longer accept new requests. It also ensures that current running requests are finished.

    Once the service has been successfully retired, the Activate button appears allowing you to activate the retired service. For more information on retiring and activating web services, see:

    • Retiring SOAP Web Services

    • Activating SOAP Web Services

• Undeploy: It undeploys the web service from Oracle SOA Suite back to Oracle Integration Repository. Deployed services can be undeployed with the following reasons:

  • Changes on an interface definition for a deployed service.

  • Changes on interaction pattern for a deployed service.

  • Changes on the Authentication Type field for a deployed service.

  • The original service was corrupt.

  After undeploying the service, make desired changes first (such as interaction pattern or authentication type). Next, regenerate the service, and then deploy the service again.

• Reset: It clears up the deployed service artifact and changes the service status from 'Deployed' with 'Active' to 'Not Generated'.

  For more information, see Resetting SOAP Web Services.

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: 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 SOAP Web Service tab or the Web Service region of an XML Gateway interface, select one of the following authentication types:

   • Username Token

   • SAML Token (Sender Vouches)

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

SOAP Web Service Tab with Reset Button Highlighted

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

SOAP Web Service Tab with Retire Button Highlighted

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 SOAP Web Service tab for the interface with the support for both SOAP and REST services or the Web Service region has the following changes:

• Web Service Status: 'Deployed' with 'Retired' state appears indicating that this deployed service will no longer accept new requests.

• Activate: This action lets you change the retired service back to an active service again.

  For information on how to activate a service, see Activating SOAP Web Services.

• Undeploy: This action lets you undeploy the retired service from an Oracle SOA Suite managed server to the repository. See: Deploying and Undeploying SOAP Web Services.

• Reset: This action lets you reset the retired service to its initial state - 'Not Generated'. See: Resetting SOAP Web Services.

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 SOAP Web Service tab (or in the Web Service region of an XML Gateway interface), 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 runtime. 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 with Retired Status and Activate Button Highlighted

Activating a service will not change its service definition. That is, the selected interaction pattern and authentication type remain the same as they were before.

After activating a service, the following fields are changed in the SOAP Web Service tab of the selected interface (or in the Web Service region of an XML Gateway interface) :

• Web Service Status: This field is changed from 'Deployed' with 'Retired' state back to 'Deployed' with 'Active' state. This indicates that the deployed service becomes available again and is ready to be invoked and accept new requests.

• Retire: This action lets you retire the activated service again. See: Retiring SOAP Web Services.

• Undeploy: This action lets you undeploy the active service from an Oracle SOA Suite managed server to the repository. See: Deploying and Undeploying SOAP Web Services.

• Reset: This action cleans up the service artifact and takes it back to its initial state - 'Not Generated'. See: Resetting SOAP Web 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 SOAP Web Service tab or the Web Service region, 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.

Business Event Details Page with Subscribe Button Highlighted

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 access certain methods in an API through Integration Repository.

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.

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.

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

Enabling Design-Time Log Configuration for SOAP Services

To troubleshoot any issues or exceptions encountered during service generation and deployment life cycle, users who have the Integration Administrator role can enable design-time log for an interface that can be exposed as a SOAP service.

If the design-time log is enabled for an interface with 'SOAP' service type, 'Enabled' is shown as the Log Configuration value in the SOAP Web Service tab. Otherwise, 'Disabled' is displayed instead.

If an interface can be exposed as both SOAP and REST services and that interface has the design-time log enabled for both 'SOAP' and 'REST' service types in two separate configurations, 'Enabled' can be shown in the SOAP Web Service tab and the REST Web Service tab.

SOAP Web Service Tab with Log Configuration 'Enabled' Highlighted

Changing an Existing Log Configuration

To change the design-time log configuration for the selected interface, click Configure next to the Log Configuration field in the SOAP Web Service tab. The Log & Audit Setup Details page appears with the selected interface where the administrator can add a new log configuration or update an existing configuration.

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

For detailed information about how to configure log settings at the service type level of an interface, see Adding a New Configuration.

Viewing Design-Time Logs

If the design-time log is enabled for an interface with 'SOAP' service type, View Log appears in the SOAP Web Service tab allowing you to view both log messages and error messages if occurred during design-time activities. See Viewing Design-Time Logs for SOAP Services.

Viewing Design-Time Logs for SOAP Services

To effectively troubleshoot any issues or exceptions encountered at design time during each stage of service generation and deployment life cycle , error messages and activity information can be logged and viewed through the Log & Error Details page.

Note: These design-time activities include generating, deploying, retiring, resetting, and activating actions for SOAP services.

• If the design-time log is enabled for 'SOAP' service type of an interface, View Log appears in the SOAP Web Service tab for that interface. For XML Gateway interface type that can be exposed as SOAP services only, the View Log appears in the header of the interface details page.

  Clicking View Log lets you view both log messages and error messages if occurred during design time.

• If the design-time log is not enabled for 'SOAP' service type of an interface and errors occurred while performing the design-time activities for that SOAP service, View Error appears instead letting you view the error messages only.

SOAP Web Service Tab with 'View Log' Highlighted

For information on enabling the design-time log for an interface with a desired service type, see Adding a New Configuration.

Viewing Error and Log Details from the View Log Button

Click View Log to display the Log & Error Details page.

Log & Error Details Page with Log Details Region

• Error Details region: If any errors or exceptions encountered during the design-time activities, error messages are displayed in the Error Details region.

• Log Details region: All messages recorded for SOAP service type of the interface are listed in the table. Each log contains log sequence, log timestamp, module, log level, and actual message recorded at the design time.

  Deleting and Exporting Logs in the Log Details Region

  After viewing the log messages, you can delete them if needed by clicking Delete Log in the Log Details region. A warning message appears alerting you that this will permanently delete all the logs retrieved in the region. Click Yes to confirm the action. An empty log table appears after logs have been 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 region to Microsoft Excel and use it later.

Viewing Error Details from the View Error Button

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

Log & Error Details Page with 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 a SOAP service, these errors are recorded and displayed in the Error Details region even if the design-time log for the SOAP service type is not configured for the interface.

Note that the Log Details region will not appear in this page because the design-time log is not configured for the SOAP service type of the selected interface.

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

• For more logging information, see Logging for Web Services.

• For information on adding a new configuration, see Adding a New Configuration.

At runtime during the service invocation, 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 for the 'SOAP' service type, View Error appears instead 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 for a desired service type, View Log appears in the SOAP Web Service tab for that interface.

   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.

Administering REST Web Services Through Integration Repository

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, 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 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:

• Deploy a Service

  A supported interface can be exposed as a REST service through a 'Deploy' action. Note that REST services are deployed on an Oracle E-Business Suite WebLogic managed server, while SOAP services are deployed on an Oracle SOA Suite WebLogic managed 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 REST services can be deployed and undeployed using the Ant script $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml. See: Managing REST Service Lifecycle Activities Using an Ant Script.

Additionally, the administrator can manage security grants through the Grants tab of the interface details page and the Ant script. It assigns grants to specific users to access or invoke the deployed REST services. 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 application 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 user name 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 performed through the Integration Repository user interface, this section includes the following topics:

• Deploying REST Web Services

• Undeploying REST Web Services

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

• Enabling Design-Time Log Configuration for REST Services

• Viewing Design-Time Logs for REST Services

Managing Other Administrative Tasks for REST Services

Similar to managing SOAP service activities, administrators can perform additional tasks in the Administration tab to configure logging, and monitor runtime inbound and outbound REST service invocation messages. See:

• Logging for Web Services

• Monitoring and Managing Inbound Service Invocation Messages Using Service Monitor

• Monitoring and Managing Outbound Service Invocation Messages Using Service Invocation Monitor

Deploying REST Web Services

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.

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="http://<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 Methods or Service Operations

  In the Service Operations table, select one or more methods to be exposed as REST service operations.

  For example, select the CREATE_INVOICE method for the PL/SQL API Create Invoice (AR_INVOICE_API_PUB). After service deployment, only the selected method CREATE_INVOICE will be exposed as a REST service operation.

• Select Desired HTTP Verbs (PL/SQL APIs, Java Bean Services, Application Module Services, Business Service Objects, Open Interface Tables, and Open Interface Views Only)

  For PL/SQL APIs, 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 checkboxes for the desired methods.

  The following table lists the interfaces that can be exposed as REST services and their supported HTTP methods:

  REST-based Interfaces with Supported HTTP Methods

  Interface Type	Supported HTTP Methods
  Concurrent Program	POST only
  PL/SQL API	POST and GET
  Java Bean Service	POST and GET
  Application Module Service	POST and GET
  Business Service Objects	POST and GET
  Open Interface Table (Inbound)	POST, GET, PUT, and DELETE
  Open Interface Table (Outbound)	GET only
  Open Interface View	GET only

  Note: 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 this interface type.

  • For PL/SQL APIs

    REST Web Service Tab for PL/SQL API with GET and POST Methods

    

    You can deploy a PL/SQL API of non-complex type as a REST service operation with the support of the GET and POST methods.

    • The GET checkbox is enabled only if the selected API is a simple data type. The checkbox is disabled if the selected API is a complex data object type.

    The administrator can select desired methods for an operation before deploying a PL/SQL API of a simple data type as a REST service.

  • For Java Bean Services and Application Module Services

    REST Web Service Tab for Application Module Services with GET and POST Methods

    

    If the Java or Application Module method is annotated (rep:httpverb) with a specific HTTP method, then the corresponding HTTP method checkbox is preselected for that method in the table.

    • If the GET HTTP method is not annotated, then the GET checkbox 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 checkbox is still active or enabled by default. This allows the administrator to select the POST checkbox if needed for the Java or Application Module method as a REST service operation before deploying the service.

    For example, if the "Get YMS Organizations" method within the "Accessible Yard Organizations" is annotated only with the POST HTTP method, then the POST method checkbox is preselected for the method. The GET method checkbox that is not annotated for the "Get YMS Organizations" 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 checkbox if the "Get YMS Organizations" 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 Interfaces

    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 checkbox is enabled only if input parameters of the selected interface are of simple data types (String, Number, etc.). The checkbox 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.

    Open Interface Table Details Page

    

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

    Open Interface View Details Page

    

REST Service Security

All REST services are secured by the HTTP Basic Authentication or Security Token Authentication at the HTTP or HTTPS transport level. Before deploying an interface as a REST service, the administrator must ensure that at least one authentication type is selected for use in authenticating users who invoke the REST services.

Note: By default, both the HTTP Basic and Security Token authentication types are selected. The administrator can update the default selection to deploy a service with only one desired authentication type (HTTP Basic or Security Token) if needed.

• HTTP Basic Authentication: This authentication is for an HTTP client application to provide a user name and corresponding password when making a REST request that is typically over HTTPS.

• Security Token Authentication: This token-based 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 user name 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 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 with 'Deployed' Status

• 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 shown. Click the link to display the deployed WADL information.

  It shows the physical location of the service endpoint where the service is hosted.

• Verb (Concurrent Programs Only): This field appears only if the selected interface is a concurrent program.

  'POST' is shown by default in this field as it is the only supported HTTP method for concurrent programs.

• Service Operations: This table displays the list of methods (or procedures and functions) contained in the selected interface in read-only mode.

  • A concurrent program contains only one method. If the selected interface is a concurrent program, then the Included Operations column will be checked for the method that has been exposed as a REST service operation with the POST HTTP method.

  • If the selected interface is an interface type of PL/SQL, Business Service Object, Java Bean Services, or Application Module Services, then the GET and POST columns will appear with the check 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 check 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 check 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.

• REST Service Security: This region displays the selected authentication type (HTTP Basic or Security Token) or both types in read-only mode for the deployed service.

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: '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="http://<hostname>:<port>/webservices/rest/Invoice/?XSD=CREATE_INVOICE_SYNCH_TYPEDEF.xsd" /> 
        </grammars>
        <resources base="http://<hostname>:<port>/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 PL/SQL, Business Service Object, 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 methods. 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 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:

   • Service Alias: Specify service alias information.

   • In the Service Operations table, select one or more methods to be exposed as REST service operations.

     If the selected interface is an interface type of PL/SQL, Business Service Object, Java Bean Services, Application Module Services, Open Interface Tables, or Open Interface Views, select the desired HTTP method checkboxes for the methods to be exposed as REST service operations.

   • In the REST Service Security region, ensure that you select at least one authentication type.

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

Interface Details Page with a Deployed REST Service

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.

To undeploy a REST 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, 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.

• PL/SQL interfaces can be exposed as SOAP services with the support for both synchronous and asynchronous patterns. The security grants given for the selected method names would be applicable to the generated services of both patterns.

• If a selected interface contains overloaded functions, each of them can be uniquely granted through the create grant feature. If you select more than one overloaded function for the grant, an Overloaded column appears in the table with the selected function names checked.

  Create Grants Page with Overloaded Functions

  

Revoking Security Grants

The administrator can revoke security grants in the following ways:

• 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 checkboxes 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 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 that can be exposed as a REST service or 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:

   • Specific User

   • Group of Users

   • All Users

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 a REST service.

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

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

Enabling Design-Time Log Configuration for REST Services

Users who have the Integration Administrator role can enable design-time log for an interface that can be exposed as a REST service. This action records any issues if encountered during the REST service deployment and undeployment activities.

If the design-time log is enabled for a REST service, 'Enabled' is shown as the Log Configuration value in the REST Web Service tab of that REST service. Otherwise, 'Disabled' is displayed instead. If the same REST service can also be exposed as a SOAP service and the 'SOAP' design-time log is also enabled in a separate configuration, then you can find 'Enabled' shown in both the SOAP Web Service tab and the REST Web Service tab.

REST Web Service Tab with Log Configuration 'Enabled'

Changing Existing Log Configurations

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

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

For detailed information about how to configure log settings at the integration interface level, see Adding a New Configuration.

Viewing Design-Time Logs

If the design-time log is enabled for a REST service, View Log appears allowing you to view both log messages and error messages if occurred during the design-time activities. See Viewing Design-Time Logs for REST Services.

Viewing Design-Time Logs for REST Services

Similar to viewing the generate and deploy time logs for SOAP services, the administrator can view design-time logs if available for REST services to troubleshoot issues or exceptions encountered during each stage of REST service deployment lifecycle activities, such as deploy and undelploy actions.

• If the design-time log is enabled for the 'REST' service type of an interface during log configuration, View Log appears in the REST Web Service tab. Clicking View Log lets you view both log messages and error messages if occurred during design time for the selected REST service.

  REST Web Service Tab with 'View Log' Highlighted

  

  Clicking View Log displays the Log & Error Details page containing the following regions:

  • Error Details region: If any errors or exceptions encountered during the design-time activities, error messages are displayed in the Error Details region.

  • Log Details region: All messages recorded for REST service type of the interface are listed in the table. Each log contains log sequence, log timestamp, module, log level, and actual message recorded at the design time.

    You can delete logs if needed by clicking Delete Log in the Log Details region.

    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 region to Microsoft Excel and use it later.

• If the design-time log is not enabled for the 'REST' service type of an interface, View Error appears instead in the REST Web Service tab allowing you to view the error messages only.

  REST Web Service Tab with 'View Error' Highlighted

  

  Clicking View Error allows you to view only the error or exception messages displayed in the Error Details region.

  Note: The Log Details region will not appear in this page because the design-time log is not configured for the REST service type of the selected interface.

  For example, if the administrator receives errors or exceptions while trying to deploy a REST service, these errors are recorded and displayed in the Error Details region even if the design-time log for the REST service type is not configured for the interface.

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

• For information on enabling the design-time log for an interface with the REST service type, see Adding a New Configuration.

• For more logging information, see Logging for Web Services.

At runtime during the service invocation, 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.

Managing Service Life Cycle and Security Grants Using an Ant Script

In addition to managing service lifecycle activities and creating security grants through the Integration Repository user interface, administrators can use an Ant script to perform these tasks through the command line:

• Managing SOAP Service Lifecycle Activities Using an Ant Script

• Managing REST Service Lifecycle Activities Using an Ant Script

• Managing Security Grants Using an Ant Script

Managing SOAP Service Lifecycle Activities Using an Ant Script

An Ant script $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml is used to implement 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.

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

You can use the isgDesigner.xml script in one of the following ways:

• Run the script without arguments

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

  When prompted, enter the arguments.

  Note: Do not enclose any input between double quotes.

• Run the script with arguments, along with the commands

  ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dactions=<comma separated list of operations> -DserviceType=SOAP -DirepNames=<comma separated list of API Names> -Dverbose=<ON|OFF>

  While passing actions and irepNames using this method, be aware of the following conditions:

  • If more than one actions or irepNames are passed as command line argument, enclose them between double quotes. For example,

    -Dactions="method1, method2,.."

    -DirepNames="ECRDTLD,FND_USER_PKG[{function1:SYNC}{function2:}...]"

  • If only one action or irepName is passed as command line argument, then there is no need to enclose between double quotes.

• Run the script by providing a descriptor file, along with the commands, as an input

  ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dfile=<absolute path of service descriptor file> -Dverbose=<ON|OFF>

  The argument values required for processing the design-time activities are provided in the file.

  See Using the Script with an Input Descriptor File for SOAP Services.

Argument Description

Valid arguments for isgDesigner.xml are described as follows:

• actions: Comma separated list of actions to be performed. Supported operations are listed as follows:

  • generate: It generates or regenerates the service.

  • deploy: It deploys the generated service.

  • undeploy: It undeploys the deployed service.

  • activate: It activates the deployed service if it is in 'Retire' state.

  • retire: It retires the deployed service if it is in 'Active' state.

  • reset: It resets the web service status to its initial state - 'Not Generated' and also deletes artifacts from the file system of Oracle SOA Suite server.

  • upgrade: It upgrades a service from Oracle E-Business Suite Release 12.1.x to Release 12.2.

  • postclone: It carries out postclone steps including redeploying the services on the Release 12.2 cloned environment.

  While passing the action names, ensure that they have been given in the order of their life cycle. For example:

  • Incorrect Usage: -Dactions="deploy,generate"

  • Correct usage: -Dactions="generate,deploy"

  Actions 'upgrade' and 'postclone' should be called independently. This means if the 'upgrade' action is given, actions argument should look like -Dactions=upgrade. It is similar to the case with action 'postclone'. More information on how actions arguments are used is described in the following examples:

  • -Dactions="generate,deploy,retire,activate,undeploy,reset"

  • -Dactions=upgrade

  • -Dactions=postclone

  Additionally, if action is 'upgrade' or 'postclone', only 'actions' and 'verbose' arguments will be used. However if you have given other arguments as well, only the three arguments mentioned above will be used.

• serviceType: (SOAP, [REST], BOTH, GRANT): "REST" is the default value for Service Type. Press the Enter key or choose the value "SOAP". To clone both SOAP and REST services, select "BOTH" as the value.

  "GRANT" is used to manage security grants. See: Managing Security Grants Using an Ant Script.

• irepNames: Comma separated list of interface names.

  Use either one of the following syntax for the interface name:

  • interface_name

  • interface_name[{function1:<interactionPattern>}{function2:<interactionPattern>}{function3...}]

    • The colon ":" after each function and before <interactionPattern> is mandatory.

    • <interactionPattern> is optional.

      For example, if <interactionPattern> is not included such as interface_name[{function1:}], then the interaction pattern will be defaulted to "SYNC".

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

    • Supported interaction patterns are SYNC, ASYNC, and BOTH. For example:

      • interface_name[{function1:SYNC}]

      • interface_name[{function1:ASYNC}]

      • interface_name[{function1:BOTH}]

      Passing an unsupported interaction pattern will result in an error.

  Multiple interfaces can be separated by comma and passed as irepName using the following syntax:

  interface_name1[{function1:}],interface_name2,interface_name3[{function1:ASYNC}]

  For example, -DirepNames="ECRDTLD,FND_USER_PKG[{function1:SYNC}]"

• file: Absolute path of the (service descriptor) XML file containing interfaces and actions to be performed on these interfaces.

  For example, -Dfile=/u01/oracle/isg_service.xml

• verbose: [ON|OFF] Default value is "OFF".

  For example, -Dverbose=OFF

Usage Examples

• Sample command for actions other than 'upgrade' and 'postclone' (actions and interface names are being passed):

  ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dactions="generate,deploy,undeploy" -DserviceType=SOAP -DirepNames="ECRDTLD,FND_USER_PKG"

• Sample command for performing design time actions from XML file:

  ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dfile=/u01/oracle/isg_service.xml

• Sample command for action 'upgrade':

  ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dactions=upgrade -Dverbose=OFF

• Sample command for action 'postclone':

  ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dactions=postclone -Dverbose=ON

  Enter Service Type : (SOAP, [REST], BOTH)

Using the Script with an Input Descriptor File for SOAP Services

This section describes how to use a descriptor file with the required argument values to manage the design-time activities.

Example 1 - Generating and Deploying a PL/SQL Service with All Functions and Generating SOAP Services for a Concurrent Program and a Business Service Object

The following descriptor file for a PL/SQL API FND_USER_PKG provides required argument values highlighted in bold text, such as <SOAP_ACTIONS>, <POLICY>, and <ALL_FUNCTIONS/>, indicating that this is to generate SOAP service operations for all the functions contained in the API with synchronous pattern, and then deploy them with SAML Token authentication type.

<INTERFACE>
        <NAME>FND_USER_PKG</NAME>
        <TYPE>PLSQL</TYPE>
        <REST_ACTIONS>
        ...
        </REST_ACTIONS>
        <SOAP_ACTIONS>
                <RESET/>
                <GENERATE>
                <!-- GENERATES ALL FUNCTIONS WITH DEFAULT ITERACTION PATTERN "SYNC" FOR PLSQL-->
                        <ALL_FUNCTIONS/>
                </GENERATE>
                <!-- DEPLOYS WITH GIVEN POLICY "SAML" -->
                <DEPLOY>
                <POLICY>SAML</POLICY>
                </DEPLOY>
                <RETIRE/>
                <ACTIVATE/>
        </SOAP_ACTIONS>
</INTERFACE>

The following descriptor file is used for a concurrent program called INTERFACE5 to generate a SOAP service. Two functions, FUNCTION1 and FUNCTION2, contained in this interface are generated with the default synchronous pattern.

<INTERFACE>
        <NAME>INTERFACE5</NAME>
        <TYPE>CONCURRENTPROGRAM</TYPE> 
        <REST_ACTIONS>
        ...
        </REST_ACTIONS>
   <SOAP_ACTIONS>
                <RESET/>
                <GENERATE>
                        <FUNCTIONS_LIST>  
                                <FUNCTION>FUNCTION1</FUNCTION>
                                <FUNCTION>FUNCTION2</FUNCTION>
                        </FUNCTIONS_LIST>
                </GENERATE>
                <DEPLOY/>
                <RETIRE/>
                <ACTIVATE/>
        </SOAP_ACTIONS>
</INTERFACE>

A similar descriptor file can be used to generate a SOAP service for the business service object (BSO) interface type called INTERFACE6 when the <TYPE>SERVICEBEAN</TYPE> is used, shown as follows:

<INTERFACE>
        <NAME>INTERFACE6</NAME>
        <TYPE>SERVICEBEAN</TYPE> 
<REST_ACTIONS>
...
</REST_ACTIONS>
<SOAP_ACTIONS>
                <RESET/>
                <GENERATE>
                        <FUNCTIONS_LIST>  
                                <FUNCTION>FUNCTION1</FUNCTION>
                                <FUNCTION>FUNCTION2</FUNCTION>
                        </FUNCTIONS_LIST>
                </GENERATE>
                <DEPLOY/>
                <RETIRE/>
                <ACTIVATE/>
</SOAP_ACTIONS>
</INTERFACE>

PL/SQL APIs, Concurrent Programs, and Business Service Objects can be exposed as both SOAP and REST services; therefore, the same descriptor file can include required argument values for REST service design-time activities as well. See: Using the Script with an Input Descriptor File for REST Services.

Example 2 - Generating SOAP Service Operations with Synchronous, Asynchronous, or Both Synchronous and Asynchronous Patterns

In this example, a PL/SQL interface called INTERFACE1 contains six functions or operations. The descriptor file indicates the required task is just to generate SOAP services operations with various interaction patterns.

Specifically, FUNCTION1 and FUNCTION2 contained in the interface are generated with both synchronous and asynchronous patterns (<FUNCTIONS_LIST pattern="BOTH">), FUNCTION3 and FUNCTION4 are generated with asynchronous pattern (<FUNCTIONS_LIST pattern="ASYNC">), and FUNCTION5 and FUNCTION6 are generated with synchronous pattern (<FUNCTIONS_LIST pattern="SYNC">).

<INTERFACE>
        <NAME>INTERFACE1</NAME>
        <TYPE>PLSQL</TYPE>
        <REST_ACTIONS>
   ...
        </REST_ACTIONS>   
        <SOAP_ACTIONS>
                <RESET/>
                <GENERATE>
                        <!-- GENERATES GIVEN FUNCTIONS WITH ITERACTION PATTERN "BOTH" FOR PLSQL-->
                <FUNCTIONS_LIST pattern="BOTH">    
                                <FUNCTION>FUNCTION1</FUNCTION>
                                <FUNCTION>FUNCTION2</FUNCTION>
                        </FUNCTIONS_LIST>
                        <!-- GENERATES GIVEN FUNCTIONS WITH ITERACTION PATTERN "ASYNC" FOR PLSQL-->
                <FUNCTIONS_LIST pattern="ASYNC">   
                                <FUNCTION>FUNCTION3</FUNCTION>
                                <FUNCTION>FUNCTION4</FUNCTION>
                        </FUNCTIONS_LIST>
                        <!-- GENERATES GIVEN FUNCTIONS WITH ITERACTION PATTERN "SYNC" FOR PLSQL-->
                <FUNCTIONS_LIST pattern="SYNC">    
                                <FUNCTION>FUNCTION5</FUNCTION>
                                <FUNCTION>FUNCTION6</FUNCTION>
                </GENERATE>
                <DEPLOY/>
                <RETIRE/>
                <ACTIVATE/>
        </SOAP_ACTIONS>
</INTERFACE>

Example 3 - Generating a SOAP Service for XML Gateway Interface Type

The following example shows a descriptor file that is used to generate a SOAP service for the XML Gateway interface called INTERFACE7. In this example, all the functions contained in this interface are generated with SOAP service operations with the default synchronous pattern.

<INTERFACE>
        <NAME>INTERFACE7</NAME>
        <TYPE>XMLGATEWAY</TYPE> 
   <SOAP_ACTIONS>
                <RESET/>
                <GENERATE>
                        <ALL_FUNCTIONS/>
                </GENERATE>
                <DEPLOY/>
                <RETIRE/>
                <ACTIVATE/>
        </SOAP_ACTIONS>
</INTERFACE>

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

• Obtaining Argument irepNames Usage Information

• Running Diagnostic Tests

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:

• interface_name[{function1:<interactionPattern1>}{function2:<interactionPattern2>}{function3...}]

• interface_name

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

Note: Patterns supported here are described in the following:

• SYNC: This is for synchronous generation.

• ASYNC: This is for asynchronous generation.

• BOTH: This is for both synchronous and asynchronous generations.

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

• Function function1 of interface interface_name will be generated with pattern Pattern1.

• Function function2 of interface interface_name will be generated with pattern 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 processed 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.

Managing REST Service Lifecycle 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 implement 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

You can use the isgDesigner.xml script in one of the following ways:

• Run the script without arguments

  For example, enter ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml

  When prompted, enter the arguments.

  Note: Do not enclose any input between double quotes.

• Run the script with arguments, along with the commands

  ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dactions=<comma separated list of operations> -DserviceType=REST -DirepNames=<interface_name[{function1:<interactionPattern>:<VerbList>}{function2...}]> -Dverbose=<ON|OFF> -Dalias=<Alias>

  For example:

  • ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dactions=deploy -DserviceType=REST -DirepNames=FND_USER_PKG[{TESTUSERNAME:SYNC:POST}] -Dverbose=ON -Dalias=FndUserPkgSvc

  • ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dactions=deploy -DserviceType=REST -DirepNames="FND_USER_PKG[{TESTUSERNAME:SYNC:POST}],FND_MESSAGE[{GET_TEXT_NUMBER::POST}]" -Dverbose=ON -Dalias="FndUserPkgSvc,FndMessageSvc"

  While passing actions and irepNames using this method, be aware of the following conditions:

  • If more than one action or irepName is passed as command line argument, enclose them between double quotes. For example,

    -Dactions="method1, method2,.."

    -DirepNames="FND_USER_PKG[{function1:SYNC:POST}{function2::}],HR_APPRAISALS_API"

  • If only one action or irepName is passed as command line argument, then there is no need to enclose between double quotes.

• Run the script by providing a descriptor file, along with the commands, as an input

  ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dfile=<absolute path of service descriptor file> -Dverbose=<ON|OFF>

  The argument values required for processing the design-time activities are provided in the file.

  See Using the Script with an Input Descriptor File for REST Services.

Argument Description

Valid arguments for isgDesigner.xml are described as follows:

• actions: Comma separated list of actions to be performed. Supported operations are listed as follows:

  • deploy: It generates the REST service artifacts and deploys the generated service.

  • undeploy: It undeploys the deployed service and resets the service status to its initial state - 'Not Deployed'. This also deletes the service artifacts from the Oracle E-Business Suite managed server.

  • postclone: It carries out postclone steps including redeploying the services on the Release 12.2 cloned environment.

  While passing the action names, ensure that they have been given in the order of their life cycle. For example,

  -Dactions="deploy,undeploy"

  Action 'postclone' should be given independently. For example:

  -Dactions="postclone"

  Note that when passing the action 'postclone', only 'actions' and 'verbose' arguments will be used. For example,

  ant -f  $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dactions="postclone" -Dverbose=ON

• serviceType: (SOAP, [REST], BOTH, GRANT): "REST" is the default value for Service Type. Press the Enter key or choose the value "REST". To clone both SOAP and REST services, select "BOTH" as the value.

  "GRANT" is used to manage security grants. See: Managing Security Grants Using an Ant Script.

• irepNames: Comma separated list of interface names.

  Use either one of the following syntax for the interface name:

  • interface_name

  • interface_name[{function1:<interactionPattern>:<VerbList>}{function2:<interactionPattern>:<VerbList>}{funcntion3...}]

    • Angle bracket "< >" represents an optional place value holder.

      • <VerbList> represents the list of verbs separated by "+", such as interface_name[{function1:SYNC:GET+POST}].

        Note: The colon ":" is mandatory in these examples.

        For example, four HTTP verbs (GET, POST, PUT, and DELETE) can be supported for an open interface table 'RAXMTR' with Inbound direction:

        -DirepNames=RAXMTR[{RA_INTERFACE_LINES_ALL:SYNC:GET+POST+PUT+DELETE}]

        If <VerbList> is not included, such as interface_name[{function1:SYNC:}], then the verb list will be defaulted to the supported verbs for the interface.

        Please note that the supported verb for Concurrent Programs is POST only; the supported verbs for Java Bean Services and Application Module Services are all the annotated verbs and POST. For PL/SQL APIs and Business Service Object interfaces, the supported verbs are POST and GET. For Open Interface Tables with Outbound direction and Open Interface Views, the supported verb is GET only.

      • <interactionPattern> represents interaction pattern. For REST services, the supported interaction pattern is SYNC (synchronous) only.

        If <interactionPattern> is not included, such as interface_name[{function1::POST}], then the interaction pattern will be defaulted to SYNC.

        If both optional place value holders are not included, such as interface_name[{function1::}], then the interaction pattern will be defaulted to SYNC and the verb list will be defaulted to the supported verbs for the interface.

        If only interface_name is mentioned, then the all the functions will be generated with the synchronous interaction pattern with the supported verbs.

        Passing an unsupported interaction pattern or verb will result in an error.

  Multiple interfaces can be separated by comma and passed as irepName.

  For example, -DirepNames="oracle.apps.fnd.rep.ws.service.EbsRestLocator[{function1:SYNC:GET+POST}],FND_USER_PKG[{function1::POST}]"

• file: Absolute path of the (service descriptor) XML file containing interfaces and actions to be performed on these interfaces.

  For example, -Dfile=/u01/oracle/isg_service.xml

• verbose: [ON|OFF] Default value is OFF.

  For example, -Dverbose=OFF

• alias: It is mandatory for REST services. If multiple services are deployed, use comma separated alias names.

  For example, -Dalias="FndUserPkgSvc,FndMessageSvc"

• policy: (BASIC, TOKEN, [BOTH])

  "BOTH" is the default value for security policy. Press the Enter key or choose the value "BOTH" for both the HTTP Basic and Token based security authentication types. To deploy a REST service with the HTTP Basic authentication type or Token based security type, select "BASIC" or "TOKEN" respectively.

Usage Examples

• Sample command for actions (actions and interface names are being passed):

  • Deploy 'TESTUSERNAME' contained in the PL/SQL API 'FND_USER_PK' as a REST service operation called FndUserPkgSvc with the POST HTTP verb:

    ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dactions=deploy -DserviceType=REST -DirepNames=FND_USER_PKG[{TESTUSERNAME:SYNC:POST}] -Dverbose=ON -Dalias=FndUserPkgSvc

    Enter Authentication Type(s): (BASIC, TOKEN, [BOTH])

    "BOTH" is the default value for the authentication type. To deploy a REST service with both the HTTP Basic and Token Based security types, select "BOTH" as the value.

  • Deploy the following PL/SQL APIs as REST services using one command:

    • 'TESTUSERNAME' contained in the PL/SQL API 'FND_USER_PK' as a REST service operation called FndUserPkgSvc with the POST HTTP verb

    • 'GET_TEXT_NUMBER' contained in the PL/SQL API 'FND_MESSAGE' as a REST service operation called FndMessageSvc with the POST HTTP verb

    ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dactions=deploy -DserviceType=REST -DirepNames="FND_USER_PKG[{TESTUSERNAME:SYNC:}],FND_MESSAGE[{GET_TEXT_NUMBER::POST}]" -Dverbose=ON -Dalias="FndUserPkgSvc,FndMessageSvc"

    Enter Authentication Type(s): (BASIC, TOKEN, [BOTH])

    "BOTH" is the default value for the authentication type. To deploy a REST service with both the HTTP Basic and Token Based security types, select "BOTH" as the value.

  • Undeploy and then deploy an open interface table 'RA_INTERFACE_LINES_ALL' contained in the 'RAXMTR' open interface as a REST service operation called raxmtr with four supported HTTP verbs:

    ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -DirepNames=RAXMTR[{RA_INTERFACE_LINES_ALL:SYNC:GET+POST+PUT+DELETE}] -DserviceType=REST -Dalias=raxmtr -Dactions="undeploy,deploy" -Dverbose=ON

  • Deploy an open interface view 'EGO_ITEM_SYNC_V' as a REST service called ego with the GET HTTP verb:

    ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -DirepNames=EGO_ITEM_SYNC_V[{EGO_ITEM_SYNC_V:SYNC:GET}] -DserviceType=REST -Dalias=ego -Dactions="deploy" -Dverbose=ON

    Enter Authentication Type(s): (BASIC, TOKEN, [BOTH])

    "BOTH" is the default value for the authentication type. To deploy a REST service with the HTTP Basic security type, select "BASIC" as the value.

  • Clone REST services from an existing 12.2.x environment

    ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dactions="postclone" -Dverbose=ON

    Enter Service Type : (SOAP, [REST], BOTH)

    "REST" is the default value for service type. To clone both SOAP and REST services, select "BOTH" as the value.

• Sample command for performing design time actions from XML file:

  ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dfile=/u01/oracle/isg_service.xml

Using the Script with an Input Descriptor File for REST Services

This section describes how to use a descriptor file with the required argument values to manage the design-time activities for REST services.

Example 1 - Deploying Concurrent Programs as REST Service Operations

The following descriptor file for a concurrent program provides required argument values highlighted in bold text, such as <REST_ACTIONS>, <ALIAS>shipment</ALIAS>, <ALL_FUNCTIONS/>, and <POLICY>, to deploy the method contained in this WSHDSNO concurrent program as a REST service with the POST HTTP method and the HTTP Basic authentication type.

Note that by default Concurrent Programs can be exposed as REST services only with the POST HTTP method and synchronous interaction pattern. Therefore, the argument <ALL_FUNCTIONS/> works the same as the argument <ALL_FUNCTIONS pattern="SYNC"/>, <ALL_FUNCTIONS verb="POST"/>, or <ALL_FUNCTIONS pattern="SYNC" verb="POST"/> in the descriptor file.

<INTERFACE>
  <NAME>WSHDSNO</NAME>
  <TYPE>CONCURRENT</TYPE>
  <REST_ACTIONS>
     <DEPLOY>
       <ALIAS>shipment</ALIAS>
       <!-- GENERATES METHOD WITH DEFAULT VERB "POST" AND DEFAULT INTERACTION PATTERN "SYNC" FOR CONCURRENT PROGRAM-->
      <ALL_FUNCTIONS/>
     <POLICY>BASIC</POLICY>
    </DEPLOY>
    <UNDEPLOY/>
  </REST_ACTIONS>
  <SOAP_ACTIONS>
   ...
  </SOAP_ACTIONS>
</INTERFACE>

Because Concurrent Programs can be exposed as both SOAP and REST services, you can use the same descriptor file to include required argument values for the SOAP service design-time activities as well. See: Using the Script with an Input Descriptor File for SOAP Services.

Example 2 - Deploying PL/SQL APIs, Java Bean Services, Application Module Services, and Business Service Objects as REST Service Operations with Both the POST and GET HTTP Methods

This section explains the descriptor files for PL/SQL APIs, Java Bean Services, Application Module Services, and Business Service Objects REST services with the support for both the POST and GET methods.

Specifically, the REST service alias name is provided in the <ALIAS> argument. All service operations that need to be deployed with both the GET and POST HTTP methods are indicated in the argument <ALL_FUNCTIONS pattern="SYNC" verb="GET,POST"/>, as shown in the following samples:

• PL/SQL APIs and Business Service Objects (Both SOAP and REST Services)

  Similar to Concurrent Programs that can be exposed as both REST and SOAP services, you can use the same descriptor files as explained below for these two interface types to include required argument values for both REST and SOAP service design-time activities. See: Using the Script with an Input Descriptor File for SOAP Services.

  • Example for a PL/SQL API

    Use the following descriptor file that provides required argument values highlighted in bold text, such as <REST_ACTIONS>, <ALIAS>USER</ALIAS>, <ALL_FUNCTIONS/>, and <POLICY>, to deploy all functions contained in this PL/SQL API FND_USER_PKG as a REST service with the POST and GET HTTP methods and Security Token based security.

    <INTERFACE>
      <NAME>FND_USER_PKG</NAME>
      <TYPE>PLSQL</TYPE>
      <REST_ACTIONS>
         <DEPLOY>
           <ALIAS>USER</ALIAS>
           <!-- GENERATES ALL FUNCTIONS WITH DEFAULT VERB "POST" AND DEFAULT ITERACTION PATTERN "SYNC" FOR PLSQL-->
          <ALL_FUNCTIONS pattern="SYNC" verb="GET,POST">
         <POLICY>TOKEN</POLICY>
        </DEPLOY>
        <UNDEPLOY/>
      </REST_ACTIONS>
      <SOAP_ACTIONS>
       ...
      </SOAP_ACTIONS>
    </INTERFACE>

  • Example for a Business Service Object

    The following sample descriptor file is used to deploy a BSO interface INTERFACE6 (with <TYPE>SERVICEBEAN</TYPE>) as a REST service with both the POST and GET HTTP methods as well as Security Token based security. ALIAS6 representing the REST service alias is provided in the <ALIAS> argument.

    <INTERFACE>
      <NAME>INTERFACE6</NAME>
      <TYPE>SERVICEBEAN</TYPE>
      <REST_ACTIONS>
         <DEPLOY>
           <ALIAS>ALIAS6</ALIAS>
           <!-- GENERATES ALL FUNCTIONS WITH VERB "GET,POST" AND ITERACTION PATTERN "SYNC" FOR BSO-->
          <ALL_FUNCTIONS pattern="SYNC" verb="GET,POST">
         <POLICY>TOKEN</POLICY>
        </DEPLOY>
        <UNDEPLOY/>
      </REST_ACTIONS>
      <SOAP_ACTIONS>
       ...
      </SOAP_ACTIONS>
    </INTERFACE>

• Java Bean Services and Application Module Services (REST Services Only)

  The following example uses a descriptor file to deploy an interface type of Java Bean Services called INTERFACE4 (with <TYPE>JAVA</TYPE>) as a REST service with both the POST and GET HTTP methods as well as Security Token based security.

  Specifically, the REST service alias name is provided in the <ALIAS>ALIAS4</ALIAS> argument. All service operations that need to be deployed with the GET and POST HTTP methods are indicated in the argument <ALL_FUNCTIONS pattern="SYNC" verb="GET,POST"/>, as shown below:

  <INTERFACE>
    <NAME>INTERFACE4</NAME>
    <TYPE>JAVA</TYPE>
    <REST_ACTIONS>
       <DEPLOY>
         <ALIAS>ALIAS4</ALIAS>
         <!-- GENERATES ALL FUNCTIONS WITH VERB "GET,POST" AND ITERACTION PATTERN "SYNC" FOR POJO SERTVICES-->
        <ALL_FUNCTIONS pattern="SYNC" verb="GET,POST">
       <POLICY>TOKEN</POLICY>
      </DEPLOY>
      <UNDEPLOY/>
    </REST_ACTIONS>
  </INTERFACE>

Other Usages

The $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml script is a multipurpose script. You can also use it to run the diagnostic tests or download the configuration file from the instance.

• Deploying Generic XML Gateway Services

• Obtaining Argument irepNames Usage Information

• Running Diagnostic Tests

To manage lifecycle activities for SOAP services, see: Managing SOAP Service Lifecycle Activities Using An Ant Script.

Managing Security Grants Using an Ant Script

You can use the same isgDesigner.xml script to manage security grants in one of the following ways:

• Run the script without arguments

  For example, enter ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml

  When prompted, enter the arguments.

  Note: Do not enclose any input between double quotes.

• Run the script with arguments, along with the commands

  ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dactions=<create | revoke> -DserviceType=GRANT -DirepNames=<interface_name[function1:function2:..]> -Dverbose=<ON|OFF> -DgranteeType=<USER | GROUP | GLOBAL> -DgranteeKey=<Grantee Key>

  See Using the Script with Arguments for the Grant.

• Run the script by providing a descriptor file, along with the commands, as an input

  ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dfile=<absolute path of service descriptor file> -Dverbose=<ON|OFF>

  The argument values required for processing the design-time activities are provided in the file.

  See Using the Script with an Input Descriptor File for the Grant.

Argument Description

In addition to some common arguments, such as -DirepNames, -Dverbose, described earlier in Managing REST Service Lifecycle Activities Using An Ant Script, the following arguments are specifically used in isgDesigner.xml for managing security grants:

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

• serviceType (SOAP, [REST], BOTH, GRANT): "REST" is the default value for Service Type. Select the value "GRANT" to create or revoke a 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 (default): This is the default value for the argument. 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/ant/isgDesigner.xml -Dactions=create -DserviceType=GRANT -DirepNames=FND_USER_PKG[CHANGE_USER_NAME:TESTUSERNAME] -Dverbose=OFF -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/ant/isgDesigner.xml -Dactions=revoke -DserviceType=GRANT -DirepNames=FND_MESSAGE,FND_USER_PKG[CHANGE_USER_NAME] -Dverbose=ON -DgranteeType=GROUP -DgranteeKey=FND_RESP|ICX|SYSTEM_ADMINISTRATION|STANDARD

Using the Script with an Input Descriptor File for the Grant

This section describes how to use a descriptor file with the required argument values to manage security grants.

For file mode, you can provide grant information either using granteeKey or using granteeName and granteeSource. granteeName and granteeSource are not available when running the script in console mode.

For example, use the following descriptor file to:

• Create the following three grants.

  • Grant all Oracle E-Business Suite users the access privileges of PROG_APPL_ID, CONC_LOGIN_ID, LOGIN_ID, and APPS_INITIALIZE service operations within a selected interface.

  • Grant the access privilege of CONC_REQUEST_ID service operation to the user group who has the System Administration responsibility only.

  • Grant the access privilege of CONC_REQUEST_ID service operation to the Oracle E-Business Suite user OPERATIONS only.

• Remove the access privileges of the selected interface from all Oracle E-Business Suite users.

<INTEGRATION_REPOSITORY>
  <INTERFACE>
   ...
    <GRANT_ACTIONS>
      <CREATE>
         <FUNCTIONS_LIST grantType="GLOBAL">
          <FUNCTION>PROG_APPL_ID</FUNCTION>
          <FUNCTION>CONC_LOGIN_ID</FUNCTION>
          <FUNCTION>LOGIN_ID</FUNCTION>
          <FUNCTION>APPS_INITIALIZE</FUNCTION>
         </FUNCTIONS_LIST>       
         <FUNCTIONS_LIST grantType="GROUP" granteeName="System Administration" granteeSource="FND_RESP">
          <FUNCTION>CONC_REQUEST_ID</FUNCTION>
         </FUNCTIONS_LIST>        
         <FUNCTIONS_LIST grantType="grantType="USER" granteeKey="OPERATIONS">
          <FUNCTION>CONC_REQUEST_ID</FUNCTION>
         </FUNCTIONS_LIST>  
      </CREATE>
      <REVOKE>
         <ALL_FUNCTIONS grantType="GLOBAL"/>
      </REVOKE>
    </GRANT_ACTIONS>   
  </INTERFACE>
</INTEGRATION_REPOSITORY>