/

The Amazon SSM multi-region endpoint

http://ssm.{region}.amazonaws.com

POST

Modifies a task assigned to a maintenance window. You can't change the task type, but you can change the following values:

TaskARN. For example, you can change a RUN_COMMAND task from AWS-RunPowerShellScript to AWS-RunShellScript.
ServiceRoleArn
TaskInvocationParameters
Priority
MaxConcurrency
MaxErrors

If the value for a parameter in UpdateMaintenanceWindowTask is null, then the corresponding field isn't modified. If you set Replace to true, then all fields required by the RegisterTaskWithMaintenanceWindow operation are required for this request. Optional fields that aren't specified are set to null.

Request Example

Shell

JavaScript

Java

Swift

curl --location -g --request POST 'http://ssm.{region}.amazonaws.com/' \
--header 'X-Amz-Target;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "WindowId": "string",
    "WindowTaskId": "string",
    "Targets": [],
    "TaskArn": "string",
    "ServiceRoleArn": "string",
    "TaskParameters": {
        "property1": {
            "Values": []
        }
    },
    "TaskInvocationParameters": {
        "RunCommand": {},
        "Automation": {
            "DocumentVersion": "string",
            "Parameters": {
                "property1": [
                    "string"
                ],
                "property2": [
                    "string"
                ]
            }
        },
        "StepFunctions": {},
        "Lambda": {}
    },
    "Priority": 0,
    "MaxConcurrency": "string",
    "MaxErrors": "string",
    "LoggingInfo": {},
    "Name": "string",
    "Description": "string",
    "Replace": true,
    "CutoffBehavior": "CONTINUE_TASK",
    "AlarmConfiguration": {
        "IgnorePollAlarmFailure": true,
        "Alarms": []
    }
}'

Response Example

200 - Example 1

{
    "WindowId": "string",
    "WindowTaskId": "string",
    "Targets": [],
    "TaskArn": "string",
    "ServiceRoleArn": "string",
    "TaskParameters": {
        "property1": {
            "Values": []
        }
    },
    "TaskInvocationParameters": {
        "RunCommand": {},
        "Automation": {
            "DocumentVersion": "string",
            "Parameters": {
                "property1": [
                    "string"
                ],
                "property2": [
                    "string"
                ]
            }
        },
        "StepFunctions": {},
        "Lambda": {}
    },
    "Priority": 0,
    "MaxConcurrency": "string",
    "MaxErrors": "string",
    "LoggingInfo": {},
    "Name": "string",
    "Description": "string",
    "CutoffBehavior": "CONTINUE_TASK",
    "AlarmConfiguration": {
        "IgnorePollAlarmFailure": true,
        "Alarms": []
    }
}

Request

Header Params

X-Amz-Target

string

required

Body Params application/json

WindowId

string

required

The maintenance window ID that contains the task to modify.

>= 20 characters<= 20 characters

Match pattern:

^mw-[0-9a-f]{17}$

WindowTaskId

string

required

The task ID to modify.

>= 36 characters<= 36 characters

Match pattern:

^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$

Targets

array [object]

optional

The targets (either managed nodes or tags) to modify. Managed nodes are specified using the format Key=instanceids,Values=instanceID_1,instanceID_2. Tags are specified using the format Key=tag_name,Values=tag_value.

>= 0 items<= 5 items

TaskArn

string

optional

The task ARN to modify.

>= 1 characters<= 1600 characters

ServiceRoleArn

string

optional

The Amazon Resource Name (ARN) of the IAM service role for Amazon Web Services Systems Manager to assume when running a maintenance window task. If you do not specify a service role ARN, Systems Manager uses your account's service-linked role. If no service-linked role for Systems Manager exists in your account, it is created when you run RegisterTaskWithMaintenanceWindow.

For more information, see the following topics in the in the Amazon Web Services Systems Manager User Guide:

TaskParameters

object

optional

The parameters to modify.

The map has the following format:

Key: string, between 1 and 255 characters

Value: an array of strings, each string is between 1 and 255 characters

TaskInvocationParameters

object

optional

The parameters that the task should use during execution. Populate only the fields that match the task type. All other fields should be empty.

RunCommand

object

optional

The parameters for a RUN_COMMAND task type.

Automation

object

optional

The parameters for an AUTOMATION task type.

StepFunctions

object

optional

The parameters for a STEP_FUNCTIONS task type.

Lambda

object

optional

The parameters for a LAMBDA task type.

Priority

integer

optional

The new task priority to specify. The lower the number, the higher the priority. Tasks that have the same priority are scheduled in parallel.

>= 0

MaxConcurrency

string

optional

The new MaxConcurrency value you want to specify. MaxConcurrency is the number of targets that are allowed to run this task, in parallel.

