Skip to main content

Exploring the DX API with Postman

9 Tasks

1 hr

Visible to: All users
Intermediate
Pega Platform '24.2
User Experience
Constellation
Low-Code App Development
English

Scenario

The Pega Digital Experience (DX) API is a set of model-driven REST API endpoints that help you programmatically view, create, and update Cases and Assignments. Understanding the messages that are transmitted between a Constellation application and Pega DX API will help you troubleshoot issues that arise during the application development process.

To better understand the relationship between Constellation applications and the DX API, your challenge is to generate several Case-related DX API calls to Sweet Life's Incident Case Type using Postman.

Note: Postman is a free, open-source API platform for building and testing APIs. For more information on Postman, see the Postman documentation overview.

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

Role User name Password
System Architect Author@SL 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 Update the TellUsMore_Service operator

  1. In the Pega instance for the challenge, enter the following credentials:
    1. In the User name field, enter Author@SL.
    2. In the Password field, enter pega123!
  2. Switch to Dev Studio.
  3. In the header of Dev Studio, click Configure > Org & Security > Organization > Operators.
  4. In the list of operators, open the TellUsMore_Service operator.
    Fell us more Service operator from the list.
  5. Click the Security tab.
  6. Click Update password, and then update the password to pega123!.
  7. Confirm that the selection for the Force password change on next login check box is clear.
    Update the password for the TellUsMore_Service operator.
  8. Click Save.
Note: You can verify the password change by logging into the TellUsMore application as the TellUsMore_Service operator with the password you entered. Be sure to log back in with the Author@SL credentials to complete the following tasks.

2 Configure OAuth 2.0 client registrations

Note: DX API V2 tests require authorization credentials. To generate a sample response to an endpoint call, you need an OAuth 2.0 Client Registration data instance.
  1. In the navigation pane of Dev Studio, click Records > Security > OAuth 2.0 Client Registration.
  2. In the upper-right corner of the OAuth 2.0 Client Registration list, click Create.
  3. In both the OAuth 2.0 Client Registration short description and Client name fields, enter Sweet Life DX API Test.
    Creating the Sweet Life DX API Test OAuth 2.o record.
  4. Click Create and open.
  5. Configure the record:
    1. In the Supported grant types section, clear the Client credentials checkbox, and then select the Password credentials checkbox.
    2. In the Identity mapping field, press the Down arrow key, and then select pyDefaultIdentityMappingForPasswordGrant.
    3. Select the Enable refresh token checkbox.
      Oauth client registration.
    4. In the Client Credentials section, click View & download.
      The client credentials for the DX API test.
    5. In the View & download window, click Download credentials.
      View and download credentials.
    6. Confirm that you downloaded the Sweet Life DX API TEst_Client Credentials file on your machine.
    7. Close the View & download window.
    8. In the header of the record, click Save.
      Note: After you save the record, the option to download the credentials is inactive.

3 Create the AllowedStartingFields Data Transform

  1. In the App Explorer, in the SL-TellUsMore-Work-Incident class, right-click Data Model, and then select Create > Data Transform
  2. In the Label field, enter AllowedStartingFields.
  3. Click Create and open.
  4. In the Data Transform, set the .pyDescription target equal to "".
    Configuration of the AllowedStartingFields Data Transform.
    Note: You can add additional fields to the AllowedStartingFields Data Transform. For more information about adding fields while creating Cases in DX API v2, see Adding fields while creating Cases in Constellation DX API.
  5. Click Save.

