REST API for Oracle Java Cloud Service

Patch a Service Instance

You can patch an Oracle Java Cloud Service instance using the REST API, as described in the following procedure.

Note:

Do not use this procedure if you are upgrading the WebLogic Server version on your Oracle Java Cloud Service instance. See Upgrade the WebLogic Server Version for an Oracle Java Cloud Service Instance in Administering Oracle Java Cloud Service.
Patching is not supported for Oracle Java Cloud Service instances if you have installed any product that modifies MW_HOME (such as Oracle WebCenter Portal and Oracle Data Integrator). Patching is also not supported if you are reusing a license via the Bring Your Own License (BYOL) entitlement (for any product that modifies MW_HOME). Because patching replaces the contents of MW_HOME, patching prechecks flag this condition and patching fails.
On accounts that are integrated with Oracle Identity Cloud Service, the identity domain ID is the Identity Cloud Service tenant name. This tenant name begins with the characters idcs-followed by a string of number and letters (for example, idcs-98888f7964454b658ac6d2f625b29030). Access the Oracle Identity Cloud Service Console in a browser to find the tenant name in the URL. You can also find the name when you sign in to your Oracle Cloud account, navigate to Identity and then select Federation.
The cURL command examples use the URL structure https://rest_server_url/resource-path, where rest_server_url is the REST server to contact for your identity domain. See Send Requests.

You cannot apply a patch when the backup service for the specified service instance is in a DISABLED state.

When patching an instance that has a Coherence data tier, review the default values of the request attributes needed to support patching a Managed Coherence Server before applying a patch. By default, the patching process performs a rolling restart of the Managed Coherence Servers. Maintaining data is achieved by checking that the StatusHA state for a Coherence member is NODE-SAFE before shutting down the node to apply the patch. See Apply a Patch.

To patch an Oracle Java Cloud Service instance:

Review the list of available patches that are currently defined to retrieve the patch ID.

curl -i -X GET -u username:password -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/api/v1.1/instancemgmt/ExampleIdentityDomain/services/jaas/instances/ExampleInstance/patches/available

Specify the following options on the cURL command line:

-i option to include the HTTP header in the output. This option is optional.
-X option to indicate the type of request (GET).
-u option to specify the user name and password for the Oracle Java Cloud Service account for authentication.
-H to define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.

If there are no patches available, you will see an empty [] in the response.

The following example shows one available patch in the response. Find the patch ID of the patch you want to apply. In this example, the patch ID is Patch_jdk1.7.0_95.

[{
   "availablePatchGuiMetadata":{"supportsPreCheck":true},
   "patchId":"Patch_jdk1.7.0_95",
   "patchNumber":"1.7.0_95",
   "patchCategory":"JDK",
   "patchSeverity":"Normal",
   "patchDescription":"Update to latest version of JDK, 1.7.0_95.",
   "patchReleaseUrl":"http://www.oracle.com/technetwork/java/javase/7u95-relnotes-2775806.html",
   "serviceType":"JaaS",
   "serviceVersion":"12cR4",
   "releaseDate":"Jan 15, 2016 8:00:00 AM",
   "entryDate":"Apr 3, 2016 4:06:34 AM",
   "entryUserId":"user",
   "componentPatches":
   {
      "JDK":
      {
         "id":1167,
         "version":"1.7.0_95",
         "releaseVersion":"1.7.0_95",
         "zipBundles":
         {
            "JDK":
            {
               "id":1134,
               "md5sum":"4d26465bff5b0744ff7ccbeed11dd308",
               "provisioningObjectRef":"JDK/7.0.95/151225/jdk.zip",
               "storageKey":"PATCH/JDK/jdk1.7.0_95",
               "zipVersion":"1.7.0_95"
            }
         }
      }
   },
   "patchType":"JDK",
   "requiresRestart":true,
   "serviceTypeVersions":"ANY",
   "isDeleted":false,
   "minToolsVersion":"15.1.3-0-1501230343",
   "displayName":"1.7.0_95",
   "releaseVersion":"1.7.0_95"
}]

