Skip to main content

Creating the REST integration interface

Archived

6 Tasks

20 mins

Visible to: All users
Advanced English
This content is now archived and is no longer updated. Progress is not calculated. Pega Cloud instances are disabled, and badges are no longer awarded. Click here to continue your progress in the latest version.

Scenario

You have created the Hotel and Hotel Proxy applications in the "Hotel and Hotel Proxy application" exercise. In this exercise you can practice creating a Hotel - Hotel Proxy REST integration interface between the Hotel and Hotel Proxy applications. The interface allows the Hotel application to create a Rooms Requet Proxy case in the Hotel Proxy application for every Rooms Request case in the Hotel application. The Hotel Proxy application allows a hotel contact to confirm the number of rooms reserved in the Rooms Request Proxy case. The interface then allows the Hotel Proxy application to send the number of rooms reserved to the originating Rooms Request case in the Hotel application.

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

Role Operator ID Password
Admin Admin2@Hotel rules
Admin Admin2@HotelProxy rules
Admin Admin2@HotelDevOnly rules

This is an optional exercise. If you have experience creating REST connectors in the Pega platform you can skip this exercise.

Note: If you import the Hotel_HotelProxy_REST_Solution.zip RAP file from the related content section you will not only import a "workin" unlocked application you can use to practice the configuration steps described in this exercise, you will also imported a working solution for this exercise. You can complete this exercise using the Hotel 01.01.05 (Hotel 01.01.05 Administrators) access group while comparing your work to the completed solution using the Hotel 01.01.06 (Hotel 01.01.06 Administrators) access group.

 

Create a REST integration interface that does the following:

  • Allows users to enter the number of rooms to reserve for the event
  • Displays the number of rooms that have been accepted, if the submission is successful
  • Displays an error message, if the submission is not successful

Detailed Tasks

1 Detailed steps

To support your requirements, you will do the following:

  1. Create a REST connector for the interface.
  2. Configure the REST connector.
  3. Configure the rules required to configure the Confirm Rooms activity.
  4. Create the Create Proxy Case activity.
  5. Create the Confirm Rooms activity.

Set-up

Before completing this exercise you must first setup your exercise environment as described in the following steps:

  1. Import the  Hotel_HotelProxy_REST_Solution.zip  RAP file
  2. Log in as Admin2@Hotel
  3. Log in as Admin2@HotelProxy

