Skip to main content

createPatchManagementMaintenanceWindow

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

Parameters

Parameter

Description

Included in request

Type

Values

name

The name you want to assign to the Patch Management window.

Mandatory

String

Possible values:

  • Must be between 1 and 80 characters.

  • Must be unique.

companyId

The ID of the company where you want the maintenance window created.

Optional

String

Default value: The ID of the company linked to the user who generated the API key.

Requirements:

  • The user must have Manage Company rights for the selected company.

  • The selected company must have a license that includes access to the Patch Management features.

allowChangeByOtherUsers

Indicates if the target is a Customer company.

Mandatory

Boolean

No additional requirements.

settings

Use this array to configure Patch Management settings for the maintenance window you are creating.

Mandatory

Array of objects

Refer to ???

Objects

downloadSettings

Parameter

Description

Type

Value

cachingServers

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

Array of objects

Contains the following information:

  • id - String, ID of patch caching server.

fallbackOnDirectDownload

Determines if the Direct Download setting is enabled.

Boolean

No additional requirements.

installPatchesSettings

Parameter

Description

Type

Value

enabled

Indicates if the patch applies automatically when enabled. Corresponds to the Apply patch switch in the GravityZone console.

Boolean

No additional requirements.

ifMissedRunAsSoonAsPossible

Indicates that the task, if not performed, will retried it as soon as possible.

Boolean

No additional requirements.

specificVendorAndProduct

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

Object

Contains the following information:

  • enabled - Indicates if inclusions or exclusions are allowed.

    Type: Boolean

  • type - Select between including or excluding vendors or products from being patched.

    Type: Integer

    Possible values:

    • 1 - for Include,

      2 - for Exclude.

  • vendorProductsPairs - , Used to select products and vendors.

    Type: Array of objects

    For more information, refer to vendorProductsPairs.

postponeReboot

Indicate if you would like to postpone a system reboot after applying a patch.

Object

Contains the following information:

  • option - Indicates how the reboot is to be postponed.

    Type: Integer

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

      If this value is assigned, the afterMinutes, afterCustomMessage, and between attributes must also be included in the request.

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

      If this value is assigned, the afterMinutes and afterCustomMessage attributes must also be included in the request.

  • afterMinutes - , number of minutes a reboot will be postponed.

    Type: Integer

    Possible values: 10, 30, 45, 60.

  • afterCustomMessage - The text to be displayed on the endpoint where the reboot will occur.

    Type: String

    Possible values: Any string of maximum 128 characters.

  • between - Time interval when reboot will occur.

    Type: Object

    For more information, refer to between.

updateType

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

Object

