External data source example

This topic shows an example of how you can integrate data from an external REST service into a Pega Customer Service application.

To integrate data from an external REST service into a Pega Customer Service application, follow the below steps in a sequential order:

1. Create data model

2. Connect to external service

3. Map response data

4. Update data page

First step is to create a new data class. As part of any data integration, you need a data class to store the data from your external source.

Transcript

As part of any data integration, you need a data class to store the data from your external source. This demonstration shows you how to create a new data class and update the application settings to use your data class as the default Contact class.

To create a new data class, first, go to the Data Explorer, then click the down arrow and choose Add new data type.

You then complete the initial form and identify a name, description, parent class, application, and ruleset to use.

Once created, you can add additional properties that the external data source may contain that Pega Customer Service™ may not have. In this example, there is not a requirement to have additional properties; therefore, the data class stores the data transform and data page that you create later in this demonstration.

After creating the MyContact data class, you need to update the inheritance path so that it inherits from PegaCA-Interface-Contact. This update allows your class to be used throughout the application where PegaCA-Interface-Contact is used and minimize the changes you need to make.

The last thing you need to configure is to update the Pega Customer Service application settings to point to your new class. The easiest way to do this is to search for ApplicationSettings.

From the results, choose the ApplicationSettings data transform. The ApplicationSettings data transform is used to call a set of additional data transforms that contain individual settings for a Pega Customer Service application. The settings you are looking for here are the CPMInterfaceLayerSettings. 

The Contact class setting is located in the .InterfaceContactClass property. Change the value from PegaCA-Interface-Contact to the name of your contact data class. In this example, that value is PegaCA-Data-MyContact.

After making that change, save the updated ApplicationSettings data transform into your applications ruleset.

You have now successfully created and configured a data class to contain data from an external source.

Second step is to create a REST connector. After creating a data class, you need to run the REST Integration wizard to connect to an external REST service.

Transcript

In this demonstration, you see how to run the REST Integration wizard to connect to an external REST service. After creating a 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 a 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 is offered 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 an existing authentication if you created a previous integration or create a new authentication. Once 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 created 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 final step in the wizard is to review the various class names that the REST Integration wizard will create. By default, the wizard creates a new ruleset for all your classes. For this example, you are going to put them in an existing ruleset.

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

Third step is to map response data. After connecting to external REST service, you need to create a data transform to map from the REST connector to the data class.

Transcript

Now that you have set up a data class and set up the integration to the external REST service, it is time to create a data transform to map between the two classes. In this demonstration, you see how to create a data transform to map the properties of the REST response to the properties of the data class.

The first step is to create a new data transform called MapRESTResponse and place it in the PegaCA-Data-MyContact class.

On the Pages & Classes tab, you need to add a page for the REST service that has the response in it. The big question is ”What class do I use?” You can find the answer in the App explorer. In the REST Integration wizard, you set the class to CPM-Int-External, so use that as the starting point.

You need the API class as it contains the request and response properties. The response property contains the values from the REST service after you call it.

Now that the Pages & Classes is configured, you can define the mappings from one class to another. In this example, you map ten properties from the response to properties in the MyContact data class.

You now have a data transform that can map data from the REST response to the MyContact data class.

Last step is to update data page. After mapping response data, update an activity to use the REST connector to retrieve data.

Transcript

Now that all the pieces are in place, it is time to actually call the REST service and process the response. In this demonstration, you call a REST Connector from an activity and process the response.

For this example, you are going to configure that Contact details data page. The page is accessible from the Data Explorer.  Because it is part of the Contact class, expand that class and then select Contact details.

First, save this data page to the MyContact class by saving it to PegaCA-Data-MyContact.

The DPLoadContact activity loads the data page. You update the DPLoadContact activity to use your connector instead of the sample data. Save the activity to PegaCA-Data-MyContact so that you have access to the data transform (and other properties if needed) in the activity.

Like you did for the data transform, you need to update the Pages & Classes references for the activity. You also want to change the Class for the AppContact page to use our PegaCA-Data-MyContact class. Then add a page for the REST service and use the same class name as you did in the data transform.

Now it is time to update what the activity actually does.  In this activity, step two is responsible for calling the sample database and getting information. You are going to comment out that step in case you want to put it back in during testing. Alternatively, you can just delete the step.

The first step you need to add is to create a new page for the RESTService. This provides an empty page used to hold the REST request and response.

Remember that your REST service had a parameter called ContactId that is used to specify which person we want contact data for. Before you can invoke the REST service, you need to set this value as part of the request. Fortunately, this activity takes a parameter for the ContactId, so all you need to do is add a Property-Set step and set the ContactId equal to the value of the parameter ContactId.

Now it is time to call the REST service! Pretty simple, actually: use the Connect-REST method, provide the RESTService step page, and provide the service to call. The service is called using the information in the RESTService page and then stores the results in the RESTService page.

Now that you have the results, map those results to the AppContact page. Add an Apply-DataTransform step and select the data transform you created earlier. This will copy the data from the REST response to the AppContact page.  The last step of the activity then merges the AppContact page into the Contact details data page.

Once you check in the new activity, you can test it out. From the interaction portal, start a Demo pop with Sara Connor.  Right away, in the incoming screen pop-up, you should notice the call is from Pat Smith. This is the data from the REST service.

Once the interaction starts, you should also notice updated contact information.

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