Using an external data source

The first step is to determine which entity to use for the external data. As part of any data integration, you need a data class to store the data from your external source.

After studying the external data and analyzing the application's requirement, review the Common Data Model entities and determine the entity data class that you want to associate with the external data. In this demonstration, we associate the Contacts entity with the new data source.

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 Contact. The following figure shows the Contact Data Page:

To copy the Contacts 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. In the newly saved D_Contacts page, in the Data Source section, click the icon next to the Response Data Transform field. 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_Contacts Data Page to your application's ruleset. For this demonstration, we do not copy all the data transforms.

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

The second 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. After selecting an entity data class to represent the data you receive from the external service, it is time to create the actual integration.

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 which of the HTTP methods to invoke on the REST service. Invocation depends on what methods the REST service uses. 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 previously selected data class. 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:

Now that you have an external data source configured, you can save the Request Data Transform to your application ruleset. The Request Data Transform …

Click Records, then expand Data Model and select Data Transforms. In the list of Data Transforms, select Con_Detail_Down 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_Contacts 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_Down

Response Data Transform Con_Detail_Up

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_Contacts 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_Contacts page, open the Request Data Transform named Con_Detail_Up.

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 Section 5.2 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 the 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_Details_Down. The default settings are maintained for this file.

You now have the two Data Transforms that can map data from the REST response to 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_Contacts 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:

Congratulations! You have successfully integrated external data from a REST service into a Pega Customer Service application!