Contains the following information:

  • securityPatchesSettings - Enable and configure security patches.

    • enabled - Boolean, enables the use of security patches.

    • scheduler - Sets up a specific schedule.

      Type: Object

      This parameter must be included in the object if:

      • If the enabled parameter under the securityPatchesSettings object has the true value.

      • If the useSameScheduler parameter under the scanPatchesSettings object has the false value.

      This parameter will be ignored if:

      • The useSameScheduler parameter under the scanPatchesSettings object has the true value.

      For more information, refer to scheduler.

    • oldScheduler - Sets up a specific schedule using the fallback system.

      Type: Object

      This parameter must be included in the object if:

      • If the enabled parameter under the securityPatchesSettings object has the true value.

      • If the useSameScheduler parameter under the scanPatchesSettings object has the false value.

      This parameter will be ignored if:

      • The useSameScheduler parameter under the scanPatchesSettings object has the true value.

      For more information, refer to oldScheduler.

  • nonSecurityPatchesSettings - Enable and configure non security patches.

    • enabled - Boolean, enables the use of non security patches.

    • scheduler - Sets up a specific schedule.

      Type: Object

      This parameter must be included in the object if:

      • If the enabled parameter under the nonSecurityPatchesSettings object has the true value.

      • If the useSameScheduler parameter under the scanPatchesSettings object has the false value.

      This parameter will be ignored if:

      • The useSameScheduler parameter under the scanPatchesSettings object has the true value.

      For more information, refer to scheduler.

    • oldScheduler - Sets up a specific schedule using the fallback system.

      Type: Object

      This parameter must be included in the object if:

      • If the enabled parameter under the nonSecurityPatchesSettings object has the true value.

      • If the useSameScheduler parameter under the scanPatchesSettings object has the false value.

      This parameter will be ignored if:

      • The useSameScheduler parameter under the scanPatchesSettings object has the true value.

      For more information, refer to oldScheduler.

  • manuallyApprovedPatchesSettings - Enable and configure manually approved patches.

    • enabled - Boolean, enables the use of manually approved patches.

    • scheduler - Sets up a specific schedule.

      Type: Object

      This parameter must be included in the object if:

      • If the enabled parameter under the securityPatchesSettings object has the false value.

      • If the useSameScheduler parameter under the scanPatchesSettings object has the false value.

      This parameter will be ignored if:

      • The useSameScheduler parameter under the scanPatchesSettings object has the true value.

      For more information, refer to scheduler.

    • oldScheduler - Sets up a specific schedule using the fallback system.

      Type: Object

      This parameter must be included in the object if:

      • If the enabled parameter under the securityPatchesSettings object has the false value.

      • If the useSameScheduler parameter under the scanPatchesSettings object has the false value.

      This parameter will be ignored if:

      • The useSameScheduler parameter under the scanPatchesSettings object has the true value.

      For more information, refer to oldScheduler.

    Note

    If the enabled parameter under the securityPatchesSettings object has the true value, the scheduler and oldScheduler settings under manuallyApprovedPatchesSettings will be ignored.

    If the enabled parameter under the securityPatchesSettings object and the useFallbackSchedule setting under the scanPatchesSettings parameter both have the false value, the scheduler setting under the manuallyApprovedPatchesSettings must be included in the request.

    If the enabled parameter under the securityPatchesSettings object has the false value, and the useFallbackSchedule setting under manuallyApprovedPatchesSettings has the true value, the oldScheduler setting under manuallyApprovedPatchesSettings must be included in the request.

manuallyApprovedPatchIds

A list of unique patch IDs.

Array of strings

The patch IDs must be valid and belong to to the company that the maintenance window is created for.

Tip

You can use the getManuallyApprovedPatches method to get a list of manual patch IDs for a specific company.

Warning

  • If the enabled parameter under the installPatchesSettings object has assigned the true value, you need to assign the true value to one of the following parameters:

    • The enabled parameter under the securityPatchesSettings option. They can be found under the updateType object, located under the installPatchesSettings object.

    • The enabled parameter under the nonSecurityPatchesSettings option. They can be found under the updateType object, located under the installPatchesSettings object.

  • If the enabled parameter under the installPatchesSettings object has assigned the fale value, you need to make sure none of these parameters have the true value assigned:

    • The enabled parameter under the securityPatchesSettings option. They can be found under the updateType object, located under the installPatchesSettings object.

    • The enabled parameter under the nonSecurityPatchesSettings option. They can be found under the updateType object, located under the installPatchesSettings object.

  • If the enabled parameter under the installPatchesSettings object has assigned the true value, the enabled parameter under the scanPatchesSettings object must also have the true value assigned.

vendorProductsPairs

Parameter

Description

Type

Value

os

The operating system the vendor-products pair is compatible with.

You can use this attribute when a specific vendor-products pair is compatible with multiple operating systems.

Integer

Possible values:

  • 1 - Windows

  • 2 - Linux

  • 3 - macOS

Default value:

  • 1, if the id attribute belonging to the vendor object only contains digits.

  • 2, if the id attribute belonging to the vendor object contains letters.

Important

The values provided to this attribute must be compatible the vendor-product pair specified in the request. Using an invalid combination will result in an error.

vendor

Include one or more vendors.

Object

The object contains the following attributes:

  • id - The ID of the vendor.

    Type: String.

products

Include one or more products

Array of objects

The object contains the following attributes:

  • id - The ID of the product.

    Type: String.

between

Parameter

Description

Type

Value

startHour

The hour the event is set to be start.

Integer

It can have a value between 0 and 23.

startMinute

The minute the event is set to be start.

Integer

It can have a value between 0 and 59.

endHour

The hour the event is set to be end.

Integer

It can have a value between startHour and 23.

endminute

The minute the event is set to be end.

Integer

It can have a value between 0 and 59.

Note

startHour:startMinute must be less than endHour:endMinute