2 Create a REST connector for the interface

  1. From your exercise system, log on to the Hotel application as Admin2@Hotel.
  2. Switch to the Hotel 01,01.05 (Hotel 01.01.05 Administrators) access group.
  3. From the Records Explorer, navigate to Integration-Resources > Service Package and open the api service package.
  4. Update the Service access group to HotelDevOnly010106:Administrators and clear the Requires authentication check box. Change the associated ruleset to HotelDevOnly. Save the service package.
    Note: For the purpose of packaging, you changed the service package's associated ruleset.
  5. From the DEV Studio menu, navigate to Integration > Connectors > Create REST Integration, which opens the REST Integration wizard.
  6. On the Connection panel, name the connector RoomsRequest and enter the following endpoint URL:

    http://127.0.0.1/prweb/api/v1/cases/{CASE_KEY}

    Note: The IP address in this example is only used during design to generate a response but is never used in production.
  7. Advance to the Resource methods panel and do the following:
    1. Name the resource RoomsRequest and select the GET, POST, and PUT check boxes.
    2. Define the data model by adding a REST response or adding a file. The system will parse sample requests and responses to determine the data model.
    3. Using the Add a REST response link is the preferred method:
      1. Select the Add a REST response dialog by clicking the Add a REST response link.
      2. Select Post or Put from the Choose method drop down list.
      3. Set Content type to JSON.
      4. Paste the sample JSON below into the Request tab.
      5. Use the Pretty print icon ({}) in the top right-hand corner of the multiline edit control to reformat the JSON.
      6. Click the Run button to auto generate the response tab.
      7. Click Submit.
        This auto generates all possible responses as described by the Pega API.
    4. Alternatively, you can also add files by creating PUT and POST JSON text files using the samples provided.
      Note: Do not just copy and paste the following example text into separate text files. First use http://www.jsonlint.com to verify and format the JSON correctly. Then copy and paste the corrected text into two separate text files.

      POST JSON

      {"caseTypeID":"FSG-HotelProxy-Work-RoomsRequest-Proxy" ,"processID":"pyStartCase" ,"content":{ "RoomsRequest":{ "FromDate":"20190331T130944.828 GMT" ,"HotelGUID":"d8825749-e2fb-46b3-97aa-3ead12b89584" ,"pxObjClass":"FSG-Data-Hotel-RoomsRequest" ,"pyLabel":" " ,"RequestSendDate":"20190325T130944.829 GMT" ,"ResponseDeadline":"20190329T130944.829 GMT" ,"RoomsRequested":"320" ,"ToDate":"20190402T130944.829 GMT" ,"Contact":{ "pxObjClass":"Data-Party" ,"pyEmail1":"[email protected]" ,"pyEmail1Type":"HTML" ,"pyFirstName":"Tony" ,"pyLabel":" " ,"pyLastName":"Parker" } } } }

      PUT JSON

      { "content":{ "RoomsRequest":{ "FromDate":"20190331T130944.828 GMT" ,"HotelGUID":"d8825749-e2fb-46b3-97aa-3ead12b89584" ,"pxObjClass":"FSG-Data-Hotel-RoomsRequest" ,"pyLabel":" " ,"RequestSendDate":"20190325T130944.829 GMT" ,"ResponseDeadline":"20190329T130944.829 GMT" ,"RoomsRequested":"320" ,"ToDate":"20190402T130944.829 GMT" ,"Contact":{ "pxObjClass":"Data-Party" ,"pyEmail1":"[email protected]" ,"pyEmail1Type":"HTML" ,"pyFirstName":"Tony" ,"pyLabel":" " ,"pyLastName":"Parker" } } } }
  8. Advance to the Data model panel.
  9. Add the POST text file to the POST method Sample type Request and add the PUT text file to the PUT method Sample type Request.
  10. Advance to the Review panel. In the panel, do the following:
    1. Specify RoomsRequest as the Integration class, FSG-Int-Hotel as the Parent class, and FSG-Int-Hotel-RoomsRequestAPI as the Integration class ID.
    2. Specify RoomsRequest as the Connector Name, and RoomsRequest as the ID.

    3. Set the Context ruleset to a new RoomsRequestInt ruleset.

    4. In the Data Layer section, select Skip (I’ll do it later).
      Note: You do not need to configure the data — you already have your data model for the room requests.
  11. Click Create to create the connector.
  12. Add the new RoomsRequestInt:01-01 ruleset to the HotelShared_20191202T192854184 • 01.01.06 component.
  13. Add the the HotelShared_20191202T192854184 • 01.01.05 component to the Enabled components list of both the Hotel • 01.01.05 and the HotelProxy • 01.01.05 applications.

 

3 Configure the REST Connector

  1. From the Records Explorer, open the new RoomsRequest REST Connector.
  2. Go to the Methods tab.
  3. In the Get Response section, configure the header as shown in the following table.

    Headers

    Name Description Map from Map from key
    etag Entity value of the case Clipboard Param.eTag
  4. In the Post Request section, configure the header as shown in the following table.

    Headers

    Name Description Map from Map from key
    Content- Type   Constant application/json
  5. In the Put Request section, configure the headers as shown in the following table.

    Headers

    Name Description Map from Map from key
    Content- Type   Constant application/json
    If-Match Entity value of the case Clipboard Param.eTag
    actionID Local Action to execute Clipboard Param.actionID
  6. Save the connector.

REST Connector Solution Tips

The REST Connector Wizard will ask for sample JSON text when configuring the POST and PUT requests. As shown below, the requests are highly similar. A convenient way to obtain the content portion, i.e., a RoomsRequest element, is to use the Hotel case’s Enter Test Data stage to populate a RoomsRequest Field Group. Once this is done, open the Clipboard, navigate to the pyWorkPage’s RoomsRequest child page, right click, and select “Show JSON”.

