Before You Begin

This 15-minute tutorial shows you how to create a simple integration from scratch and use it within a process application.

Background

Do you want to call a web service or access another application from within your process? If so, create an integration.

Integrations enable you to easily access applications and services across your enterprise and beyond. Using integrations, you can seamlessly provide all essential information to process users for executing tasks in an application.

Let’s create a simple application that uses a REST integration to fetch real-time weather data for a city. When prompted, you enter a city’s name and the application displays the weather data for it. Using this example, we'll explore all the steps involved in building an integration—from creating and configuring to activating and testing it on the server.

What Do You Need?

• Access to an instance of Oracle Integration.
• Sign-in credentials (user name and password) assigned to the developer role. See Oracle Integration Roles and Privileges in Administering Oracle Integration.
• API key to access an external application and fetch the weather data. Generate a new key by signing up here: https://developer.worldweatheronline.com/signup.aspx.

Create a Simple Application

First, let’s create a process application that uses your integration, then create the integration within it.

1. Create an application.
   In the Integration navigation pane, click Processes. On the Process Applications page, click Create and select Create an Application. Enter a name (WeatherData) and click Create.
2. Create a process.
   In the Create a Process pane, select Start with a form, enter a process name (Weather Process), and click Create.
3. Add a human task.
   On the Weather Process tab, expand Human on the palette, drag an Approve element to the process, and drop it after the start event.
4. Rename the flow elements.
   Double-click the names of the flow elements and rename the start event to Input City and the human task to Display Result.

   

5. Add a web form.
   Select the Input City element, click Menu and select Open Properties. In the Title field, enter a name (Weather Process) to display for the application.

   Click Create New Form next to the Form field. Enter InputCityWebForm in the Name field, select the Open Immediately check box, and click Create.
6. Add an input field to the web form.
   From the Basic palette, drag and drop an Input text control onto the canvas. Select the control and, in the Properties pane, edit its Name field to inputcity and its Label field to Enter City.
7. Add a presentation to display results.
   Click the form outside a control. On the Form tab, click Add Presentation next to Presentations. Enter a name for the new presentation (Result), select [From scratch] in the Based on field, and click Create.
8. Save the application.
9. Return to the process by clicking the Weather Process tab. Open the properties for the Display Result human task. Click Browse next to the Form field and select InputCityWebForm. In the Presentation field, select Result. Additionally, change the name of the actions in Action field from APPROVE,REJECT to OK,CANCEL.

Create a REST Integration

Now, create a REST connector to communicate and obtain weather data from an external application that is exposed as a REST service.

To create a REST connector:

1. In the Application navigation pane, select Integrations.
2. In the Integrations page, click Create, select External, and then select REST.
3. In the Create REST Connector dialog, enter a name for the connector (WeatherConnector), enter the following example address in the Base URL field, uncheck Open Immediately, and click Create.
   Base URL: http://api.worldweatheronline.com/premium/v1/weather.ashx

View and Edit the Connector’s Configuration Settings

Click the REST connector you just created to configure it. In the Rest Connector Editor:

1. Click Edit to expand the Configuration section.
2. In the General tab, verify the base URL you specified previously, and optionally edit the connector’s time out settings.
3. In the Security tab, you may apply authentication to the connector. For simplicity, we’ll not use authentication in this example.
4. In the Visibility tab, you can control your connector’s visibility on the Process Elements palette. We use the default settings in this example, that is, this connector is visible on the Elements palette.
5. Click Apply to save the changes you made (if any) in the Configuration section.

Add Resources to the Connector

A resource contains one or more standard HTTP method requests (such as GET, PUT, DELETE, and so on) which perform create, read, update, or delete operations on the resources at the source application or service. To add a resource:

1. Click Add in the Resources section.
2. Click the resource to expand it. Optionally, edit the name of the resource.
3. In the Operations section, click Add to add an operation to the resource and select GET operation.
4. Click the operation to expand it. Use the default values for the operation’s Type, Name, and hierarchical Path fields. Enter a description in the Documentation field.

Specify Request and Response Parameters for the Operation

Use the Request and Response tabs to edit the operation’s Parameters and Body sections.