Before applying a patch, perform a patching precheck to identity potential issues that might prevent the patch from completing successfully, without actually patching.
```
curl -i -X PUT -u username:password -d @emptyfile.json -H "Content-Type:application/json" -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/api/v1.1/instancemgmt/ExampleIdentityDomain/services/jaas/instances/ExampleInstance/patches/checks/Patch_jdk1.7.0_95
```
Specify the following options on the cURL command line:
- -i option to include the HTTP header in the output. This option is optional.
- -X option to indicate the type of request (PUT).
- -u option to specify the user name and password for the Oracle Java Cloud Service account for authentication.
- -d option to identify an empty request document. No parameters are supported in the payload at this time.
- -H to identify the content type as application/json, and define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.
The following provides an example of the response body, in JSON format.
```
{
   "details":
   {
      "jobId":"671344",
      "message":"JCS-PATCHING-5227: Pre-Checking service for patch [Patch_jdk1.7.0_95] is submitted as an asynchronous job."
   },
   "status":"Completed"
}
```
Check the status of the patching precheck operation.
```
curl -i -X GET -u username:password -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/api/v1.1/instancemgmt/ExampleIdentityDomain/services/jaas/instances/ExampleInstance/patches/checks/job/671344
```
Specify the following options on the cURL command line:
- -i option to include the HTTP header in the output. This option is optional.
- -X option to indicate the type of request (GET).
- -u option to specify the user name and password for the Oracle Java Cloud Service account for authentication.
- -H to define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.
The following provides an example of the response body in JSON format. In this example, the status of the patching precheck operation indicates that no changes are required in the environment in order for the patch to complete successfully.
```
{
   "id":602,
   "jobId":"671344",
   "patchId":"Patch_jdk1.7.0_95",
   "jsonResult":"{\"resultMessage\":\"Completed\",\"messages\":[]}",
   "startDate":"May 6, 2016 6:27:53 PM",
   "endDate":"May 6, 2016 6:29:11 PM",
   "performedBy":"username",
   "inProgress":false,
   "status":"PASSED_PRECHECK",
   "preCheckMessages":[]
}
```
Create a JSON document, patch.json, to add a note about the patch information.
For example:
```
{
    "additionalNote":"Applying JDK patch"
}
```
Patch the Oracle Java Cloud Service instance, passing in the JSON document created in the previous step.
```
curl -i -X PUT -u username:password -d @patch.json -H "Content-Type:application/json" -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/api/v1.1/instancemgmt/ExampleIdentityDomain/services/jaas/instances/ExampleInstance/patches/Patch_jdk1.7.0_95
```
Specify the following options on the cURL command line:
- -i option to include the HTTP header in the output. This option is optional.
- -X option to indicate the type of request (PUT).
- -u option to specify the user name and password for the Oracle Java Cloud Service account for authentication.
- -d option to identify the request document, in JSON format, on the local machine (patch.json)
- -H to identify the content type as application/json, and define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.
The following shows an example of the response in JSON format.
```
{
   "details":
   {
      "jobId":"670607",
      "message":"JCS-PATCHING-5068: Patching service with patch [Patch_jdk1.7.0_95] is submitted as an asynchronous job."
   },
   "status":"Completed"
}
```

Check the status of the patching operation by viewing applied patches.

curl -i -X GET -u username:password -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/api/v1.1/instancemgmt/ExampleIdentityDomain/services/jaas/instances/ExampleInstance/patches/applied

Specify the following options on the cURL command line:

-i option to include the HTTP header in the output. This option is optional.
-X option to indicate the type of request (GET).
-u option to specify the user name and password for the Oracle Java Cloud Service account for authentication.
-H to define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.

The following provides an example of the response body in JSON format. Locate the Job ID returned in the previous step, then find the ID value of the patch operation. In this example, the job ID is 670607, and the ID of the patch operation is 78991.

[{
   "backupStatus":"Unknown",
   "additionalNote":"Applying JDK patch",
   "appliedBy":"username",
   "appliedDate":"May 6, 2016 8:55:42 PM",
   "totalTime":"0 min, 0 sec",
   "patchId":"Patch_jdk1.7.0_95",
   "patchDescription":"Update to latest version of JDK, 1.7.0_95.",
   "patchReleaseUrl":"http://www.oracle.com/technetwork/java/javase/7u95-relnotes-2775806.html",
   "releaseDate":"Jan 15, 2016 8:00:00 AM",
   "resultMessage":"Patching in progress",
   "lastStatus":"IN_PROGRESS",
   "lastStatusMessage":"Patching in progress",
   "componentPatches":
   {
      "JDK":
      {
         "id":1167,
         "version":"1.7.0_95",
         "releaseVersion":"1.7.0_95",
         "zipBundles":
         {
            "JDK":
            {
               "id":1134,
               "md5sum":"4d26465bff5b0744ff7ccbeed11dd308",
               "provisioningObjectRef":"JDK/7.0.95/151225/jdk.zip",
               "storageKey":"PATCH/JDK/jdk1.7.0_95",
               "zipVersion":"1.7.0_95"
            }
         }
      }
   },
   "patchType":"JDK",
   "patchCategory":"JDK",
   "patchSeverity":"Normal",
   "jobId":"670607",
   "displayName":"1.7.0_95",
   "inProgress":true,
   "operationType":"Patching",
   "id":78991,
   "patchingResult":
   {
      "patchingId":76841,
      "versionBeforeThisPatch":"JDK 1.7.0_91",
      "strategy":"Rolling",
      "customRollbackId":"670607_1462568142007",
      "startDate":"May 6, 2016 8:55:42 PM",
      "endDate":"May 6, 2016 8:55:42 PM",
      "patchingStatus":"IN_PROGRESS",
      "resultMessage":"Patching in progress",
      "additionalNote":"Applying JDK patch",
      "appliedBy":"username",
      "jobId":"670607",
      "completeLog":"",
      "progressMessages":
      [
         "8:55:41.996 PM Phase initialize started",
         "8:55:42.045 PM Phase initialize completed",
         "8:55:42.084 PM Phase pre-check started",
         "8:55:42.143 PM Phase pre-check-rex started"
      ]
   },
   "rollbackId":"78991",
   "currentPatchLevel":"JDK 1.7.0_95"
}]