scheduler

Parameter

Description

Type

Value

recurrence

Sets the frequency of a specific task

Integer

Possible values:

  • 1 - immediately.

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

    If this value is assigned, the object must also include the weeklyRecurrence parameter.

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

    If this value is selected, the the object must also include the

    monthlyRecurrence parameter.

startDate

Indicates the current epoch time (10 characters, seconds precision) if current day is selected.

Integer

Must be be a value greater than 0.

between

Sets a time interval for running tasks

Object

For more information, refer to between.

weeklyRecurrence

Determines the frequency of a weekly task.

This parameter is only available if recurrence is set to 3.

Object

Contains the following information:

  • every - Sets the time span between running tasks, measured in weeks.

    Type: Integer

    Possible values: 1 - 4.

  • days - Sets the task to recur on a specific day of the week.

    Type: Array of Integers

    Possible values: 0 (Sunday) - 6 (Saturday).

monthlyRecurrence

Determines the frequency of a monthly task.

This parameter is only available if recurrence is set to 4.

Object

Contains the following information:

  • every - Sets the time span between tasks, measured in months.

    Type: Integer

    Possible values: 1 - 12.

  • frequency - Sets the frequency of the recurring tasks.

    Type: Integer

    Possible values:

    • 0 - runs on a specific day of the month.

      If this value is assigned, the object must include the frequencyDayNumber parameter.

      Note

      If the value of frequency is 0, the monthlyRecurrence object

    • 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 1,2, 3,4 or 5, the object must include the frequencyDayOfWeek parameter.

  • frequencyDayNumber - Indicates on which day of the month the task will run.

    Type: Integer

    Possible values: 1 - 31

  • frequencyDayOfWeek -Indicates on which day of the week the task will run.

    Type: Integer

    Possible values: 0 (Sunday) - 6 (Saturday).

oldScheduler

Parameter

Description

Type

Value

recurrence

Sets the frequency for running a task

Integer

Possible values:

  • 1- for immediately

  • 2 - for daily

  • 3 - for weekly

startHour

The hour the event is set to be start.

Integer

Possible values: 0 - 23.

startMinute

The minute the event is set to be start.

Integer

Possible values: 0 - 59.

days

Sets the task to recur on a specific day of the week.

Array of Integers

Possible values: 0 (Sunday) - 6 (Saturday).

scanPatchesSettings

Parameter

Description

Type

Value

enabled

Indicates if scans are automatically made to search for new patches. Corresponds to the Scan for patches switch in the GravityZone console.

Boolean

No additional requirements.

runOnSystemChanges

Indicates if scans are made 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.

Boolean

No additional requirements.

useFallbackSchedule

Switches between the current schedule system (schedule) and the fallback (oldScheduler).

String

Possible values:

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

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

useSameSchedule

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

Boolean

No additional requirements.

scheduler

Sets up a specific schedule.

Objects

Contains the following information

  • 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

Sets up a specific schedule using the fallback system.

Object

Contains the following information:

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

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": [
                        {
                            "os": 3, 
                            "vendor": {
                                "id": "Oracle"
                            },
                            "products": [
                                {
                                    "id": "java-11-openjdk 11"
                                },
                                {
                                    "id": "java-1.8.0-openjdk"
                                }
                            ]
                        },
                        {
                            "vendor": {
                                "id": "Inkscape"
                            },
                            "products": [
                                {
                                    "id": "0"
                                }
                            ]
                        },
                        {
                            "vendor": {
                                "id": "65"
                            },
                            "products": [
                                {
                                    "id": "15694"
                                }
                            ]
                        }         
          ]
        },
        "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
                ]
              }
            },
          },
          "securityPatchesSettings": {
            "enabled": true,
            "scheduler": {
              "recurrence": 1
          },
          "manuallyApprovedPatchesSettings": {
            "enabled": True,
            "scheduler": {
            "recurrence": 1
            }
          }
        }
        "manuallyApprovedPatchIds": [
          "{00016C6E-0000-0000-0000-000000000000}",
          "{0001354A-0000-0000-0000-000000000000}"
        ]
      },
      "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
            ]
          }
        },
      }
    },
    "companyId": "6196964afb457113d33fb25e"
  }
}

Response:

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