Creating the REST integration interface

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

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.

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”.

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.

      

       

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.

      

       

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.

   
9. Save the activity for use by the process.

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
   
6. Modify or Review the Hotel Contact information (an email address MUST be supplied)
   
7. Modify or Review the 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
   
   
   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
    
13. Launch the case. enter the numnber of confirmed rooms, click Confirm
    
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
    
    
    The number of confirmed rooms should have been communicated to the SOR Hotel case