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

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": "[e-mail]",
      "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": "[e-mail]",
                "progressReport": 1,
                "resultReport": 1,
                "createdAt": 1587746121,
                "changedAt": 0
            }
        ],
        "createdAt": 1587395426,
        "changedAt": 0
    }
]