Create REST and Web Service Connectors

You can create connections to exposed REST and web services using Process. Your process applications can communicate and exchange data with these services.

Topics:

• About REST and Web Services

• Create a REST Connector

• Create a Web Service Connector

• Work with Web Service Definition Files

About REST and Web Services

Process applications can communicate and exchange data with local and remote applications that are exposed as either REST or web services.

When considering whether to use REST or web services, keep in mind that some applications support one and some the other, so the protocol decision may already be made for you. As a general rule, use REST services for integration over the web, and use web services for enterprise application integration scenarios. Cloud applications provide open REST APIs for consumers to interact with them and applications running in the cloud typically communicate through REST calls.

REST and web services are client and server applications that communicate over the World Wide Web (WWW) using HyperText Transfer Protocol (HTTP).

For general information about REST and web services, see:

• The W3C home page for the Web Application Description Language (WADL) file:

  www.w3.org/Submission/wadl

• The W3C home page for the Web Services Description Language (WSDL) file:

  www.w3.org/TR/wsdl

• The Web Services chapter of the Java EE 6 Tutorial:

  docs.oracle.com/javaee/6/tutorial/doc/gijti.html

You will need some basic information about the REST or web service you want to connect to. However, you don’t need to know the details of how services are structured.

Connection to a REST Service

To create a connection to a REST service, you need the following service information:

• Definition of the REST service to connect to WADL, RAML, YAML or other

• URLs to the location of the different resources

• Access to these URLs to get the JSON sample used to create the types needed to send and receive data to/from the service

• List of operations to use on each resource

• List of parameters to pass to operations

• For a secure REST service, the user name and password required to access the service

Connection to a Web Service

To create a connection to a web service, you need the following service information:

• Location of the WSDL file, as a local file path or a URL

• Port type and callback port type in the WSDL file to select

• For a secure web service, the user name and password required to access the service

Create a REST Connector

Use the outbound REST connector to call a REST service to retrieve, create, update, or delete data on a web server that supports the REST architecture. The connector enables Oracle Integration to interact with other Oracle Cloud applications via REST, including SaaS and PaaS applications running inside or outside Oracle Cloud. Using the REST Connector editor, you define the resources and operations needed to connect to a REST service, regardless of the description language used to define the service.

Creating a REST connector involves the following main tasks:

• Create the connector, which opens the editor.

• Set connector timeout settings.

• Apply authentication to the connector (optional).

• Add resources to the connector.

• Add operations to resources.

• Specify request and response parameters for operations.

• Specify visibility settings for the connector on the elements palette.

• Implement the REST connector within a process.

For example, you might create an Oracle Integration application that interacts with Oracle Eloqua via REST service calls, in which the application retrieves an email from Oracle Eloqua and updates the email with information from a process.

• The REST connector uses a GET operation to retrieve email content from Eloqua, and a PUT operation to update the email with the response. Business objects contain the sample payload values.

• The process contains two service tasks that act as Eloqua integration points. The process receives the email ID to approve. One service task fetches the email content from Eloqua, using the supplied email ID. After an approval or reject action, the other service task modifies the email content to contain the outcome of APPROVED or REJECTED.

To create, configure, and implement a REST connector:

1. Create a REST connector.
   1. On the Application Home tab, click Integrations and select the Integrations view.
   2. Click Link to an Integration and then select Create a REST connector.

      Optionally, click Create, then click External, and then select REST.

   3. In the Create REST Connector dialog box, enter a name and base URL for the REST service, and click Create.
      The Rest Connector editor opens, with expandable Configuration and Resources sections. The Configuration section displays the base URL you specified.
   4. Click Edit to expand the connector’s configuration settings.
2. In the General tab, set timeout settings for the REST connector (optional).

   
   Description of the illustration general_tab_rest.png

   1. In the Read Timeout field, specify the timeout in milliseconds to wait to read data from the host.
   2. In the Connection Timeout field, specify the timeout in milliseconds to make the initial connection.
3. In the Security tab, apply authentication to the REST connector (optional).

   By default, no security is configured. You can apply HTTP basic authentication, which provides access control to web resources by requiring a user name and password when making requests.

   
   Description of the illustration security_tab_rest.png

   1. In the Security Type field, select APP Id - Basic Authentication to apply basic authentication to the connector.
   2. Complete the keystore credential fields that display. To create a new key, select New Key and enter a key name, user name, and password.
   3. Click Apply to save the configuration settings.

   Note that Apply is active only when there are changes to save.

   Want to learn more about managing credentials? See Configure Credentials for Web Services.

4. Add resources to the connector.

   A resource contains one or more operations that control data by performing basic create, read, update, and delete operations (CRUD) on resources using standard HTTP method requests.

   
   Description of the illustration weath_connect1.png

   1. At the top of the Resources section, click Add. Click the new resource that was added to the Resources list to expand it.
   2. Enter a name for the resource. You’ll select this resource name when implementing a service task.
   3. In the Path field, identify the resource path within the base URL.
   4. If needed, duplicate (clone) and delete resources, and undo and redo changes to them, using options in the Resources section. Duplicating a resource can be useful when configuring similar resources.
5. Add operations to resources.
   1. In the Operations section, click Add.
   2. Select an HTTP method to add (GET, PUT, POST, PATCH, DELETE, or HEAD). The new operation is added to the Operations list, along with its name and path.

      
      Description of the illustration weath_connect2.png

6. Specify request and response parameters for operations.
   1. In the Operations list, select an operation to expand it. If needed, make changes to the operation’s Type, Name, and hierarchical Path fields. Optionally, enter a description in the Documentation field.
   2. Click the Request and Response tabs to view the operation’s parameter and body fields. The HTTP method you selected determines the request and response message combination to complete for the operation. An asterisk displays if one or more required fields on the tab need to be completed.

      Refer to the table below for required and optional parameters for HTTP methods. Information in this table is based on the Methods definition section of the HTTP/1.1 protocol definition.

      HTTP Method	Description	Request Message-Body	Response Message-Body
      GET	Retrieve information from a resource	Optional	Yes
      POST	Create a resource	Yes	Optional
      PUT	Completely update an existing resource	Yes	Optional
      PATCH	Partially update an existing resource	Yes	Optional
      DELETE	Delete a resource	Optional	Optional
      HEAD	Identical to a GET except that no message body is returned in the response	Optional	No

   3. In the Body field, add or select a business object to store the message data. You can create business objects based on JSON files for REST operation payloads. To create a business object by importing or pasting a JSON sample, click Create Business Object , and complete the fields in the Import Business Object from JSON dialog box, uploading or pasting JSON sample text, and clicking Import. The JSON text is validated, and if invalid, an error displays.
      Ensure that the JSON output of the REST connector does not contain elements that start with a number or contain spaces. These elements may throw up a failed mapping error during runtime when converted to XML. Element names are case sensitive, and must start with a letter or underscore.
   4. When you select a business object in the Body field, you must also specify the message’s media type in the Media type field. Oracle Integration supports application/json.
   5. In the Parameters table, configure one or more parameters for the operation. Click an empty row to add a line, and complete name, style, and description fields. Depending on the selected method, supported style options include template, header, body, and query. When you add, edit, or remove a parameter token in the operation’s path (for example, {Id}), its corresponding template parameter is automatically created, edited, or deleted.
   6. Click Apply to save the operation. Apply is active only when all required information has been entered.
7. In the Visibility tab, specify visibility settings for the connector on the elements palette.

   
   Description of the illustration visibility_tab_rest.png

   1. Click the Show on Palette icon to hide or display the connector on the elements palette. The connector is set to show on the palette by default.
   2. Select:

      • Show connector to display the connector on the palette.

      • Show resources to display the connector resources on the palette.

   3. Click Customize display... to customize the name of the connector or resource to be displayed in the palette. If you choose to display a connector resource, you can choose the display name for each resource to be displayed in the palette.

      
      Description of the illustration display_resource.png