POST JSON PUT JSON
{"caseTypeID":"FSG-HotelProxy-Work-RoomsRequest-Proxy" ,"processID":"pyStartCase" ,"content":{ "RoomsRequest":{ "FromDate":"20190331T130944.828 GMT" ,"HotelGUID":"d8825749-e2fb-46b3-97aa-3ead12b89584" ,"pxObjClass":"FSG-Data-Hotel-RoomsRequest" ,"pyLabel":" " ,"RequestSendDate":"20190325T130944.829 GMT" ,"ResponseDeadline":"20190329T130944.829 GMT" ,"RoomsRequested":"320" ,"ToDate":"20190402T130944.829 GMT" ,"Contact":{ "pxObjClass":"Data-Party" ,"pyEmail1":"[email protected]" ,"pyEmail1Type":"HTML" ,"pyFirstName":"Tony" ,"pyLabel":" " ,"pyLastName":"Parker" } } } } { "content":{ "RoomsRequest":{ "FromDate":"20190331T130944.828 GMT" ,"HotelGUID":"d8825749-e2fb-46b3-97aa-3ead12b89584" ,"pxObjClass":"FSG-Data-Hotel-RoomsRequest" ,"pyLabel":" " ,"RequestSendDate":"20190325T130944.829 GMT" ,"ResponseDeadline":"20190329T130944.829 GMT" ,"RoomsRequested":"320" ,"ToDate":"20190402T130944.829 GMT" ,"Contact":{ "pxObjClass":"Data-Party" ,"pyEmail1":"[email protected]" ,"pyEmail1Type":"HTML" ,"pyFirstName":"Tony" ,"pyLabel":" " ,"pyLastName":"Parker" } } } }
Note: The Access Group specified for the “api” Service Package, is HotelDevOnly010106:Administrators. Since this is only an exercise, The “Requires authentication” checkbox is unchecked. If that checkbox was checked, the PegAPI_Hotel Authentication Profile configured on the RoomsRequest REST connector would be used. Regardless of the box being checked, because the PegAPI_Hotel Authentication profile is specified on the RoomsRequest REST connector the profile must exist, otherwise an error will be thrown. 

4 Create rules required by the CreateProxyCase and ConfirmRooms activities

  1. From your exercise system, log on to the Hotel application as Admin2@Hotel.
  2. Switch to the Hotel 01.01.05 (Hotel 01.01.05 Administrators) access group.
  3. In the FSG-Data class (FSG:01.01.05 ruleset), create two Text type properties named SORCaseKey and ProxyCaseKey.
  4. Create a when rule named RESTErrorDetected (FSGInt:01-01-05 ruleset) that applies to FSG-Int with the following condition:
    .pyHTTPResponseCode >= 300
    Note: .pyHTTPResponseCode is the HTTP Response Code set by Rule-Connect-HTTP.
  5. Create a CreateProxyError message that applies to FSG-Hotel-Work-RoomsRequest. In the Message field, specify this message: An Create Proxy error occurred. Please try again.

Create the (FSG-Hotel-Work-RoomsRequest) CreateProxyCase activity

  1. From your exercise system, log on to the Hotel application as Admin2@Hotel.
  2. Switch to the Hotel 01.01.05 (Hotel 01.01.05 Administrators) access group.
  3. Create the the CreateProxyCase activity that applies to the FSG-Hotel-Work-RoomsRequest class and is saved in the RoomsRequest:01.01.05 ruleset.

CreateProxyCase activity overview

Step 2 within this activity ensures the .SORCaseKey property is set within the .RoomsRequest Field Group. The to-be-created remote RoomsRequestProxy case would not be able to respond to the RoomsRequest case that created it if this was not done.

Step 3 uses the Interface step page of class FSG-Int-Hotel-RoomsRequestAPIand  sets .request.body_POST.content.RoomsRequest equal to Primary.RoomsRequest.

Afterward a REST connector named RoomsRequest is invoked. The URL passed to the REST connector ends in "/api/v1/cases". The REST connector’s method is POST.

Then the REST connector is invoked and the AutoMapAll Data Transform is run against a step page named PegaAPI of class Pega-API.

Next the Primary.RoomsRequest.ProxyCaseKey property is set equal to the PegaAPI step page ID property. This is important should the Hotel application ever need to issue a PUT request to update the number of requested rooms.