4 Configure the Postman environment

  1. Download the DXAPIdefinition.postman_collection.zip file to your machine, and then open and extract it:
  2. Extract the file from Step 1, and then save the DXAPIdefinition.postman_collection.json file to your machine.
  3. Access the Postman website, and then create a free account if you do not have one already.
  4. Create a Postman workspace named Sweet Life DX API Test for this challenge.
    Postman workspace
  5. In the Postman workspace, click Import, and then import  DXAPIdefinition.postman_collection.json file.
    The import begins automatically when you select the file.
    The imported DX API definition file in Postman.
  6. On the DX API definition, click the Variables tab.
    Highlighting the Variables tab on the Postman work section.
  7. Open the Sweet Life DX API Test_ClientCredentials.txt file that you downloaded and saved in an earlier task. 
  8. Modify the values in the Current value column so that they correspond to the information contained in the Sweet Life DX API Test_ClientCredentials (SLDXAPI_CC) file.
    You must modify some information from the SLDXAPI_CC file slightly. The following table includes more information: 
    Postman variable name Current value
    server Enter a partial URL from the SLDXAPI_CC file that includes the text from https to prweb.
    For example, https://*******.pegacea.net/prweb.
    The asterisks correspond to server-specific values in your SLDXAPI_CC file.
    baseUrl Enter a partial URL from the SLDXAPI_CC file that includes the text from https to prweb, and then append /api/application/v2.
    For example, https://*******.pegacea.net/prweb/api/application/v2.
    The asterisks correspond to server-specific values in your SLDXAPI_CC file.
    AccessTokenURL Enter the Access token endpoint value from the SLDXAPI_CC file
    ClientID Enter the Client ID from the SLDXAPI_CC file
    ClientSecret Enter the Client Secret from the SLDXAPI_CC file
    user TellUsMore_Service
    password pega123!
    OriginChannel Web
  9. Click Save.
    Postman variables after the import and updates.
  10. Click the Authorization tab, and then review the details:
    1. Confirm that value in the Auth Type list is OAuth 2.0.
    2. Confirm that that value in the Token list is Available tokens.
      DX API definition
  11. In the Configure New Token section, view the value in the Password field, and then confirm the value is {{password}}.
    The visible Password value.
  12. Click Save if you have made updates.
  13. On the Authorization tab, attempt to generate a new token and verify that the authentication configuration is successful by clicking Get New Access Token.
    After Postman authorizes the information you entered, a screen with your new access token is displayed.
  14. Click Use Token to save the new token to your authorization profile.
    Managing your access tokens.

Postman updates the token associated with the authorization profile.

5 Create a new Incident Case

  1. In the navigation pane of Postman, expand the cases folder, and then click Create new Incident - success.
    The Create new Incident - success case.
  2. Click the Body tab, and then enter the following JSON code:
    {
        "content": {
             "pyDescription": "Description"
        },
        "caseTypeID": "SL-TellUsMore-Work-Incident",
        "parentCaseID": ""
    }
  3. Click Send to send the DX API request.
    The Create new Incident Case request.
  4. Toward the bottom of the request page, analyze the JSON response data objects returned by the DX API:
    1. Review the caseInfo object and note the case ID.
      Caseinfo ID Response object
    2. Review the relatedCaseTypes object.
      Related Casetypes Postman
    3. Review the assignments object.
      The assignments object in the API response provides information about the Assignments created as part of the Case. It can include details such as the Assignment ID, the name of the assignee, the deadline for completion, and any associated data or attachments.
      The assignments JSON object.
    4. Review the availableChildCaseTypes object.
      The the availableChildCaseTypes JSON data.
    5. Review the availableActions object.
      The availableActions object that returns in the response of Create DX API is a list of Actions that users can perform on the created work object. These Actions are defined in the Case Type and can include options such as submitting the work object, saving it as a draft, or canceling it.
      The availableActions JSON data.
    6. Review the stages section: 
      In Pega DX API, the stages object in the response for Case creation refers to the Stage of the Case where the newly created Case currently resides. A Stage in Pega Platform™ represents a logical division of a Case where a specific set of Actions or Tasks are performed. Each Stage typically has a set of Steps or Assignments that must be completed before the Case can move on to the next Stage. When you create a Case with the Pega DX API, the response includes a Stage object that provides information about the current Stage of the Case. This object might include properties such as the Stage name, ID, status, and other details about the current Stage. This information can be useful for tracking the progress of the Case and determining what Tasks or Assignments need to be completed before the Case can move on to the next Stage.
      The stages JSON data.
  5. In the nextAssignmentInfo object, copy the Assignment ID returned by the DX API (for example, ASSIGN-WORKLIST SL-TELLUSMORE-WORK I-1!CREATEFORM_DEFAULT) for the next task.
    The nextAssignmentlnfo JSON object.
  6. Return to App Studio, preview the application, and then open the TellUsMore - BO Portal.
  7. Click Incidents, and then confirm that the newly created Case is displayed on the landing page.
    Highlighting the new Incident Case on the Incidents landing page of the BO Portal.

6 Get Assignment details

  1. In the navigation pane of Postman, expand the assignments > {assignmentsID} folder path.
  2. Open the Get first assignment details request.
    The path to Get first assignment detail file
  3. In the central work pane, click the Params tab, and then modify the query param values:
    1. In the viewType row, enter page.
    2. Leave the pageName row empty.
    3. In the assignmentID row, enter the value returned in the nextAssignment object from the new Case call that you copied in Task 5, step 5.
      For example, ASSIGN-WORKLIST SL-TELLUSMORE-WORK I-1!CREATEFORM_DEFAULT.
      Get first assignment details modified Query parameters.
  4. Click Save, and then click Send.
  5. Investigate the JSON response object, and then copy the details of the submit object for the next task (for example, ASSIGN-WORKLIST SL-TELLUSMORE-WORK I-1!CREATEFORM_DEFAULT).
    The submit response object.

7 Use the assignments DX API endpoint to Get submit action details

  1. In the navigation pane of Postman, expand the assignments > {assignmentID} > actions > {actionID} folder path.
  2. Open the Get submit action details request.
    The Get submit action details file path.
  3. In the central work pane, click the Params tab, and then modify the query param values:
    1. Leave the viewType row empty.
    2. In the excludeAdditionalActions row, enter true.
    3. In the assignmentID row, enter the value from the submit object from Task 6, step 5 (for example, ASSIGN-WORKLIST SL-TELLUSMORE-WORK I-1!CREATEFORM_DEFAULT).
    4. In the actionID row, enter DetermineCategory.
      Query params for Get submit action details API call.
  4. Click Save, and then click Send.
  5. Review the JSON response object.
  6. In the response, click the Headers tab, and then copy the etag value for the next task.
    Highlighting the etag value from the Get submit action details response object.

8 Perform a Submit Action

  1. In the navigation pane of Postman, expand the assignments > {assignmentID} > actions > {actionID} folder path.
  2. Open the Submit first assignment request file.
    The Submit first assignment file path
  3. In the central work pane, open the Params tab, and then modify the query param values:
    1. In the viewType row, enter none.
    2. In the assignmentID row, enter the value from the submit object that you copied in Task 5, step 5. (for example, ASSIGN-WORKLIST SL-TELLUSMORE-WORK I-1!CREATEFORM_DEFAULT).
    3. In the actionID row, enter DetermineCategory.
      The Submit first assignment query params.
  4. Click the Headers tab, and then in the if match row, enter the value from the etag object that you copied in Task 6, step 6.
    The Submit first assignment Header etag value.
  5. Click the Body tab, and then enter the following JSON request code:
    {
        "content": {
            "IncidentType": "Product faulty or unsafe",
            "IncidentSubType": "Product not as described"
        }
    }
  6. Click Save, and then click Send.
  7. Review the JSON response object, and then confirm that the request was successful.
  8. Return to App Studio, preview the application, and then open the TellUsMore - BO Portal.
  9. Confirm that the Incidents landing page contains values the Incident Type and Incident SubType fields.
    The TellUsMore-BO Portal with the Case Incident Type and Incident SubType populated by DX API

9 Create a new product over DX API

  1. Return to Postman.
  2. In the navigation pane of Postman, expand the data > {data_view_ID} folder path.
  3. Open the Create Product request.
    The Create Product file path.
  4. In the central work pane, click the Params tab, and in the data_view row, enter D_ProductSavable.
    The Create Product query params.
  5. Click the Body tab, and then enter the following JSON code:
    {
        "data": {
            "Name":"Shocker",
            "Category":"20b3b6c4-d7d5-4516-a4ed-4cda31ddc5da",
            "SKU":"32491"
        }
    }
    The JSON code for Create Product.
  6. Click Save, and then click Send.
  7. Review the JSON response object, noting the Category, Name, pyGUID, and SKU fields.
    Create product JSON response object.
  8. Return to App Studio, and then click Data > Product > Records.
  9. Confirm that the Shocker product is included in the list of Product records.
    Shocker is included in the Product records.

Confirm your work

Your work has been confirmed as part of the steps in the Detailed Tasks section of this challenge.


This Challenge is to practice what you learned in the following Module:


Available in the following mission:

If you are having problems with your training, please review the Pega Academy Support FAQs.

Did you find this content helpful?

Want to help us improve this content?

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