Skip to main content

PARTNERS

createPatchManagementMaintenanceWindow

This method creates a maintenance window which you can use in Patch Management.

Parameters

Parameter

Type

Optional

Description

name

String

No

The name of the window. Must be between 1 and 80 characters. Must be unique.

companyId

String

Yes

The ID of the company where you want the maintenance window to be created. The default value is the ID of the company linked to the user who generated the API key.

The ID must belong to a company which is:

  • Managed by the user account

  • A partner company or a customer company with a license that includes Patch Management.

Note

If the target company is a child, the allowChangeByOtherUsers parameter must be set to True.

allowChangeByOtherUsers

Boolean

No

Must be set to True if the company ID belongs to a child company.

settings

Object

No

The settings to be assigned to the window. For more information on the available settings and how to use them refer to Settings

Settings

You can use the settings parameter to modify the Patch Management settings for the maintenance window you are creating.

The available objects are:

downloadSettings

Member

Type

Description

cachingServers

Array of objects

Used to specify which patch caching servers are to be used. Position in array should be interpreted as priority. Each object should contain:

  • id - String, ID of patch caching server

Needed validations :

  • ids should belong to the company for which the maintenance window is created.

  • ids should be of relays that have specifics.isPatchManagementServer = true.

fallbackOnDirectDownload

Boolean

Toggles fallback on Direct Download setting on/off.

Note

Must be true if cachingServers is empty

scanPatchesSettings

Member

Type

Description

enabled

Boolean

When enabled, scans are automatically made to search for new patches. Corresponds to the Scan for patches switch in the GravityZone console.

runOnSystemChanges

Boolean

Scans for available patches whenever installing a new supported application. Corresponds to the Smart scan for patches when new applications are installed switch in the GravityZone console.

useFallbackSchedule

Boolean

Switches between the current schedule system (schedule) and the fallback (oldScheduler). It can have one of the following values::

  • enabled - the oldScheduler parameter must be included in installPatchesSettings.

  • disabled - the scheduler parameter must be included in installPatchesSettings.

useSameSchedule

Boolean

Sets this schedule as default for all tasks. Corresponds to the Use the same schedule for all targeted operations switch in the GravityZone console.

scheduler

Object

Sets up a specific schedule.

Components:

  • recurrence - Integer, sets the frequency of a specific task. It can have one of the following values:

    • 3 - weekly. In this case, it must also include the weeklyRecurrence object.

    • 4 - monthly. In this case, it must must also include the monthlyRecurrence object.

  • startDate - Integer, indicates the current epoch time (10 characters, seconds precision) if current day is selected. Should be a value greater than 0.

  • between - Object, sets a time interval for running tasks. Components:

    • startHour - Integer, between 0 and 23

    • startMinute - Integer, between 0 and 59

    • endHour - Integer, between startHour and 23

    • endMinute - Integer, between 0 and 59

      Note

      startHour:startMinute must be less than endHour:endMinute

  • weeklyRecurrence - Object, required if recurrence = 3. Components:

    • every - Integer, value range of between 1 and 4. Sets the time span between running tasks, measured in weeks.

    • days - Integer array, value range between 0 and 6 (with 0 being Sunday and 6 being Saturday). Sets the task to recur on a specific day of the week.

  • monthlyRecurrence - Object, required if recurrence = 4. Components:

    • every - Integer, value range between 1 and12. Sets the time span between tasks, measured in months.

    • frequency - Integer, sets the frequency of the reccuring tasks. It can have one of the following values:

      • 0 - runs on a specific day

      • 1 - runs on the first frequencyDayOfWeek of the week in month.

      • 2 - runs on the second frequencyDayOfWeek of the week in month.

      • 3 - runs on the third frequencyDayOfWeek of the week in month.

      • 4 - runs on the fourth frequencyDayOfWeek of the week in month.

      • 5 - runs on the last frequencyDayOfWeek of the week in month.

        Note

        If the value of frequency is 0, the monthlyRecurrence object must also include frequencyDayNumber. If the value of frequency is 1,2, 3,4 or 5, the monthlyRecurrence object must also include frequencyDayOfWeek.

    • frequencyDayNumber - Integer, indicates on which day of the month the task will run. The value ranges between 1 and 31.

    • frequencyDayOfWeek Integer, indicates on which day of the week the task will run. The value ranged between 0 and 6, with 0 being Sunday and 6 being Saturday.

Note

Must be included if enabled = true and useFallbackSchedule = false.

oldScheduler

Object

Sets up a specific schedule using the fallback system.

