1. Configuring Applications Using Application Composer
  2. Register REST Endpoints

Register REST Endpoints

In the Groovy scripts that you use in Application Composer, you can include calls to both internal and external web services. For each web service that you call in your scripts, you must first register the REST endpoint that you want to access.

Creating a Web Service Reference

To create a web service reference, do the following in Application Composer:

  1. Confirm that you're in an active sandbox session.

  2. In Application Composer, under Common Setup, click Web Services.

  3. Click the Create Web Service Reference icon.

  4. Select REST, then OK.

  5. Enter the name for this web service reference.

    This name is simply an identifier that is used in the list of web services on the Expression Builder's Web Services tab.

  6. Specify the URL of the file location for the web service that you want to integrate with.

  7. If you select an authentication scheme, then specify the required information. For secure communication with a web service, you can use various schemes for authenticating user credentials and ensuring security. The following schemes are supported for web services from Groovy scripts:

    • None

      Select this option to specify that no security scheme is used.

    • Call with basic authentication

    • Propagate user identity using SAML over SSL

    • Propagate user identity using SAML

    • Call using OAUTH

      Don't use this scheme with non-Oracle web service endpoints. This scheme currently supports only resources protected with Oracle Cloud OAuth server.

    For the security schemes that require user name and password credentials, specify a credential key. The web service provider will tell you about the credentials that you must use for a particular web service.

  8. Next, select and configure methods against the resource. You can register the resource operation (GET, POST, and so on) and the associated payload format type (JSON/XML). Only registered operations appear in the Groovy expression builder.

    Selection

    Description

    Method Type

    Select the check box for the method type you want to expose in the Expression Builder.

    • GET

    • PUT

    • POST

    • PATCH

    • DELETE

    For each method you want to expose, specify the following information.

    Method Name

    The name of the method you selected appears here. By default it's the same as the method type (such as POST) but you can change it.

    Format

    Select a format for the method, based on what the selected web service returns.

    • XML

    • JSON

    This information is provided by your web service provider or web service documentation.

    Request Payload

    Specify the object structure of the payload, if needed. You can do this in one of two ways:

    • Directly provide the schema URL that represents the object structure.

    • Provide a code sample in JSON or XML format. This is an optional parameter useful for displaying reference hints in the Expression Builder.

      To obtain a JSON code sample, execute the API externally using a REST client, such as Postman. The request payload in your Postman execution forms the Request Payload for this Code Sample parameter.

    This section is optional.

    Response Payload

    If the method will return a response (for example, GET), specify the response object structure in which you want the response payload to be returned:

    • Schema URL

      A URL that provides a structure for the data but doesn't include any values.

    • Code Sample

      If you don't have a schema available, you can select this option and paste a sample response (for example, from the service documentation) in JSON or XML format into this field. This parameter is useful for displaying reference hints in the Expression Builder.

      To obtain a JSON code sample, execute the API externally using a REST client, such as Postman. The response payload in your Postman execution forms the Response Payload for this Code Sample parameter.

    Note: You must include an entry in the Response Payload field. If you don't, then Groovy returns "null" instead of the response payload. If you don't want to include a response payload, enter { }for JSON or <a/> for XML as the code schema sample.

You can always edit existing web service references, for example, to change the security scheme used or the settings used for a particular security scheme.

After you create a web service reference, the name of the web service appears in the list available on the Web Services tab in the Expression Builder. When you select a web service from the list, you can then select any of the functions provided by the web service for use in your Groovy scripts.

Tip: When managing web service references, click the Refresh icon in the Web Services page to make sure the list is up to date. Read "Refreshing the List of Web Service References" below for information about when you need to click Refresh.

Refreshing the List of Web Service References

If new methods are added for a web service, you must click the Refresh icon on the Web Services page so that the web service reference is updated. Otherwise, the new methods won't be available for the web service in the Expression Builder.

The Refresh icon is applicable whenever the service contract with the client changes. This can result in new methods, in the changing of the signature of existing methods, or in the deletion of existing methods.

You might also want to click Refresh to display any new web service references that have been created in a separate user session.

Configuring Security

Configure security differently, depending on whether you're creating a web service reference to an associated service endpoint or unassociated service endpoint.

When creating a web service reference to an associated service endpoint, such as to Oracle Java Cloud Service - SaaS Extension residing in the same identity domain, the required setup including SSO enablement is completed during association.

  • Learn more about association in the Oracle Cloud Managing and Monitoring Oracle Cloud at http://docs.oracle.com/en/cloud/get-started/subscriptions-cloud/mmocs/managing-associations-services.html.

    To synchronize users between Oracle SaaS and Oracle PaaS (JCS-SaaS Extension), review the steps in https://docs.oracle.com/en/solutions/embed-java-saas-extension-app-in-sales-cloud/synchronizing-oracle-sales-cloud-oracle-hcm-cloud-and-oracle-erp-cloud-user-identities-and-roles-sim.html#GUID-C3F3348C-8C74-4F17-B9CE-0893CE2FA7CC.

When creating a web service reference to an unassociated service endpoint, most likely a non-Oracle Cloud service, do the following setup:

  • Retrieve the server's CA SSL certificate from the service provider. Don't use self-signed certificates.

  • Add the certificate to the OPSS Keystore Service. The Keystore Service enables you to manage keys and certificates for SSL, message security, encryption, and related tasks. You use the Keystore Service to create and maintain a keystore that contain keys, certificates, and other artifacts.

    The customer certificate import isn't required.

  • Use a secure connection (https) and use the default port (443).

  • If basic authentication isn't necessary, then use the SAML over SSL authentication scheme.

    Learn more about Oracle Single Sign-On in the Oracle Cloud Understanding Identity Concepts guide at http://docs.oracle.com/en/cloud/get-started/subscriptions-cloud/ocuid/oracle-single-sign.html#GUID-379DAC22-B3AC-4957-AF60-D45A07CC8598.

Resolving Security Setup Errors

If some security setup hasn't been performed, then you might receive some errors when the web service is called from a Groovy script.

  • A bad encryption error, when message protection is used

  • A PolicyEnforcementException error when message protection security is used.

You must create a service request with Oracle Support to resolve the errors. Retrieve the server's encryption certificate and the issuer certificate from the service provider and attach them both in the service request along with the location and the error details.

Moving Application Changes

You can download the application changes you make in a "source" environment, and upload them into a "target" environment. This can save you time when working with application changes across multiple environments.

To do this, do the following:

  1. Use the Configuration Set Migration page to create a set of all changes and extensions made to an application environment.

  2. Then, download the configuration set and upload it into another environment.

    This is often referred to as configuration set migration, or CSM.

However, web service references created in Application Composer in the source environment won't work in your target environment after the migration. Therefore, after you upload the configuration set to the target environment, you must re-create the web service references using Application Composer in the target environment, as well.

You can also compare your application changes between two environments during the migration process. Use the Configuration Delta Report to do so. This report lets you check for configuration differences so you can easily troubleshoot issues that occur in one environment, but not in another. See Migrate Your Configurations for detailed information.

Related Topics