>= 1 characters<= 7 characters

Match pattern:

^([1-9][0-9]*|[1-9][0-9]%|[1-9]%|100%)$

MaxErrors

string

optional

The new MaxErrors value to specify. MaxErrors is the maximum number of errors that are allowed before the task stops being scheduled.

>= 1 characters<= 7 characters

Match pattern:

^([1-9][0-9]*|[0]|[1-9][0-9]%|[0-9]%|100%)$

LoggingInfo

object

optional

The new logging location in Amazon S3 to specify.

Name

string

optional

The new task name to specify.

>= 3 characters<= 128 characters

Match pattern:

^[a-zA-Z0-9_\-.]{3,128}$

Description

string <password>

optional

The new task description to specify.

>= 1 characters<= 128 characters

Replace

boolean

optional

If True, then all fields that are required by the RegisterTaskWithMaintenanceWindow operation are also required for this API request. Optional fields that aren't specified are set to null.

CutoffBehavior

enum<string>

optional

Indicates whether tasks should continue to run after the cutoff time specified in the maintenance windows is reached.

CONTINUE_TASK: When the cutoff time is reached, any tasks that are running continue. The default value.
CANCEL_TASK:
- For Automation, Lambda, Step Functions tasks: When the cutoff time is reached, any task invocations that are already running continue, but no new task invocations are started.
- For Run Command tasks: When the cutoff time is reached, the system sends a CancelCommand operation that attempts to cancel the command associated with the task. However, there is no guarantee that the command will be terminated and the underlying process stopped.
The status for tasks that are not completed is TIMED_OUT.

Allowed values:

CONTINUE_TASKCANCEL_TASK

AlarmConfiguration

object

optional

The CloudWatch alarm you want to apply to your maintenance window task.

IgnorePollAlarmFailure

boolean

optional

When this value is true, your automation or command continues to run in cases where we can’t retrieve alarm status information from CloudWatch. In cases where we successfully retrieve an alarm status of OK or INSUFFICIENT_DATA, the automation or command continues to run, regardless of this value. Default is false.

Alarms

array[object (Alarm) {1}]

required

The name of the CloudWatch alarm specified in the configuration.

>= 1 items<= 1 items

Examples

Responses

🟢200Success

application/json

Body

WindowId

string

optional

The ID of the maintenance window that was updated.

>= 20 characters<= 20 characters

Match pattern:

^mw-[0-9a-f]{17}$

WindowTaskId

string

optional

The task ID of the maintenance window that was updated.

>= 36 characters<= 36 characters

Match pattern:

^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$

Targets

array [object]

optional

The updated target values.

>= 0 items<= 5 items

TaskArn

string

optional

The updated task ARN value.

>= 1 characters<= 1600 characters

ServiceRoleArn

string

optional

The Amazon Resource Name (ARN) of the Identity and Access Management (IAM) service role to use to publish Amazon Simple Notification Service (Amazon SNS) notifications for maintenance window Run Command tasks.

TaskParameters

object

optional

The updated parameter values.

TaskInvocationParameters

object

optional

The updated parameter values.

RunCommand

object

optional

The parameters for a RUN_COMMAND task type.

Automation

object

optional

The parameters for an AUTOMATION task type.

StepFunctions

object

optional

The parameters for a STEP_FUNCTIONS task type.

Lambda

object

optional

The parameters for a LAMBDA task type.

Priority

integer

optional

The updated priority value.

>= 0

MaxConcurrency

string

optional

The updated MaxConcurrency value.

>= 1 characters<= 7 characters

Match pattern:

^([1-9][0-9]*|[1-9][0-9]%|[1-9]%|100%)$

MaxErrors

string

optional

The updated MaxErrors value.

>= 1 characters<= 7 characters

Match pattern:

^([1-9][0-9]*|[0]|[1-9][0-9]%|[0-9]%|100%)$

LoggingInfo

object

optional

The updated logging information in Amazon S3.

Name

string

optional

The updated task name.

>= 3 characters<= 128 characters

Match pattern:

^[a-zA-Z0-9_\-.]{3,128}$

Description

string <password>

optional

The updated task description.

>= 1 characters<= 128 characters

CutoffBehavior

enum<string>

optional

The specification for whether tasks should continue to run after the cutoff time specified in the maintenance windows is reached.

Allowed values:

CONTINUE_TASKCANCEL_TASK

AlarmConfiguration

object

optional

The details for the CloudWatch alarm you applied to your maintenance window task.

IgnorePollAlarmFailure

boolean

optional

Alarms

array[object (Alarm) {1}]

required

The name of the CloudWatch alarm specified in the configuration.

>= 1 items<= 1 items

🟠480DoesNotExistException

🟠481InternalServerError