Configure the steps in the CreateProxyCase activity Steps tab

  1. For Step 1 on the Steps tab, do the following:

    1. Create a new page named Interface of class FSG-Int-Hotel-RoomsRequestAPI.
  2. For Step 2 on the Steps tab, do the following:
    1. Update the Step to obtain the SOR Case Key.
    2. Set the following method parameters.
       
      PropertiesName PropertiesValue
      Param.PageName @Default.PrimaryPageName(tools)
      .SORCaseKey Primary.pzInsKey != "" ? Primary.pzInsKey : @GetInstanceHandle(param.PageName, tools)
  3. For Step 3 on the Steps tab, do the following:
    1. Use Interface.request.body_POST.content as the Step page.
    2. Copy the case's .RoomsRequest into the POST Request's .Content .
    3. Set the following method parameter.
       
      PropertiesName PropertiesValue
      .RoomsRequest Primary.RoomsRequest
  4. For Step 4 on the Steps tab, do the following:
    1. Use Interface.request.body_POST as the Step page.
    2. Set Interface.request.body_POST.caseTypeID and process ID as shown in the following image.
    3. Set the following method parameters:
       
      PropertiesName PropertiesValue
      .caseTypeID "FSG-HotelProxy-Work-RoomsRequestProxy"
      .processID "pyStartCase"
  5.  For Step 5 on the Steps tab, do the following:
    1. Use the Primary page as the Step page.
    2. Set the following method parameter:

       
      PropertiesName PropertiesValue
      Param.EndPointURL pxRequestor.pxReqContextURI+"/api/v1/cases"
      Note: Only set Param.EndPointURL. Do not set the CASE__KEY in the URL.
  6. For Step 6 on the Steps tab, do the following:
    1. Issue a POST using the Connect-REST method and Step pageInterface to create the Proxy case by setting the following parameter values:  
      Name Value
      ServiceName RoomsRequest
      EndPointURL Param.EndPointURL
      MethodName POST
      ExecutionMode Run
  7. For Step 7 on the Steps tab, do the following:
    1. Set the parameters needed to de-serialize the JSON.
    2. Set properties on Interface.response_POST
    3. Set parameter jsonData to .defaultResponse_POST (DefaultResponse_POST)
    4. Set the parameter executionMode to "DESERIALIZE"
  8. For Step 8 on the Steps tab, do the following:
    1. Capture the ProxyCaseKey by first Auto-Maping everything from the JSON.
    2. Apply the AutoMapAll data transform to the PegaAPI page.
  9. For Step 9 on the Steps tab, do the following:
    1. Set properties on PegaAPI
    2. Set Primary.RoomsRequest.ProxyCaseKey to .ID (ID)
    3. If true Jump to step CLN (Clean up). Otherwise, continue with Error processing before CLN
  10. For Step 10 on the Steps tab, do the following:
    1. Error Handling
    2. Set the message CreateProxyErroron the Primary page
  11. For Step 11 (aka CLN) on the Steps tab, do the following:
    1. Clean Up
    2. Remove the following pages from memory:
      1. Interface
      2. PegaAPI
  12. Save the CreateProxyCase activity.

(FSG-HotelProxy-Work-RoomsRequestProxy) ConfirmRooms activity overview

The ConfirmRooms activity makes two back-to-back Pega API REST service calls, a GET and a PUT. The purpose of the GET request is to capture an etag header value from the response and to ensure the latest version of the originating Rooms Request case is being updated. The etag header value is copied to a parameter named eTag on the Clipboard. This parameter is not visible within the ConfirmRooms activity since that activity shared its parameter page with the REST connector. The .RoomRequest page is copied to the Interface step page’s .request.body_PUT.content page prior to the PUT request. Within the REST connector’s configuration for that PUT request, the If-Match header value is set equal to param.eTag.

Create the (FSG-HotelProxy-Work-RoomsRequestProxy) ConfirmRooms activity

  1. From your exercise system, log on to the Hotel Proxy application as Admin2@HotelProxy.
  2. Switch to the Hotel Proxy 01.01.05 (Hotel Proxy 01.01.05 Administrators) access group.
  3. From the App Explorer, create an activity named ConfirmRooms that applies to the FSG-HotelProxy-Work-RoomsRequestProxy class and RoomsRequestProxy ruleset.
  4. On the Steps tab for the activity, enter the following values.
    Step Label Method Step page Description  
    1   Page-New Interface FSG-Int-Hotel-RoomsRequestAPI  
    2   Property-Set .RoomsRequest Set Proxy Case Key in case SOR case needs to contact again  
    3   Property-Set Interface.request Set CASE_KEY plus param.EndPointURL  
    4   Connect-REST Interface GET eTag header value set into Param.eTag later used by PUT Jump
    5   Property-Set Interface.request.body_PUT Set .content.RoomRequest and Param actionID=pyResolveAndCloseCase  
    6   Connect-REST interface PUT If-Match, actionID, and content = NumConfirmedRooms Jump
    7 ERR Page-Set-Messages   If error, output NumRoomsConfirmed SendError Field Value text  
    8 CLN Page-Remove interface Clean up  
  5. On the Pages & Classes tab for the activity, define Interface as a Page name and specify FSG-Int-Hotel-RoomsRequestAPI as the Class.
  6. After each Pega API REST service is called the FSGInt-defined RESTErrorDetected When rule is checked. If the HTTP response code is >= 300, the ConfirmRooms activity jumps to the step labeled “ERR”.

 

