Bulk patches

Based on the set of search results from the steps above and any new property versions you needed to create, you can now launch a bulk patch to modify them.

🚧
If you run a bulk patch that misconfigures your properties, it can adversely affect the performance of your web content. Make sure to thoroughly test any bulk patches on the staging network before activating on production.

Launch a bulk patch job

Review the results array from the earlier bulk search GET response. You'll need to build a simple JSON Patch operation for each of the matchLocations, and apply it to the newly created version:

[
    {
        "propertyId": "prp_1",
        "propertyVersion": 1,
        "stagingStatus": "ACTIVE",
        "productionStatus": "INACTIVE",
        "lastModifiedTime": "2018-01-18T00:00:00Z",
        "matchLocations": [
            "/rules/behaviors/0/options/hostname"
        ]
    },
    {
        "propertyId": "prp_15",
        "propertyVersion": 2,
        "stagingStatus": "INACTIVE",
        "productionStatus": "ACTIVE",
        "lastModifiedTime": "2018-01-18T00:00:00Z",
        "matchLocations": [
            "/rules/behaviors/0/options/hostname"
        ]
    }
]

Create a new bulk patch request object, as in the example below. For each pairing of property ID and version from the original results, specify an object with:

the propertyId.
the newly created propertyVersion number, or the original value if no versioning was necessary.
an optional etag for any bulk-versioned properties.

From the property ID and version pairings in the original search results, you need the JSON pointer expressions that appear in the matchLocations to build a series of patches with corresponding JSON Patch operations. Pass in the original value from the matchLocations as the path. Also specify the new value you want to change it to. Specify the JSON Patch operation (op) as replace:

{
    "patchPropertyVersions": [
        {
            "propertyId": "prp_15",
            "propertyVersion": 3,
            "etag": "343410c585cf67fc",
            "patches": [
                {
                    "op": "replace",
                    "path": "/rules/behaviors/0/options/hostname",
                    "value": "new.example.com"
                }
            ]
        },
        {
            "propertyId": "prp_3",
            "propertyVersion": 11,
            "etag": "3333333c33cc333",
            "patches": [
                {
                    "op": "replace",
                    "path": "/rules/behaviors/0/options/hostname",
                    "value": "new.example.com"
                }
            ]
        }
    ]
}

👍
Make sure that the replacement value specifies the same JSON data type as the original match, or the update fails.

Once you refine your set of patches, POST the object to this URL:

POST /papi/v1/bulk/rules-patch-requests

See Bulk patch a set of properties for details on the operation. It repeatedly invokes a lower-level Patch a rule tree operation, which you can use to modify an individual configuration.

Again, once you launch the bulk patch process, the response's Location header and JSON response object provides a navigable link to check on its progress:

{
    "bulkPatchLink": "/papi/v1/bulk/rules-patch-requests/42"
}

Check bulk patch status

Once you have launched a bulk patch request, GET the response's bulkPatchLink URL to check on progress. For details on this operation, see List bulk-patched properties:

{
    "bulkPatchId": 7,
    "bulkPatchStatus": "COMPLETE",
    "bulkPatchSubmitDate": "2018-01-18T00:00:00Z",
    "bulkPatchUpdateDate": "2018-01-18T01:00:00Z",
    "patchPropertyVersions": [
        {
            "propertyId": "prp_15",
            "propertyVersion": 3,
            "etag": "343410c585cf67fc",
            "status": "UPDATED",
            "patchSubmitDate": "2018-01-18T00:00:00Z",
            "patchUpdateDate": "2018-01-18T00:00:00Z",
            "propertyVersionRulesLink": "/papi/v1/properties/prp_1/versions/1/rules",
            "patches": [
                {
                    "op": "replace",
                    "path": "/rules/behaviors/0/options/hostname",
                    "value": "new.example.com"
                }
            ]
        },
        {
            "propertyId": "prp_3",
            "propertyVersion": 11,
            "status": "FATAL_ERROR",
            "patchSubmitDate": "2018-01-18T00:00:00Z",
            "patchUpdateDate": "2018-01-18T00:00:00Z",
            "fatalError": "BAD SYNTAX UNABLE TO SAVE",
            "patches": [
                {
                    "op": "replace",
                    "path": "/rules/behaviors/0/options/hostname",
                    "value": "new.example.com"
                }
            ]
        }
    ]
}

Following the same pattern of other asynchronous responses, the response reflects back the original set of requested patchPropertyVersions, but with additional status for each property version's update progress. The bulkPatchStatus reflects the status of the overall bulk patch process. If its value isn't yet COMPLETE when you poll the operation, wait some time and call the operation again later.

👍
Once you complete a single bulk patch operation, you can run additional bulk searches to update other values. From the search results, remove any active property versions. Doing so confines further updates to the set you just modified.

Possible bulk patch errors

Once the bulkPatchStatus of the bulk patch's GET response is COMPLETE, there may still be problems with individual updates. For each object in the patchPropertyVersions array, check the patchPropertyVersionStatus value:

If it's FATAL_ERROR, something prevented the property from updating, and an additional fatalError member provides guidance. The problem may be caused by invalid JSON Patch syntax, an invalid replacement value, or a mismatching etag digest.

In the example discussed above, patching in a replacement value that's not a valid hostname would cause a fatal error.
If it's UPDATED, and no papiWarnings or papiErrors are present, you can go ahead and activate the property as discussed in the next section.
If it's UPDATED but there's a papiErrors array, the property was saved, but you can't activate it in its current state with errors present. Either modify each configuration individually to remove the error, or remove them from the batch to activate.
If it's UPDATED but there's a papiWarnings and with no accompanying papiErrors, you can activate the property in the next step by acknowledging all the warnings. Warnings don't necessarily indicate an actual problem. You can GET the propertyVersionRulesLink URL and scrutinize the warnings from the configuration to research the issue.

For details on the range of errors and warnings that may appear in PAPI configurations, see the Errors section.