1. Select the Request tab and enter the following parameters:

   

   These are the parameters you must pass to successfully retrieve the weather data from the source application used in this example. They contain the following information:

   • q: Holds the location information that you specify.
   • format: Holds the information about the output format in which the data is to be returned. For simplicity, we use JSON in this example
   • key: Holds the API key required to access the example application.
2. Click the Response tab to switch to the Body section.
   Here, you can use existing business objects or create new business objects based on JSON files to hold the response from external applications.
3. Add a new JSON business object for this example.
   • Click Create business object . In the resulting dialog, enter a name for the business object (WeatherObject), select Instance, paste the following sample JSON response into the dialog, and click Next. The dialog generates a JSON schema based on the sample you entered.
     JSON Sample: {"data":{"request":[{"type":"Zipcode","query":"33458"}], "current_condition":[{"observation_time":"09:55 AM","temp_F":"70", "windspeedMiles":"6","precipMM":"0.2","humidity":"60","visibility":"16", "pressure":"1020","cloudcover":"50","FeelsLikeF":"70"}]}}
   • Click Import to create the business object.
4. Click Apply to save your changes to the Resources section.

Use the Integration in Your Application

Now let’s use this REST integration in the process you created previously.

1. Return to the process by clicking the Weather Process tab.
2. Expand Integrations on the Elements palette, drag the REST integration you created (WeatherConnector) to the process, and drop it before the Display Result task.

   

3. Configure the integration element.
   • Select the element, click Menu , and select Open Properties. In the resulting pane, leave the Service Call option selected in the Type field and click Configure next to it.
   • In the Configure dialog, select REST, browse for the REST connector you created, choose the connector’s resource and operation, and click OK.

Set Up the Output Web Form

Notice that, previously, you created a presentation to display the result but didn’t add controls to it. To add controls to the Result presentation:

1. Select the Display Result human task, click Menu , and select Open Form.
2. Switch to the Result presentation through the drop-down menu.
3. From the Business Types Palette, drag and drop BusinessData.WeatherObject onto the form’s canvas.
4. Optionally, rename the labels of the controls.
5. Click Save.

Map Data to and from the Integration

Define how the data flows in and out of the integration element.

1. On the Weather Process tab, view data association for the start activity and the human task. In these cases, data association was automatically configured for you.
   • Select the Input City element and click Data Association in the toolbar. Expand the values in both side panes. Notice that the value entered into the web form is written to a data object called inputCityWebFormDataObject. Click Cancel.

     

   • Select the Display Result element and click Data Association in the toolbar. Notice that for input, the same data object (inputCityWebFormDataObject) is used to write values back to the web form. Click Cancel.
2. Configure the input and output for the integration element. The integration needs to use the input value (city) contained in inputCityWebFormDataObject and store the response from the external application in the same data object.
   • Open data association for the WeatherConnector element. With the Input tab selected, expand the values in both side panes, and perform the following mappings:

     

   Note: For the format and key parameters of the connector, you pass constant strings. You pass "json" as format because you have previously defined a JSON business object to hold the response, and you pass a valid key obtained in advance to access the external application.
   • Select the Output tab and map the values as follows:
   body.data.current_condition to inputCityWebFormDataObject.weatherObject.data.current_condition
   body.data.request to inputCityWebFormDataObject.weatherObject.data.request

   

3. Click Apply.

Test Your Integration

Let’s run the application in test mode as an end user.

1. From the toolbar, click Test.
2. On the Test Application tab, click Activate. In the Activate to Test dialog, leave the Add Me to All Roles check box selected and click Activate.
3. After the application activates successfully, click Try in Test Mode. When the new browser tab opens displaying runtime options, click Weather Process from the My Apps page.
4. In the form, enter the name of a city (for example, Madrid) and click Submit.
5. Click My Tasks and open your new task. The output web form displays the weather data for the city you entered.
6. View the data.

   

What's Next

Congratulations! You have now completed all the tasks and successfully created and activated your first process application with an integration. However, for the application to be available to the end users, roles need to be assigned to the users. Roles define what end users can do, such as whether they can start the application and what tasks they’re assigned. After your application has been activated to a production server and is ready for use, contact your administrator to assign roles for the application.

Want to Learn More?

• Create REST and Web Service Connectors in Using Processes in Oracle Integration.
• Assign and Manage Roles in Using Processes in Oracle Integration.