8. Implement the REST connector within a process.
   1. In a process, expand the Integrations flow element, and drag and drop the connector you want to use onto the canvas.
   2. Using data association, configure input and output for the connector. For example, if the REST connector uses a GET operation to retrieve email content from Eloqua, and a PUT operation to update the email with the response, configure the business object to store the values as they're changed by the service calls.
   3. If you have chosen not to display the REST connector in the palette, you can implement it in one or more service tasks within a process.

      In this step, configure one or more service tasks to call the REST service, perform an operation and store data changes in the business object. See Invoke Integrations, REST, and Web Services. Configure data association to pass new values (such as the body message and template) as input and output to the service task.

   4. Add or open a service task in the process. In its properties, implement a service call to a REST service. Select the REST connector, resource, and operation to call.
   5. Using data association, configure input and output for the service task. For example, if the REST connector uses a GET operation to retrieve email content from Eloqua, and a PUT operation to update the email with the response, configure the business object to store the values as they're changed by the service calls.

      To delete a REST service connector, click its delete icon on the Integrations page. You can’t delete a REST service connector that is being called by a service task.

Work with Web Service Definition Files

From the Definitions view of the Integrations page, you can import a web service definition (WSDL) file, upload a new version of the file, and add a new web service connector file based on a specific port type.

On the Application Home tab, click Integrations and then click the Definitions view option.

Import a WSDL

You can use this import feature to update current versions of WSDL files. However, updating your WSDL files using the import feature is different from the update feature you can find in the Definitions — Details view where you can only update the current WSDL file. When updating WSDL files using the import feature you update the WSDL file and XSD dependencies contained in the ZIP file or imported through a remote URL.

To import a WSDL:

1. Click Import to open the Upload Web Service Definition File dialog box.

2. Select one of the following options:

   • Upload from file: Click Browse to browse for a WSDL or ZIP file.

   • Use URL: Provide the URL for your WSDL or Zip file.

3. Click Validate, and then click Upload.

   After clicking Validate a summary of the files to be added are shown if the validation is successful.

   Note:

   If validation is unsuccessful, instead of showing a summary of the files, the validation errors or warnings are displayed. Validation warnings occur if some of the files that you want to upload override exiting ones. In this case you can upload and override existing files. Whenever an unexpected error occurs, the error is logged in the server log and the upload is cancelled. You can’t import files that fail validation.

When you accept the import by clicking Upload, the operation is committed and the files are uploaded to the application and shown in the Definitions view of the Integrations page.

Upload a New Version of a WSDL

To upload a new version of a WSDL:

1. Click the name of the WSDL that you want to override.

2. Click the Options menu and then select Upload New Version to open the Upload New Version dialog.

   

3. Select one of the following options:

   • Upload from file: Click Browse to browse for a WSDL or ZIP file.

   • Use URL: Provide the URL for your WSDL or Zip file.

4. Click Validate and then click Upload.

   After clicking Validate a summary of the files to be added are shown if the validation is successful.

In certain business cases, you may need to update a WSDL (SOAP integration) with changes that are incompatible with the current WSDL.

An incompatible WSDL (SOAP integration) can include changes like:

• Port type (that is being used in the current WSDL) has been removed
• Some operations have been removed from port type
• Some elements have been updated to new types or removed from (XSD) schema

While updating a WSDL with incompatible changes, you get warning messages to indicate the impact of the changes. After you have updated a WSDL with incompatible changes, validate your application and fix any errors that may have occurred due to the update.

Add a Web Service Connector

To add a new web service connector based on a specific port type:

1. Click Add to open the Add Service Connector dialog. Enter a name and select the port type. You can also select a callback port type if required.