When the patch operation is completed, use the unique ID of the patch operation to view complete details of the patch operation.

curl -i -X GET -u username:password -H "X-ID-TENANT-NAME:ExampleIdentityDomain" https://rest_server_url/paas/api/v1.1/instancemgmt/ExampleIdentityDomain/services/jaas/instances/ExampleInstance/patches/applied/78991

Specify the following options on the cURL command line:

-i option to include the HTTP header in the output. This option is optional.
-X option to indicate the type of request (GET).
-u option to specify the user name and password for the Oracle Java Cloud Service account for authentication.
-H to define a custom header, X-ID-TENANT-NAME, to identify the identity domain ID.

The following provides an example of the response body, in JSON format.

[
   {
      "backupStatus":"Available",
      "additionalNote":"Applying JDK patch",
      "appliedBy":"username",
      "appliedDate":"May 6, 2016 8:55:42 PM",
      "totalTime":"39 min, 52 sec",
      "patchId":"Patch_jdk1.7.0_95",
      "patchDescription":"Update to latest version of JDK, 1.7.0_95.",
      "patchReleaseUrl":"http://www.oracle.com/technetwork/java/javase/7u95-relnotes-2775806.html",
      "releaseDate":"Jan 15, 2016 8:00:00 AM",
      "resultMessage":"Completed",
      "lastStatus":"COMPLETED",
      "lastStatusMessage":"Completed",
      "componentPatches":
      {
         "JDK":
         {
            "id":1167,
            "version":"1.7.0_95",
            "releaseVersion":"1.7.0_95",
            "zipBundles":
            {
               "JDK":
               {
                  "id":1134,
                  "md5sum":"4d26465bff5b0744ff7ccbeed11dd308",
                  "provisioningObjectRef":"JDK/7.0.95/151225/jdk.zip",
                  "storageKey":"PATCH/JDK/jdk1.7.0_95",
                  "zipVersion":"1.7.0_95"
               }
            }
         }
      },
      "patchType":"JDK",
      "patchCategory":"JDK",
      "patchSeverity":"Normal",
      "jobId":"670607",
      "displayName":"1.7.0_95",
      "backupId":"1462569267815",
      "inProgress":false,
      "operationType":"None",
      "id":78991,
      "patchingResult":
      {
         "patchingId":76841,
         "backupId":"1462569267815",
         "versionBeforeThisPatch":"JDK 1.7.0_91",
         "strategy":"Rolling",
         "customRollbackId":"670607_1462568142007",
         "startDate":"May 6, 2016 8:55:42 PM",
         "endDate":"May 6, 2016 9:35:34 PM",
         "patchingStatus":"COMPLETED",
         "resultMessage":"Completed",
         "additionalNote":"Applying JDK patch",
         "appliedBy":"username",
         "jobId":"670607",
         "completeLog":"",
         "progressMessages":
         [
            "8:55:41.996 PM Phase initialize started",
            "8:55:42.045 PM Phase initialize completed",
            "8:55:42.084 PM Phase pre-check started",
            "8:55:42.143 PM Phase pre-check-rex started",
            ...
            "9:35:33.639 PM Phase patch-rex completed",
            "9:35:33.954 PM Phase patch completed",
            "9:35:34.016 PM Phase finalize started",
            "9:35:34.057 PM Completed"
         ]
      },
      "rollbackId":"78991",
      "rollbackVersion":"JDK 1.7.0_91",
      "currentPatchLevel":"JDK 1.7.0_95"
   }
]