Components:

  • recurrence - Integer, sets the frequency for running a task. It can have one of the following values:

    • 2 - for daily

    • 3 - for weekly

  • startHour - Integer. It can have a value between 0 and 23.

  • startMinute - Integer. It can have a value between 0 and 59.

  • days - Integer array, value range between 0 and 6 (with 0 being Sunday and 6 being Saturday). Sets the task to recur on a specific day of the week.

    Note

    Must be included if enabled = true. Ignored if recurrence = 2.

installPatchesSettings

Member

Type

Description

enabled

Boolean

When enabled, patches are automatically applied when available. Corresponds to the Apply patch switch in the GravityZone console.

ifMissedRunAsSoonAsPossible

Boolean

If true, a scheduled task that has not been performed, will be retried it as soon as possible.

specificVendorAndProduct

Object

Specify which vendors and products you would like to include or exclude from being patched.

Components:

  • enabled - Boolean, indicates if inclusions or exclusions are allowed.

  • type - Integer, select between including or excluding vendors or products from being patched. It can have one of the following values:

    • 1 - for Include,

      2 - for Exclude.

  • vendorProductsPairs - Array of objects, used to select products and vendors . Components:

    • vendor - Object, include one or more vendors. Object components:

      • id, string

    • products - Array of objects, include one or more products . Object components:

      • id, string

postponeReboot

Object

Object components:

  • option - Integer, how how a reboot can be postponed. It can have one of the following values:

    • 0 - Users may postpone the system restart until a more convenient time.

    • 1 - Users may postpone the system restart only within a specific interval. selected, the postponeReboot object must also contain: afterMinutes, afterCustomMessage, and between.

    • 2 - System restarts automatically after a specific number of minutes. If selected, the postponeReboot object must also contain: afterMinutes, afterCustomMessage.

  • afterMinutes - Integer, number of minutes a reboot will be postponed. It can have one of the following set values: 10, 30, 45, 60.

  • afterCustomMessage - String (maximum 128 characters), the text to be displayed on the endpoint where the reboot will occur.

  • between - Object, time interval when reboot will occur. Components:

    • startHour - Integer. It can have a value between 0 and 23.

    • startMinute - Integer. It can have a value between 0 and 59.

    • endHour - Integer. It can have a value between startHour and 23.

    • endminute - Integer. It can have a value between 0 and 59.

      Note

      startHour:startMinute must be less than endHour:endMinute

updateType

Object

Used to enable and apply specific settings to either security or non security updates. Object components:

  • securityPatchesSettings - Object. Components:

    • enabled - Boolean

    • scheduler - Object

      Sets up a specific schedule.

      Components:

      • recurrence - Integer, sets the frequency of a specific task. It can have one of the following values:

        • 1 - immediately.

        • 3 - weekly. In this case, it must also include the weeklyRecurrence object.

        • 4 - monthly. In this case, it must must also include the monthlyRecurrence object.

      • startDate - Integer, indicates the current epoch time (10 characters, seconds precision) if current day is selected. Should be a value greater than 0.

      • between - Object, sets a time interval for running tasks. Components:

        • startHour - Integer, between 0 and 23

        • startMinute - Integer, between 0 and 59

        • endHour - Integer, between startHour and 23

        • endMinute - Integer, between 0 and 59

          Note

          startHour:startMinute must be less than endHour:endMinute

      • weeklyRecurrence - Object, required if recurrence = 3. Components:

        • every - Integer, value range of between 1 and 4. Sets the time span between running tasks, measured in weeks.

        • days - Integer array, value range between 0 and 6 (with 0 being Sunday and 6 being Saturday). Sets the task to recur on a specific day of the week.

      • monthlyRecurrence - Object, required if recurrence = 4. Components:

        • every - Integer, value range between 1 and12. Sets the time span between tasks, measured in months.

        • frequency - Integer, sets the frequency of the reccuring tasks. It can have one of the following values:

          • 0 - runs on a specific day

          • 1 - runs on the first frequencyDayOfWeek of the week in month.

          • 2 - runs on the second frequencyDayOfWeek of the week in month.

          • 3 - runs on the third frequencyDayOfWeek of the week in month.

          • 4 - runs on the fourth frequencyDayOfWeek of the week in month.

          • 5 - runs on the last frequencyDayOfWeek of the week in month.

            Note

            If the value of frequency is 0, the monthlyRecurrence object must also include frequencyDayNumber. If the value of frequency is 1,2, 3,4 or 5, the monthlyRecurrence object must also include frequencyDayOfWeek.

        • frequencyDayNumber - Integer, indicates on which day of the month the task will run. The value ranges between 1 and 31.

        • frequencyDayOfWeek Integer, indicates on which day of the week the task will run. The value ranged between 0 and 6, with 0 being Sunday and 6 being Saturday.

      Note

      Must be included if securityPatchesSettings.enabled = true, scanPatchesSettings.useSameScheduler = false and scanPatchesSettings.useFallbackSchedule = false. Will be ignored if scanPatchesSettings.useSameScheduler = true.

  • oldScheduler - Object

    Sets up a specific schedule using the fallback system.

    Components:

    • recurrence - Integer, sets the frequency for running a task. It can have one of the following values:

      • 1- for immediately

      • 2 - for daily

      • 3 - for weekly

    • startHour - Integer. It can have a value between 0 and 23.

    • startMinute - Integer. It can have a value between 0 and 59.

    • days - Integer array, value range between 0 and 6 (with 0 being Sunday and 6 being Saturday). Sets the task to recur on a specific day of the week.

      Note

      Must be included if securityPatchesSettings.enabled = true, scanPatchesSettings.useSameScheduler = false and scanPatchesSettings.useFallbackSchedule = true. Is not required and will be ignored if scanPatchesSettings.useSameScheduler = true.