Configure the steps on the activity Steps tab

  1. For Step 1 on the Steps tab, do the following:
    1. Create a new page named Interface of class FSG-Int-Hotel-RoomsRequestAPI.
  2. For Step 2 in the activity, set the method parameter .ProxyCaseKey = Primary.pzInsKey.
  3. For Step 3, set the following method parameters.
    PropertiesName PropertiesValue
    .CASE_KEY Primary.RoomsRequest.SORCaseKey
    Param.EndpointURL

    pxRequestor.pxReqContextURI+"/api/v1/cases/{CASE_Key}"

    Note: This parameter is used with both Connect-REST steps.
  4. For Step 4 set the Connect-Rest method and a Jump.
    1. For the method parameters, set the following values.
      Name Value
      ServiceName RoomsRequest
      EndPointURL Param.EndPointURL
      MethodName GET
      ExecutionMode Run
    2. Set a Jump in the event of an error using the FSG-Int RESTErrorDetected when rule. On exception, Jump to Later Step ERR (Step 7).

      The configuration will look like the following image.

      RESTErrorDetected rule

       

  5. For Step 5, set the following method parameters.
    PropertiesName PropertiesValue
    Param.actionID "pyResolveAndCloseCase"
    .content.RoomsRequest Primary.RoomsRequest
  6.  For Step 6, set the method and a jump.
    1. For the method parameters, set the following values.
      Name Value
      ServiceName RoomsRequest
      EndPointURL Param.EndPointURL
      MethodName PUT
      ExecutionMode Run
    2. Set a Jump in the event of an error using the FSG-Int RESTErrorDetected when rule. On exception, Jump to Later StepERR (Step 7) otherwise Jump to Later StepCLN (Step 8).

      The configuration will look like the following image.

      RESTErrorDetected jump to ERR step

       

  7. For Step 7 method parameters, set Category to NumRoomsConfirmed and Message to ProxySendError.
  8. For Step 8, remove the Interface page.

    When you are finished, the Steps tab will look like the following image.

    ConfirmRooms activity
  9. Save the activity for use by the process.

5 Verify your work

Verify your work

  1. Login a "Admin2@Hotel"
  2. Switch to the “Hotel 01.01.05 (Hotel 01.01.05 Administrators)” application
  3. Click on the Rooms Request case within the Case Designer
  4. Click the “Run” button
  5. Down-arrow with the Hotel Name field to select an existing FSG-Data-Hotel
    Rooms request case
  6. Modify or Review the Hotel Contact information (an email address MUST be supplied)
    Hotel Contact Information
  7. Modify or Review the Rooms Request information
    Rooms request information
  8. Create an Operator record based on the hotel contact’s email address. If this is not done, an error will occur when the RoomsRequestProxy case attempts to route to the Confirm Rooms assignment.
  9. Advance the Hotel case to where the Email subcase is created by clicking on Actions -> Refresh
    Email subcase

    Note the attached Data-Corr-Email instance and the two workparties, Owner and Contact.
  10. Login as "Admin2@HotelProxy"
  11. Verify that the RoomsRequestProxy case was created by entering class name FSG-HotelProxy-Work-RoomsRequestProxy in the App Explorer followed by clicking on that class name.
    1. Launch a RoomsRequestProxy case, open the Clipboard, then locate pyWorkPage.
    2. Note that pxApplication = HotelProxy
    3. Note how the Assign-Worklist pyUserWorkList Report Definition defined in the Pega-EndUserUI ruleset filters on .pxApplication = pxThread.pxCurrentApplicationName
    4. Note how the HotelProxy ruleset overrides the Assign-Worklist pyUserWorkList Report Definition to remove this filter condition
  12. Using a different browser, log in as the hotel contact. A RoomsRequestProxy case should be present in that contact’s worklist
    RoomsRequestProxy case
  13. Launch the case. enter the numnber of confirmed rooms, click Confirm
    Confirmed rooms
  14. Locate the SOR case in the App Explorer using FSG-Hotel-Work-RoomsRequest as the class. Note that the the number of confirmed rooms has been received from the RoomsRequestProxy case
    RoomsRequestProxy  resolved

    The number of confirmed rooms should have been communicated to the SOR Hotel case
    Roomsrequest SOR

6 Solution download



Available in the following mission:

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