Checksums for PATCHes and business action POSTs

For operations that have a request payload, checksums can be specified in the request payload. This applies to PATCHes and to most POSTs that execute business actions. (If a business action POST does not allow a request payload, you can still specify a checksum. But, you must do this in the request header. For more information, see Checksums for DELETEs.)

The checksum property is a child of the data property and a sibling of the attributes property. It uses the following syntax:

"checksum": "<value>"

For example, the following payload is for a PATCH to an activity. The payload specifies a new attribute value (setting priority to urgent) and a checksum value (7a0d9677f11e246bbe3c124889219c50).

{
  "data": {
    "attributes": {
      "priority": {
        "code": "urgent"
      }
    },
    "checksum": "7a0d9677f11e246bbe3c124889219c50"
  }
}

Checksums can be specified on the root resource and on any included resource. Specifying a checksum for any one resource does not require you to specify checksums for the others. For example:

  • You could specify a checksum for only the root resource.
  • You could specify a checksum for only one of the included resources.
  • You could specify a checksum for the root resource and some of the included resources, but not all of the included resources.

Tutorial: PATCH an activity using checksums

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more information, see Tutorial: Set up your Postman environment.

In this tutorial, you will attempt to PATCH an activity twice. Both PATCHes will include a checksum value. The first PATCH will succeed, and the second will fail.

Tutorial steps

  1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
    1. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
  2. The sample data includes one "Review risk information" activity for Alice Applegate. Query for that activity by entering the following call and clicking Send:
    1. GET http://localhost:8180/pc/rest/common/v1/activities?filter=subject:sw:Review%20risk
  3. Note the ID, subject, and checksum of the first activity returned in the response payload. (These values are referred to in later steps as "<ActivityID>", "<originalSubject>", and "<originalChecksum>".)
  4. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
  5. Change the operation to PATCH and enter the following URL, but do not click Send yet:
    1. PATCH http://localhost:8180/pc/rest/common/v1/activities/<ActivityID>
  6. Specify the request payload.
    1. In the first row of tabs (the one that starts with Params), click Body.
    2. In the row of radio buttons, select raw.
    3. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
    4. Paste the following into the text field underneath the radio buttons. For subject, specify the original subject with an additional "-1". 
      {
  "data": {
    "attributes": {
      "subject" : "<originalSubject>-1"
    },
    "checksum": "<originalChecksum>"
  }
}
  7. Click Send. The checksum value in the payload matches the checksum value for the activity stored in PolicyCenter. So, the PATCH should be successful and the response payload should appear below the request payload.
  8. Click Send a second time. Now, the checksum value in the payload does not match the checksum value for the activity calculated by PolicyCenter. So, the second PATCH is unsuccessful and an error message appears.

Tutorial: Assign an activity using checksums

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more information, see Tutorial: Set up your Postman environment.

In this tutorial, you will attempt to execute a business action (assigning an activity) twice. Both attempts will include a checksum value. The first attempt will succeed, and the second will fail.

Tutorial steps

  1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
    1. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
  2. The sample data includes one "Review risk information" activity for Alice Applegate. Query for that activity by entering the following call and clicking Send:
    1. GET http://localhost:8180/pc/rest/common/v1/activities?filter=subject:sw:Review%20risk
  3. Note the ID and checksum of the first activity returned in the response payload. (These values are referred to in later steps as "<ActivityID>", and "<originalChecksum>".)
  4. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
  5. Change the operation to POST and enter the following URL, but do not click Send yet:
    1. POST http://localhost:8180/pc/rest/common/v1/activities/<ActivityID>/assign
  6. The POST /{activityId}/assign endpoint requires a request payload that specifies how the assignment is to be done. Specify the request payload.
    1. In the first row of tabs (the one that starts with Params), click Body.
    2. In the row of radio buttons, select raw.
    3. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
    4. Paste the following into the text field underneath the radio buttons. For subject, specify the original subject with an additional "-1". 
      {
  "data": {
    "attributes": {
        "autoAssign": true
    },
    "checksum": "<originalChecksum>"
  }
}
  7. Click Send. The checksum value in the payload matches the checksum value for the activity stored in PolicyCenter. So, the POST /assign should be successful and the response payload should appear below the request payload.
  8. Click Send a second time. Now, the checksum value in the payload does not match the checksum value for the activity calculated by PolicyCenter. (The successful POST /assign from the previous step will have modified the checksum value.) So, the second POST /assign is unsuccessful and an error message appears.