Skip to content

PatchJob

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 chapter.

A PatchJob has several properties that define which ApplicationInstances 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 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
applicationId string Yes The PatchJob will apply to instances of this Application
patchJobMethodId int Yes The patching method. You can find a list of available methods via GET /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
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
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 Read-only Current overall state of the PatchJob
applicationBuild [PatchJobApplicationBuild] Yes A list of elements defining which ApplicationBuilds must be replaced
fleet [PatchJobFleet] Yes The PatchJob will apply to instances in these Fleets
email [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.

Note

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).

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

HTTP request

POST /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
    }
]