Talend ESB REST Client

Talend Connectors for BPM Reference Guide

EnrichVersion
6.2
task
Design andĀ Development
EnrichPlatform
Talend Studio

The Talend ESB REST Client connector calls a REpresentational State Transfer (REST) Web service provided by Talend ESB. This makes it a primary connector to leverage the Talend ESB Providers and Routes from within a process.

This connector provides support for:

  • Request/Response and One Way service operations.

  • Security types:

    • Basic HTTP authentication

    • Digest authentication

  • Service Activity Monitoring (using the Talend ESB SAM Server)

  • Service Discovery (using the Talend ESB Service Locator)

  • Business Correlation

Configuring the ESB REST Client connector

To configure the Talend REST Client connector, proceed as follows:

  1. If you have not added the connector, select the Talend ESB REST Client connector from the connector list;

    If you have already added it to the process or a task of the process, select the connector and click Edit in the Connectors tab of the General view for the process or task.

    A configuration wizard opens to guide you through the configuration.

  2. Complete the following information and click Next to go to the next step.

    Field / option

    Description

    Name *

    Name of the connector.

    Description

    Description of the connector.

    Select event *

    Event that triggers the connector:

    • enter - event occurs when the flow enters this process step;

    • start - event occurs when the flow starts;

    • suspend/resume - event occurs when the user presses the suspend/resume button on the web-form;

    • finish - event occurs when the flow exits this process step

    If connector fails...

    Action to take if the connector fails consuming the Web service:

    • Put in failed state - puts the step in failed state and terminates the process;

    • Ignore error and continue process - continues the process ignoring the error;

    • Throw error event - throws a user-specified error.

    Named Error

    Specifies the name of the error which should be thrown if the connector fails. Available only if the Throw error event option is selected.

    Note

    Fields followed by an asterisk (*) are required.

  3. The following step of the wizard allows you to define the properties of the REST service to be called from within the process.

  4. Fill in the following information and click Next to go to the next step.

    Field / option

    Description

    Endpoint URL

    URL of the REST service to be invoked. When the Use Service Locator check box is selected on the next page of this wizard, this field is not used and the URL of the REST service will be obtained from the Service Locator server automatically.

    Relative Path

    Relative path of the REST service to be invoked.

    If Use Service Locator is disabled: You can enter any of the first part of the address in the Endpoint URL field, and the second part in the Relative Path field.

    If Use Service Locator is enabled: The URL part will be given by the Service Locator. In this case, you need to know the URL part, and specify the rest part in Relative Path. This depends on the service you request.

    Method

    From this list, select an HTTP method that describes the desired action. The specific meanings of the HTTP methods are subject to definitions of your Web service provider. Listed below are the generally accepted HTTP method definitions:

    - GET: retrieves data from the server end based on the given parameters.

    - POST: uploads data to the server end based on the given parameters.

    - PUT: updates data based on the given parameters, or if the data does not exist, creates it.

    - DELETE: removes data based on the given parameters.

    Accept Type

    Select the media type the client end is prepared to accept for the response from the server end.

    Available options are XML, JSON, and ANY. When ANY is selected, the response message can be of any type and will be transformed into a string.

    Query

    Specify the URI query parameters in the form of name-value pairs.

    This option is mostly used with the GET method.

    Request

    This option is required only when the POST or PUT HTTP method is selected.

    Content Type: Select XML, JSON, or FORM according to the media type of the content to be uploaded to the server end.

    Request: Payload of the request message.

    Security

    Use Security: Select this check box if authentication is required on the REST server end. Once selected, you need to provide your username and password.

    Security Type: choose a security type between Basic HTTP and Digest.

    Headers

    Type in the name-value pair(s) for HTTP headers to define the parameters of the requested HTTP operation.

    Timeouts

    Connection timeout: Set the amount of time, in seconds, that the client will attempt to establish a connection before it times out. If set to 0, the client will continue to attempt to open a connection indefinitely. (default: 30)

    Receive timeout: Set the amount of time, in seconds, that the client will wait for a response before it times out. If set to 0, the client will wait indefinitely. (default: 60)

  5. This step allows you to use or not the Talend ESB Infrastructure services for this consumer request.

  6. Fill in the following information and click Next to go to the next step.

    Feature

    Field / option

    Description

    Service Locator

    Use Service Locator

    Select this check box to enable the Service Locator feature.

    With this feature enabled, the provider endpoint (URL) will be requested at runtime from the Talend ESB Service locator. In this way, the process is loosely coupled to the provider so the provider can be used based on availability, regardless of where they are hosted.

     

    Service Name

    Name of the service to be invoked.

     

    Service Namespace

    Namespace of the service to be invoked.

     

    Service Locator Properties

    Optional: additional metadata can be set as a filter for the list of service providers. For example, if the provider uses a locationmetadata to specify the data center location they are running with (values EU and US for example), a row in this table with 'locator' values EU would only retrieve an endpoint where the provider is located in a EU data center.

    Service Activity Monitoring

    Use Service Activity Monitoring

    Select this check box to enable monitoring the service calls with Service Activity Monitoring. In this way, request from the process to a ESB Provider is also tracked as a Service Activity event.

     

    Service Activity Monitoring Custom Info

    The table allows you to provide additional user-defined metadata which is stored together with the Service Activity Event.

    Business Correlation

    Use Business Correlation

    Select this check box to enable the Business Correlation feature. This will pass a correlation ID to the service it calls via the request HTTP header, so that chained service calls will be grouped under this correlation ID.

    With this feature enabled, the connector will also extract the correlation ID from the response HTTP header and store it in the process variable specified in the next step for further use in the process.

     

    Correlation ID

    Specify your correlation ID or select a process variable for your correlation ID to pass to the service the connector calls. If you leave this field empty, a random UUID will be generated automatically at runtime.

  7. Set the parameters as follows to map the Web service response to variables/data types of the process, and then click Finish.

    Field

    Description

    Connector output

    Allows you to select the connector output or its part for storing it in the specified variable. The list also allows you to open a dialog box which provides a structured view of the response parameter.

    Destination variable

    Variable where the connector output should be stored. With the Create data... option, you can create new process variables within this dialog box.

Scenario 1: Retrieving data from a REST service from within a process using the Talend ESB REST Client connector

This scenario explains how to configure the Talend ESB REST Client connector to retrieve data from a REST-ful Web service provided through a demo Job of Talend ESB.

Prerequisites:

  • You have imported the ESB demo project your Talend Studio.

  • You have launched the demo Job DemoREST in the Integration perspective of your Talend Studio, and you can see information like the following when entering http://localhost:8090/services/customers in your Web browser:

Creating a new process and adding a variable for the input data (Step one)

  1. Create a new process and select the Step1 element in the process model.

  2. From the General view of the Details panel, select the Data tab and click the Add... button.

  3. Name the variable Customer_ID, select the Auto-generate form check box. You can also specify the default value in the Default value field.

  4. Click Finish. A form allowing you to enter the value for the Customer_ID variable will be generated.

Adding and configuring the Talend ESB REST Client connector

  1. From the General view, select the Connectors tab and click the Add... button. A window opens.

  2. Select Talend > Talend ESB REST Client then click Next to open the connector configuration wizard.

  3. Give the connector a name, ESB_RS_getCustomerInfo for example, and click Next.

    The REST Service configuration page opens.

  4. Configure the REST Service.

    • Fill the Endpoint URL field with the URL of the REST Service implement by the DemoREST Job, http://localhost:8090/services/customers in this example.

    • Fill in the Relative Path field with ${customer_ID}, which corresponds to the variable you just created. This allows you to enter the relative path on your Web browser when the process is executed.

    • From the Method list, select GET. This operation will retrieve data from the REST service to be called.

  5. Click Next. The Configure TESB Feature page opens to let you configure service locator information, service activity monitoring, and business correlation. As we do not use any of these options in this example, simply click Next to proceed with connector output mapping.

  6. Click the Create data button to open the [Add a new variable] dialog box.

  7. Name the variable Customer_Info, clear the Auto-generate form check box, then click Finish to close the dialog box.

  8. Click Finish to close connector configuration wizard.

Next, you have to display the Customer_Info variable in a process Web User Interface to show the returned information.

Configuring response display (Step two)

  1. Add a new task (Step 2) and an end event to the process model.

  2. Click the Step2 icon in the process model, then click the tools icon on the bottom-left corner.

  3. Select the Human icon. The task type is changed to Human.

  4. From the General view for this new human task, select the Actors tab and click the Choose... button.

  5. Select Initiator and click Finish to close the window.

  6. From the Application view, click the Entry Pageflow tab and click the Add... button next to the first table.

  7. Select the Create a new form option and click Next.

  8. On the next step, configure which variables will be shown on the form. Select the customer_Info check box and click Finish. A newly created form displays the customer_Info variable.

Running the process and retrieve customer information from the ESB REST service

  1. Click the Run process button to run the process. The studio opens the process page in your default browser.

  2. Click the Submit button to start the process and call the REST service.