Warning

  • If specifics.installPatchesSettings.enabled = true, at least one of the following 2 must be enabled:

    • specifics.installPatchesSettings.updateType.securityPatchesSettings.enabled

    • specifics.installPatchesSettings.updateType.nonSecurityPatchesSettings.enabled

  • if specifics.installPatchesSettings.enabled = false, both must also be false:

    • specifics.installPatchesSettings.updateType.securityPatchesSettings.enabled

    • specifics.installPatchesSettings.updateType.nonSecurityPatchesSettings.enabled

  • if specifics.installPatchesSettings.enabled = true, specifics.scanPatchesSettings.enabled must be true.

Return value

This method returns a value of true or false, indicating if the maintenance window was successfully created.

Example

Request:

{
  "method": "createPatchManagementMaintenanceWindow",
  "id": "a7f1d11d-3c94-47f0-a599-b48d2fc44241",
  "jsonrpc": "2.0",
  "params": {
    "name": "QXPzQWvgtqtI4FlCRSU9z",
    "allowChangeByOtherUsers": true,
    "settings": {
      "downloadSettings": {
        "cachingServers": [
          
        ],
        "fallbackOnDirectDownload": true
      },
      "installPatchesSettings": {
        "enabled": true,
        "ifMissedRunAsSoonAsPossible": true,
        "specificVendorAndProduct": {
          "type": 1,
          "enabled": false,
          "vendorProductsPairs": [
            
          ]
        },
        "postponeReboot": {
          "option": 0
        },
        "updateType": {
          "nonSecurityPatchesSettings": {
            "enabled": true,
            "scheduler": {
              "recurrence": 3,
              "startDate": 1637258826,
              "between": {
                "startHour": 21,
                "startMinute": 0,
                "endHour": 23,
                "endMinute": 59
              },
              "weeklyRecurrence": {
                "every": 1,
                "days": [
                  1,
                  2,
                  3,
                  4,
                  5,
                  6,
                  0
                ]
              }
            },
            "oldScheduler": {
              "recurrence": 1
            }
          },
          "securityPatchesSettings": {
            "enabled": true,
            "scheduler": {
              "recurrence": 1
            },
            "oldScheduler": {
              "recurrence": 1
            }
          }
        }
      },
      "scanPatchesSettings": {
        "enabled": true,
        "useSameSchedule": false,
        "useFallbackSchedule": true,
        "runOnSystemChanges": true,
        "scheduler": {
          "recurrence": 3,
          "startDate": 1637258826,
          "between": {
            "startHour": 21,
            "startMinute": 0,
            "endHour": 23,
            "endMinute": 59
          },
          "weeklyRecurrence": {
            "every": 1,
            "days": [
              1,
              2,
              3,
              4,
              5,
              6,
              0
            ]
          }
        },
        "oldScheduler": {
          "recurrence": 2,
          "startHour": 21,
          "startMinute": 0
        }
      }
    },
    "companyId": "6196964afb457113d33fb25e"
  }
}

Response:

{
   "id" : "a7f1d11d-3c94-47f0-a599-b48d2fc44241",
   "jsonrpc" : "2.0",
   "result" : {
      "data" : [
         "61969696af703331ad53a948"
      ],
      "success" : true
   }
}
In this section: