Using an external data source

The first step is to create a REST connector. You run the REST Integration wizard to connect to an external REST service.

You can integrate external data in different formats depending on the data location, for example a web service, a database server, a REST service, or JMS.

In this demonstration, you see how to run the REST Integration wizard to connect to an external REST service.

In the first step in the wizard, you enter the details about connecting to the REST service. If part of the endpoint URL is in curly braces, the URL is identified as being parameterized. In our example, that means passing the ContactId to the REST service for the contact details of a customer. You could also take advantage of parameterizing the URL where the same service is offered but in different regions, to increase response time.

After entering the Endpoint URL, you can enter the credentials used to access the service. You can either reuse existing authentication if you created a previous integration or create new authentication. After you have set up the authentication, you can move on to the next part of the wizard.

In step two of the wizard, you configure the HTTP method to invoke on the REST service. In this example, you want to use the GET method.

In step three of the wizard, you configure the data model for the REST response object. This class is what you will map to the Logical Data Model (LDM) class for Contact. Here you can click Add a REST Response and call the service, to see the response you receive. Pega creates a class with properties that represent each of the fields returned from the REST service.

The last step in the wizard is to review the various class names that the REST Integration wizard creates. By default, the wizard creates a new ruleset for all your classes.

After clicking Create, you see the classes that the wizard generates. You have now set up the integration to the external REST service.

In the GetExternalContactData REST service, you can test the connectivity of the source. The following screenshot shows an example test that was successful, with the response data:

To make the data available to the sample application, you create copies of the Data Page and the Data Transforms to your application ruleset. For this example, you are going to configure the Contact details Data Page. The page is accessible from the Data Explorer. Expand the Contact class and then select D_Contact. The following figure shows the D_Contact Data Page:

The Data Sources show a profile named Profile_Con_Detail, which gets a record from the data source via the REST API. Each profile is associated with a different method (Get, Post, Put, Patch, Delete) and uses Data Transforms specific to that method. For more information about how the profiles and Data Transforms work, see Entity design pattern topic.

To copy the Contact Data Page, open the D_Contacts page and save the page using the default Context settings to add the Common-LDM-Entity class to the application ruleset. The D_Contacts page holds the contents of one contact record, for example, the address, phone, and email for Sara Connor.

Next, copy the response data transform, which maps data in the external source to your application Under Contact > Data Model, expand Data Transform, and then select Con_Detail_Response. Save the rule using the default Context settings to add the rule to the application's ruleset.

To enable create, replace, update and delete operations (CRUD), you must also copy the remaining data transforms associated with the D_Contact Data Page to your application's ruleset. For this demonstration, we do not copy all the data transforms.

You now have the Data Page and Response Data Transform saved to your application.

Save the Request Data Transform to your application ruleset. The Request Data Transform maps data from the Logical Data Model (LDM) to the data source.

Click Records, then expand Data Model and select Data Transforms. In the list of Data Transforms, select Con_Detail_Request to display the Data Transform. Save the page using the default Context settings and change the Applies to field to reference the external data source – in this case Common-Int-External-GET_ExternalContactDataAPI.

The next step is to modify the Data Page to use the external data source and the Data Transforms.

Modify the D_Contact page in your application ruleset to reference the external REST source. To do this, in the Data Explorer, expand the Contact class and then select Contact.

In the Data Source section, in the first statement under Profile_Con_Detail, you add the information to connect to the external REST service. In this example, the information is:

Source Connector

Type REST

Name GET_ExternalContactData

Request Data Transform Con_Detail_Request

Response Data Transform Con_Detail_Response

Endpoint URL http://localhost:8080/prweb/PRRestService/test/01-01-01/getContactData/{ContactId}

Method GET

The following figure shows the updated section of the Data Page:

Now that you have set up the integration to the external REST service, you modify the Data Transforms to map between the two classes.

In this demonstration, you see how to modify a Data Transform to map the properties of the REST response to the properties of the entity data class.

There are two Data Pages that map properties, one for the request and one for the response.

To enable create, replace, update and delete (CRUD) operations, you also update the remaining Data Transforms that are associated with the D_Contact page. For this demonstration, we do not modify all transforms.

You can define the mappings from one class to another. In this example, you map properties from the response to properties in the Contact data class.

In the Data Sources section of the D_Contact page, open the Request Data Transform named Con_Detail_Response.

On the Pages & Classes tab, you modify the ConnectorPage to use the REST service. You use the API class because it contains the request and response properties. The response property contains the values from the REST service after you call it. The Response page and the ContactDetail page are already defined.

Next, you map the fields from the external source. You can remove the unused properties.

The following figure shows the mapped properties in Sections 3 through 12 of the Data Transform. Values on the left are the target property and values on the right are the source property. You can remove any unused properties.

In a previous section, you created a version of the Request Data Transform in your application ruleset and modified the Applies to field to reference the REST service for the external data. This Data Transform is named Con_Detail_Request. The default settings are maintained for this file.

You now have the two Data Transforms that can map data between the data source and the Contact data class.

Now that all the pieces are in place, it is time to call the REST service and process the response.

Open the D_Contact Data Page, and then click Actions > Run. In the Run Data page dialog box, in the ContactID field, enter ContactId and then click Run. The dialog box shows the properties for the Pat Smith contact, as in the following screenshot: