Update a software services instance

You can use this operation to update fields in a software services instance.

HTTP method and URI path

PUT /zosmf/provisioning/rest/<version>/scr/<object-id>

In this request, the URI path variables are described, as follows:

<version> identifies the version of the provisioning service. The following value is valid: 1.0.
<object-id> identifies the software services instance to be updated.

Query parameters

None.

Description

This operation updates a software services instance.

Request content

The request content is expected to contain a JSON object containing the fields to be updated. Table 1 lists the fields that are valid.

Table 1. Request content for the update software services instance request
Field name	Type	Required or optional	Description
state	String	Optional	The current state of the software: being-initialized being-provisioned provisioned being-deprovisioned deprovisioned provisioning-failed deprovisioning-failed
external-name	String	Optional	The external name to identify the software registry object. Up to 25 characters.
system	String	Optional	System on which the software is provisioned, up to eight characters. Cannot be updated if the registry type is catalog for the software services instance.
sysplex	String	Optional	Sysplex on which the software is provisioned, up to eight characters Cannot be updated if the registry type is catalog for the software services instance.
vendor	String	Optional	Vendor of the software, up to 24 characters Cannot be updated if the registry type is catalog for the software services instance.
version	String	Optional	Version of the software, up to 24 characters Cannot be updated if the registry type is catalog for the software services instance.
description	String	Optional	Description for the software, up to 256 characters
owner	String	Optional	The user ID that identifies the owner of the software registry object, up to eight characters Cannot be updated if the registry type is catalog for the software services instance.
provider	String	Optional	The user ID that identifies the provider of the software, up to eight characters. This is the owner of the software catalog object. Cannot be updated if the registry type is catalog for the software services instance.
quality-attributes	String	Optional	The quality attributes associated with the software, up to 16 characters Cannot be updated if the registry type is catalog for the software services instance.
workflow-key	String	Optional	The workflow key associated with provisioning the software. This field is not valid when the value for registry-type is general.
workflow-clean-after-provisioned	String	Optional	The indication of whether the workflow instance used to provision this instance will be removed after the workflow is completed. Must be true or false. This field is not valid when the value for registry-type is general.
actions	Action[]	Optional	The actions for the software. Cannot be updated if the registry type is catalog for the software services instance. See Table 2.
variables	Variable[]	Optional	The variables for the software. Refer to Table 3. Cannot be updated if the registry type is catalog for the software services instance.
user-data-id	String	Optional	The user data ID.
user-data	String	Optional	The user data.
ssin	String	Optional	Software service instance name, used in generating names for software services instances. This field is not valid when the value for registry-type is general.

Table 2. Action structure
Field	Type	Description
name	String	The name of the action. If the name of the action is deprovision, the action is for deprovisioning the software. You can indicate that the action is for deprovisioning either by setting the is-deprovision field to `true` or by naming the action `deprovision`.
type	String must be one of: command workflow instructions	The type of the action.
is-deprovision	String	Indicates if the action deprovisions the software, as follows: If true, the action deprovisions the software. If false or not set, the action does not deprovision the software. This is overriden if the value of the name field is deprovision.
command	String	For command type actions, the command.
command-run-as-user	String	For command type actions, if provided, the user ID to be used when the command is run.This is not valid when the registry-type is general.
command-sol-key	String	For command type actions, if provided, the key to search for in the solicited messages command response.
command-unsol-key	String	For command type actions, if provided, the key to search for in the unsolicited messages.
command-detect-time	String	For command type actions, if provided, the time in seconds to detect for the command-unsol-key in the unsolicited messages. Also, the minimum time before a command response is checked for after the command is submitted for execution. If not provided, the default command-detect-time is 15 seconds when the command-unsol-key is specified or 10 seconds when the command-unsol-key is not specified.
workflow-definition-file	String	For workflow type actions, the workflow definition file.
workflow-variable-input-file	String	For workflow type actions, if provided, the workflow variable input file.
workflow-variables	Variable[]	For workflow type actions, if provided, the workflow variables. See Table 3.
instructions	String	For instruction type actions, the instructions.
prompt-variables	PromptVariable[]	Prompt variables, for workflow type actions, if any are provided. At create time, there are prompts for the values. See Table 4.
at-create-variables	String	Names of the at create variables, for workflow type actions, if any are provided. These are the only variables that are allowed on input variables for the do action operation.

Table 3. Variable structure
Field	Type
name	String
value	String
visibility	String. The value must be public or private.

Table 4. Prompt variable structure
Field	Type
name	String
value	String
abstract	String
description	String
error-message	String
label	String
max	String
min	String
milti-line	Boolean
must-be-choice	Boolean
choices	String List
places	String
regex	String
required	Boolean
type	String

Authorization requirements

The user’s z/OS user ID must have READ access to the following resource profile in the ZMFAPLA class: <SAF-prefix>.ZOSMF.PROVISIONING.SOFTWARE_SERVICES.

The user issuing the request must be the owner of the software services instance, or, for catalog registry type objects, a domain administrator of the software services instance, or, for general registry type objects, the landlord.

For more information, see Authorization requirements.

HTTP status codes

On successful completion, HTTP status code 204 Normal is returned.

Otherwise, the following HTTP status codes are returned for the indicated errors.

Table 5. HTTP error response codes for a update software services instance request
HTTP error status code	Description
`HTTP 400 Bad request`	Request contained incorrect parameters.
`HTTP 401 Unauthorized`	The requestor user ID is not authorized for this request.
`HTTP 404 Not found`	The specified software services instance instance was not found; the software services instance does not exist.
`HTTP 409`	The field cannot be updated for the registry type.

Response content

On successful completion, the response body contains nothing.

If a failure occurs, the response body contains a JSON object with a description of the error.

Table 6. Response from a request failure
Field	Type	Description
httpStatus	Integer	HTTP status code.
requestMethod	String	HTTP request method.
requestUri	String	HTTP request URI.
messageID	String	Message identifier for the error.
messageText	String	Message text describing the error.
additionalInfo	String	Additional information describing the error.
debug	String	Debug information about for the error.

Example HTTP interaction

In the following example, the PUT method is used to update a software services instance. The software services instance is uniquely identified by the software services instance key, which is represented by the following string value: 76963ea5-81a4-42d6-99d6-f3e19747cf61.

Figure 1. Sample request to update a software services instance property

PUT /zosmf/provisioning/rest/ 1.0/scr/ 76963ea5-81a4-42d6-99d6-f3e19747cf61

{       
             "state":"provisioned"
}