Skip to main content

Adding an external data source to a data type

6 Tasks

30 mins

 Visible to: All users Applies to: Pega Platform '23
Intermediate
Data Integration
English
Verify the version tags to ensure you are consuming the intended content or, complete the latest version.

Scenario

Requests for roadside assistance must identify the vehicle so that a service provider can prepare for the service call. For example, certain vehicles may require a flat-bed tow truck or a higher octane blend of fuel. To better prepare service providers for a service call, stakeholders want to ensure that users only enter a valid combination of make, model, and model year for a vehicle. After evaluating several possible sources for vehicle models, stakeholders decided to source this information from a US National Highway Traffic Safety Administration (NHTSA) web service available at https://vpic.nhtsa.dot.gov/api.

Replace the current simulated data source with an integration to source the model information for passenger cars and trucks using a Representational State Transfer (REST) service provided by the NHTSA. Populate the D_VehiclemodelsList Data Page with NHTSA response data, based on the model year and make entered by the user.

Note: NHTSA data includes information on other types of vehicles, such as buses, that are not supported by GoGoRoad roadside assistance service. To display only relevant vehicle models, configure the integration to support two calls to the NHTSA service: one for passenger cars, and one for trucks.

The following table provides the credentials you need to complete the challenge.

Role User name Password
Application Developer author@gogoroad pega123!
Note: Your practice environment may support the completion of multiple challenges. As a result, the configuration shown in the challenge walkthrough may not match your environment exactly.

You must initiate your own Pega instance to complete this Challenge.

Initialization may take up to 5 minutes so please be patient.

Challenge Walkthrough

Detailed Tasks

1 Create a data object with an external data source

  1. In the Pega instance for the challenge, enter the following credentials:
    1. In the User name field, enter author@gogoroad.
    2. In the Password field, enter pega123!.
  2. In the App Studio navigation pane, click Data.
  3. In the upper-right corner of the Data objects and integrations landing page, click New to open the Data Object wizard and create a data object to access the NHTSA service.
  4. In the Data Object wizard, in the Data object name field, enter NHTSA Model data.
    data_object_creation
  5. Click Next to create and configure the data object connection details.
  6. In the System drop-down, select Create new. The wizard updates to display additional fields to define the new data source.
  7. In the Name field, enter NHTSA vPIC.
  8. In the Description field, enter NHTSA Product Information Catalog Vehicle Listing.
    system_details
  9. In the Endpoint URL field, enter https://vpic.nhtsa.dot.gov/api/vehicles/GetModelsForMakeYear/make/Ford/modelyear/2015/vehicletype/Truck?format=json to specify the URL for the NHTSA web service.
  10. Expand the Parameters section to display the URL parts for the service URL.
  11. Using the following table, add parameters for the make, model year, and vehicle type parts of the service URL.
    URL part Parameter name
    Ford make
    2015 modelyear
    Truck vehicletype
    connection_details
  12. Click Initialize call to call the REST service and advance to the third step of the wizard.

2 Map the response from the data source

Note: The response indicates seven results were returned and displays data for one of the seven results. The number of results returned varies according to the parameters passed to the service.
  1. In the SearchCriteria row of the data mapping dialogue box, click Add new to map the SearchCriteria field from the REST response to a field for the data object. The contents of the row update to display the Map to field and a drop-down listing Field Types.
  2. In the SearchCriteria row, click the Add/Edit map to icon to accept the default mapping and create a text field named SearchCriteria in the data object.
    Search Criteria
  3. Repeat steps 1 and 2 for the Make_Name, Model_Name, and VehicleTypeName response fields.
    Data mapping
  4. Click Next to complete the data mapping and advance to the fourth step of the wizard.

3 Define the endpoint settings for the integration

Note: The NHTSA does not require user authentication to access the service and receive response data. Other data providers may require authentication. Verify any authentication requirements when you configure an integration to a web service.
  1. Under Endpoint URL, in the Name field, enter GetVehicleModels_BaseURL to identify the connection settings.
  2. Under Dev, in the Base URL field, enter https://vpic.nhtsa.dot.gov to complete the URL used while developing the application in the development system.
  3. Under Stage, in the Base URL field, enter https://vpic.nhtsa.dot.gov to complete the URL used after migrating the application to a staging system.
  4. Under Prod, in the Base URL field, enter https://vpic.nhtsa.dot.gov to complete the URL used after migrating the application to a production system.
  5. Under Authentication, in the Name field, enter AuthProfile_NHTSA_vPIC.
    Environment settings
  6. Click Submit to complete the configuration of the data object and REST integration.

4 Aggregate the responses from the data source

  1. In the Dev Studio navigation pane, click Data types to list the data objects defined for the GoGoRoad application.
  2. Click Vehicle models to open the data type.  
  3. Click the Sources tab to view available sources and click List Vehicle models to open the D_VehiclemodelsList Data Page, which caches a listing of vehicle models.
  4. In the Data Sources section, clear the Simulate data source check box to remove the simulated data source from the Data Page.
  5. In the Source drop-down, select Aggregate sources to source the Data Page using two REST calls.
  6. In the Aggregate source name field, enter NHTSA vPIC to identify the data source for the Data Page.
  7. In the Source drop-down, select Data Transform.
  8. Click Add source to add a second source for the Data Page.
  9. In the second Source drop-down, select Data Transform.
    aggregate_sources_DP

5 Configure the source Data Transform

  1. For the first source, in the Data Transform name field, enter MapModels.
  2. Click the Open icon to create the Data Transform.
    Open icon
  3. Click Create and open to accept the default settings and open the Data Transform Rule form.
  4. Click the Parameters tab to define the three parameters required by the NHTSA service.
    1. On the Parameters tab, click the Add icon to add a row to define a parameter.
    2. In the empty parameter row, in the Name field, enter make.
    3. In the Required drop-down, select Yes.
    4. Repeat steps 4a-4c to add two more parameters to the Data Transform, using the information in the following table.
      Name Required
      modelyear Yes
      vehicletype Yes
  5. Click the Pages & Classes tab to identify the pages used by the Data Transform and the class of each page.
    1. On the Pages & Classes tab, in the Page name field, enter Primary.pxResults to identify the page that contains the output of the Data Transform.
    2. In the Class field, enter or select GoGo-GoGoRoad-Data-VehicleModels to identify the class of the output page.
    3. Click the Add item icon to add a second row to the Pages & Classes tab.
    4. In the Page name field, enter D_NHTSAModelData.Results to identify the page that contains the output of the Data Transform.
    5. In the Class field, enter or select GoGo-GoGoRoad-Data-NHTSAModelData-Results to identify the class of the output page.
      Page name
  6. Click the Definition tab to configure the Data Transform logic.
    1. For step 1, in the Action drop down, select Append and Map to to create a new results page for each result returned. The Data Transform adds a child row labeled 1.1 below step 1.
    2. For step 1, in the Target field, enter Primary.pxResults.
    3. In the Relation drop-down, select each page in.
    4. In the Source field, enter D_NHTSAModelData[vehicletype:param.vehicletype,modelyear:param.modelyear,make:param.make].Results to pass the required parameters to the Data Page that calls the NHTSA service and caches the response.
    5. For step 1.1, in the Target field, enter or select .Make to set the value of the Make property on the target page.
    6. In the Source field, enter or select .Make_Name to identify the property to copy to the target.
    7. Click the Add a row icon twice to add steps 1.2 and 1.3 to the Data Transform.
    8. Complete the fields of steps 1.2 and 1.3 by using the information in the following table.
        Action Target Source
      1.2 Set .Model .Model_Name
      1.3 Set .VehicleType .VehicleTypeName
      map_models_DT
  7. Click Save to complete the configuration of the Data Transform.

6 Parameterize the Data Page to configure both service calls

  1. In Dev Studio, click the D_VehiclemodelsList tab to return to the Data Page Rule form.
  2. On the D_VehiclemodelsList Data Page Rule form, click the Parameters tab to add parameters to the Data Page.
  3. In the empty row, in the Name field, enter make to define a parameter for the make to pass to the Data Transform.
  4. In the Required drop-down, select Yes to mark the parameter as required.
  5. Click the Add item icon to add a second parameter to the Data Page.
  6. In the second row, in the Name field, enter modelyear to define a parameter for the model year to pass to the Data Transform.
  7. In the Required drop-down, select Yes to mark the parameter as required.
  8. Click the Definition tab to resume configuration of the aggregate sources.
  9. Below the Data Transform name field, click Parameters to open a dialog box for setting values to pass to the Data Transform.
    1. In the dialog box, in the Value field for the make parameter, enter param.make to pass the value of the make parameter passed to the Data Page.
    2. In the Value field for the modelyear parameter, enter param.modelyear to pass the value of the model year parameter passed to the Data Page.
    3. In the Value field for the vehicletype parameter, enter Passenger Car to pass a constant string.
    4. Click Submit to close the modal dialog and save the parameter configuration.
  10. For the second aggregate source, in the Data Transform name field, enter or select MapModels to call the Data Transform a second time to populate the Data Page.
  11. Press the Tab key to exit the field. The Parameters link is displayed below the Data Transform name field.
  12. Repeat step 9 for the second aggregated source to add parameter values for the MapModels Data Transform by using the information in the following table.
    Parameter Value
    make param.make
    modelyear param.modelyear
    vehicletype Truck
  13. Click Save to complete the configuration of the Data Page.

This Challenge is to practice what you learned in the following Module:
If you are having problems with your training, please review the Pega Academy Support FAQs.

Did you find this content helpful?

Yes
No

Want to help us improve this content?
Suggest an edit

We'd prefer it if you saw us at our best.

Pega Academy has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

Close Deprecation Notice