SOAP Web Service References for Groovy Scripts

In the Groovy scripts that you use in Application Composer, you can include calls to both internal and external SOAP web services.

For each web service that you call in your scripts, you must set up a web service reference that specifies the Web Services Description Language (WSDL) file location and the security scheme, if any, used to access the web service.

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

Select Web Services in the Common Setup pane.
On the Web Services page, click the New icon, then select SOAP.
Specify a name for the web service connection.
Specify the URL of the WSDL file for the web service.

Note: Protected WSDLs aren't supported.
Specify the user and password credentials as required for the security scheme for the web service. Read "Specifying the Security Values for the Web Service" below for information about which schemes are supported.

Note: The WSS security user name and password aren't supported for non-SSL web services due to security issues.

After you create a web service reference, the name of the web service appears in the list available in 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.

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

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.

Specifying Variable Names

When you create a web service reference, you specify a variable name on the Create SOAP Web Service Connection page. This name is simply an identifier that's used in the list of web services in the Expression Builder.

Specifying WSDL URLs

The WSDL file for a web service provides information about a web service that includes the following:

Service. Defines one or more ports for the web service.
Port. Defines an address or connection endpoint to the web service.

For each service and port there can be one or more associated security policies.

To specify a WSDL URL:

On the Create SOAP Web Service Connection page, enter the WSDL file in URL format, for example:
```
http://internal-hosted:7101/MathsWS-Model-context-root/UsernameTokenSecurity?wsdl
```
Click Read WSDL.

The Service, Port, and Security Scheme fields are then populated based on what is found in the WSDL. When there are multiple services and ports defined, the Service and Port fields have the first service and port found in the WSDL selected.
If a different service and port is required for this web service, select the appropriate values in Service and Port.

When you select a particular service and port, a default security scheme is selected based on the security policy defined in the WSDL.

If the port number is omitted, then it's assumed that the service is listening on the default HTTP port number 80.

When registering a WSDL, make sure that the URL is added to the allowlist in the proxy, so that it can be accessed from the Oracle network.

Specifying the Security Values for the Web Service

For secure communication with a SOAP web service, you can use various schemes for authenticating user credentials and ensuring security. The following schemes are supported for SOAP web services from Groovy scripts. Hover over each option to view the associated WSDL security policy.

None
Call with basic authentication
Call with separate user credentials over SSL
Call with separate user credentials and message protection
Propagate user identity using SAML
Propagate user identity using SAML and message protection

Note: If a web service is hosted on the same environment as the Groovy script that calls the web service, then the separate user name and password credentials that you provide as security values are overridden when the flow is triggered. Instead, updates are recorded as made by the signed-in user who actually called the Groovy script, not the user registered to the web service.

On the Create SOAP Web Service Connection page, you specify a credential key for the security schemes that require user name and password credentials. The web service provider will tell you about the credentials that you must use for a particular web service.

Resolving Security Setup Errors

You may receive some errors if some security setup hasn't been performed. For example, you may get a SSL certificate error when you try to create the web service reference. In this case:

Retrieve the server's CA SSL certificate from the service provider, and ensure that the certificate chain is proper on the WSDL host. 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.

Also, use a secure connection (https) and use the default port (443).

You may also receive 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.

For these errors you must also create a service request with Oracle Support to resolve the errors. You must 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 WSDL location and the error details.

Using Worked Examples of Calling Web Services from Groovy

Worked examples of creating web service connections and calling the web service from a Groovy script are provided in separate topics as listed under "Related Links" below.

The topics cover the various security schemes that are supported for calls to both internal and external web services. The topics include information about contacting your administrator to resolve security setup errors where appropriate.

Refreshing the List of Web Service References

If new methods are added for a web service, you must click Refresh 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 action is applicable whenever the service contract with the client changes. This can result in new methods, changing of the signature of existing methods, and 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.

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 changes across multiple environments.

To do this, you will do the following:

Use the Configuration Set Migration page to create a set of all changes and extensions made to an application environment.
Then, download the configuration set and upload it into another environment.

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

See: "Moving Application Changes".

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.