# Patching The PatchJob element represents a scheduled patching process. This chapter only describes the PatchJob element itself and refers to directly related elements. For explanations on how the patching process itself works and which different patching methods are available (and how they work), please refer to the [Patching Process](https://docs.i3d.net/game-hosting/processes/index) chapter. A PatchJob has several properties that define which [ApplicationInstances](https://docs.i3d.net/game-hosting/elements/application/applicationinstance) you want to update: * DeploymentEnvironment ID (`PatchJob.deploymentEnvironmentId` property) * Application ID (`PatchJob.applicationId` property) * One or more old ApplicationBuild IDs (`PatchJob.applicationBuild` property) * One or more Fleet IDs (`PatchJob.fleet` property) You can preview your instance selection using the endpoint [`POST /v3/patchJob/applicationInstancePreview`](https://docs.i3d.net/api/api_one#v3-patchjob-applicationinstancepreview) which takes the above arguments and returns an array of regions along with the number of instances per region that fall within your selection. All other properties define how the PatchJob behaves. An important one is the `patchJobMethodId` property which states which patching method will be used. E.g. forced update, rolling update or A/B deployment. ## Element structure | Property | Value type | Required | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | id | string | Read-only | Unique identifier of this element | | deploymentEnvironmentId | string | Yes | The PatchJob will apply to instances within this [DeploymentEnvironment](https://docs.i3d.net/game-hosting/elements/deploymentenvironment) | | applicationId | string | Yes | The PatchJob will apply to instances of this [Application](https://docs.i3d.net/game-hosting/elements/application) | | patchJobMethodId | int | Yes | The patching method. You can find a list of available methods via [`GET /v3/patchJob/type`](https://docs.i3d.net/api/api_one#v3-patchjob-type) | | patchJobMethod | string | Read-only | The name of the selected patching method | | patchJobName | string | Yes | The name of the PatchJob | | status | int | Read-only | The status of the PatchJob. You can find a list of available codes via [`GET /v3/patchJob/status`](https://docs.i3d.net/api/api_one#v3-patchjob-status) | | stopMethodId | int | No | The stop method ID to apply if instances need to be stopped. You can find the list available stop methods via [`GET /v3/application/stopMethod`](https://docs.i3d.net/api/api_one#v3-application-stopmethod) | | stopMethodName | string | Read-only | The name of the selected stop method | | stopMethodTimeout | int | No | The maximum time in seconds the system will wait for a graceful stop command to be executed. If the maximum timeout is reached, an implicit, forced stop will be performed | | comments | string | No | Custom comments | | schedulerStartTime | int | No | A unix timestamp for when to start the PatchJob. Must be at least 5 minutes from the time of submission | | patchJobStartTime | int | Read-only | A unix timestamp indicating the actual start time of the PatchJob | | patchJobRunTime | int | No | The maximum run time of a PatchJob. If exceeded, the PatchJob will be forcefully finalized | | patchJobRuntimeType | int | No |

patchJobRunTime unit:
0: seconds (default)
1: minutes
2: hours
3: days

| | patchJobRuntime | string | Read-only | The name of the patchJobRuntimeType | | patchJobOverallProgress | [PatchJobOverallProgress](https://docs.i3d.net/game-hosting/elements/patchjob/patchjoboverallprogress) | Read-only | Current overall state of the PatchJob | | applicationBuild | \[[PatchJobApplicationBuild](https://docs.i3d.net/game-hosting/elements/patchjob/patchjobapplicationbuild)] | Yes | A list of elements defining which ApplicationBuilds must be replaced | | fleet | \[[PatchJobFleet](https://docs.i3d.net/game-hosting/elements/patchjob/patchjobfleet)] | Yes | The PatchJob will apply to instances in these Fleets | | email | \[[PatchJobEmail](https://docs.i3d.net/game-hosting/elements/patchjob/patchjobemail)] | No | A list of PatchJob related email addresses, indicating who to send reports to and which report types | | createdAt | int | Read-only | A unix timestamp of when this element was created | | updatedAt | int | Read-only | A unix timestamp of when this element was last updated | Table 1: PatchJob element structure ## Making adjustments to an existing PatchJob Updating a PatchJob is only allowed up to 5 minutes before the start time of the job. The only exception to this rule are the reporting email addresses, which can be updated at any time. The reason for this is to prevent the system from becoming confused with sudden changes being introduced when the PatchJob has just started running. Additionally, the platform will perform certain operations in preparation for the start of the PatchJob. E.g. we will start distributing the new build software to the hosts 5 minutes before the start time of the job, in order to have a more swift patching process itself. {% hint style="info" %} Once you created a Patch Job for an application that is of type Game, you cannot update it to switch to an application that is of type Utility (or vice-versa). {% endhint %} ## Running PatchJobs in parallel It is possible to create multiple PatchJobs and have them run in parallel, as long as the instance selections of the PatchJobs do not overlap. In other words, if you have more than one PatchJob scheduled at or around the same time and they will (partially) apply to the same ApplicationInstances, only one PatchJob will run at the time - the other one(s) will wait for the first to finish before starting. ## Cancelling a PatchJob You can cancel a pending or running PatchJob at any time. If it has not yet started, its status will simply be changed to CANCELLED and the PatchJob will never run. When you attempt to cancel a PatchJob, you will have two choices: * Cancel and revert. * Cancel and wrap-up (don't do anything). ## API example Create a new PatchJob within your i3D.net account. [Full API reference](https://docs.i3d.net/api/api_one#v3-patchjob) #### HTTP request [`POST /v3/patchJob`](https://docs.i3d.net/api/api_one#v3-patchjob) #### Request body ``` { "deploymentEnvironmentId": "7089186347851060494", "applicationId": "8939460394116420757", "patchJobMethodId": 1, "patchJobName": "Demo Patch Job", "stopMethodId": 0, "stopMethodTimeout": 0, "comments": "Deployment of v2.0.5 - fixes a number of bugs", "schedulerStartTime": 1587405918, "patchJobRunTime": 0, "patchJobRuntimeType": 0, "applicationBuild": [ { "oldApplicationBuildId": "7302942857359174099", "newApplicationBuildId": "6257774125730552445" } ], "fleet": [ { "fleetId": "7089186347851060494" } ], "email": [ { "email": "DemoPatchMonitoring@i3d.net", "progressReport": 1, "resultReport": 1 } ] } ``` #### Response body ``` [ { "id": "7089186347851060494", "deploymentEnvironmentId": "6133202252238171791", "applicationId": "8939460394116420757", "patchJobMethodId": 1, "patchJobMethod": "Forced deployment", "patchJobName": "Demo Patch Job", "status": 8, "stopMethodId": 0, "stopMethodName": "Hard kill", "stopMethodTimeout": 0, "comments": "Deployment of v2.0.5 - fixes a number of bugs", "schedulerStartTime": 1587405918, "patchJobStartTime": 0, "patchJobInstanceRunTime": "Seconds", "patchJobInstanceRuntimeTypeId": 0, "patchJobInstanceRuntime": "Seconds", "patchJobOverallProgress": null, "applicationBuild": [ { "id": "6585830247739430646", "oldApplicationBuildId": "7302942857359174099", "newApplicationBuildId": "6257774125730552445" } ], "fleet": [ { "id": "2956430507214878357", "fleetId": "7089186347851060494" } ], "email": [ { "id": "5874260432191151466", "email": "DemoPatchMonitoring@i3d.net", "progressReport": 1, "resultReport": 1, "createdAt": 1587746121, "changedAt": 0 } ], "createdAt": 1587395426, "changedAt": 0 } ] ```