2. Expand Advanced and provide the following information, and then click OK to add the new web service connection.

   • Read Time Out: Specify the time out for reading the WSDL file in milliseconds.

   • Connection Time Out: Specify the time out for connecting to the web service in milliseconds.

   • Security: Select None, APP Id – Basic Auth, APP Id – Username Token, or APP Id – Username Token With Message Protection from the drop-down list.

     See Apply Message Security to Integrations.

   • Certificate: If the Security is set to APP Id — Username Token With Message Protection, select New Certificate Alias from the drop-down list and click Add Certificate to upload a certificate.

     See Manage Security Certificates During Design Time.

   • Keystore Credential: If Security isn’t set to None, select a key from the drop-down list.

     You can also select [New Key] and type a Name, Username, and Password. For an existing key, the Username and Password values are automatically populated.

     Want to learn more about how to add credentials? See Configure Credentials for Web Services.

Prepare Local WSDL Files Containing Remote References

If a WSDL file has dependencies on remote schema files, you can download the files and set up local references. Note that this step is needed if creating from a local file only. If creating from a remote URL, Process handles remote references for you.

You must follow the same steps for a process exposed as a web service or for a web service created outside of Process.

To prepare a WSDL file with remote references for use in a web service connection in Process:

1. Create a root directory with two subdirectories named WSDLs and Schemas.
   You can create additional subdirectories of WSDLs and Schemas, as long as all files under WSDLs are WSDL files and all files under Schemas are schema files.
2. If the WSDL file is only accessible using a URL, download it and copy it to the WSDLs directory.
3. If the WSDL file has an extension other than .wsdl, such as .xml, rename it and give it a .wsdl extension.
4. Open the WSDL file in a text editor.
5. Search the WSDL file for URLs that reference schema (.xsd) files.
   For example, a schema file reference might look like this: schemaLocation="http://www.example.com/ExampleService/ExampleSchema.xsd"
6. Download each schema file and copy it into the Schemas directory or a subdirectory of Schemas.
7. In the WSDL file, change each schema file reference to refer to the Schemas directory.
   For example, an edited schema file reference might look like this: schemaLocation="/Schemas/ExampleService/ExampleSchema.xsd"
8. Save and close the WSDL file.
9. Zip the root directory that contains the WSDLs and Schemas directories.
   Make sure the zipping process doesn’t create any extra files in the .zip file. The .zip file must contain only WSDLs and Schemas directories and subdirectories that in turn contain only WSDL and schema files.

Use the resulting .zip file to create a connection to the web service. See Create a Web Service Connector.

Use SOAP Headers in Data Associations

Create data inputs and outputs based on headers specified in the WSDL of a SOAP connector. The headers get exposed through the SOAP connector and the header values can be used for mapping input and output data while configuring data associations in the process.

1. Create a SOAP integration that has headers specified in its WSDL.

   See Developing Integrations with Oracle Integration in Using Integrations in Oracle Integration Generation 2.

   For example, we have created an integration that uses a WSDL (as shown below) with header.

   
   Description of the illustration wsdl-header.png

   In the message of the header, there are header values such as userId, technicalUserId, and sessionId. These values can be used during data association.

2. Use an active integration in a process by creating a connector.
   1. On the Application home tab, click Integrations.
   2. In the Use an Integration dialog box, browse and select the integration you created with the WSDL containing the header.
   3. Click Create.
3. Call the SOAP connector in a process.

   You can do this either directly from the Integrations flow element (as shown in the steps below) or through a service task that calls the SOAP endpoints in the process .

   1. In a process, expand the Integrations flow element in the Elements palette.
   2. Drag and drop the connector into the process flow in the canvas.
4. Configure data associations using the header values as input and output data.

   For example, map InputText to userID (header value) and map InputText1 to technicalUserId (header value).

   
   Description of the illustration wsdl-header-da.png

See Configure Integrations.