Create a software services instance

You can use this operation to create a software services instance in the registry.

HTTP method and URI path

POST /zosmf/provisioning/rest/<version>/scr

In this request, the URI path variable <version> identifies the version of the z/OSMF software services instance service. The following value is valid: 1.0.

Query parameters

None.

Description

This operation creates a software services instance in the registry, based on the properties that are specified in the request body (a JSON object). For the properties that you can specify, see Request content.

On successful completion, HTTP status code 201 (Created) is returned, indicating that the request resulted in the creation of a new software services instance. The URI path for the software object is provided in the Location response header and a response body is provided, as described in Response content.

Request content

The request content is expected to contain a JSON object. Table 1 lists the fields in the JSON object.

Table 1. Request content for the create software services instance request
Field name	Type	Required or optional	Description
type	String	Required	Type of the software. Up to 8 characters.
registry-type	String	Required	The type of software registry object: catalog or general. An object with registry-type catalog is created from a software services template in the software services catalog. When the registry type is catalog, a catalog object ID and catalog name are also required.
state	String	Required	The current state of the software: being-initialized being-provisioned provisioned being-deprovisioned deprovisioned provisioning-failed deprovisioning-failed
catalog-object-id	String	Required when registry-type is catalog	The identifier of the software services template to be used to create the software services instance.
catalog-object-name	String	Required when registry-type is catalog	The name of the software services template to be used to create the software services instance.
external-name	String	Optional	The external name to identify the software registry object. If the external name is not provided then it is set from object-name in the response body. Up to 34 characters.
system-nickname	String	Required when registry-type is catalog	The name of the system entry in the system entry table of the software.
system	String	Optional	System on which the software is provisioned. Up to 8 characters.
sysplex	String	Optional	Sysplex on which the software is provisioned. Up to 8 characters.
vendor	String	Optional	Vendor of the software. Up to 24 characters.
version	String	Optional	Version of the software. Up to 24 characters.
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 8 characters.
provider	String	Optional	The user ID that identifies the provider of the software, . Up to 8 characters. This is the owner of the software catalog object.
quality-attributes	String	Optional	The quality attributes associated with the software. Up to 16 characters.
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. See Table 2.
variables	Variable[]	Optional	The variables for the software. See Table 3.
user-data-id	String	Optional	The user data ID.
user-data	String	Optional	The user data.
domain-id	String	See description.	The domain ID. This field is not valid when the value for registry-type is general. It is required when the value for registry-type is catalog.
tenant-id	String	See description.	The tenant ID. This field is not valid when the value for registry-type is general. It is required when the value for registry-type is catalog.
domain-name	String	See description.	The name of the domain. This field is not valid when the value for registry-type is general. It is required when the value for registry-type is catalog.
tenant-name	String	See description.	The name of the tenant. This field is not valid when the value for registry-type is general. It is required when the value for registry-type is catalog.
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	The type of the action. The value must be one of the following: command workflow instructions
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.
instructions	String	For instruction type actions, the instructions.
prompt-variables	PromptVariable[]	For workflow type actions, if provided, the prompt variables, which are the variables that will have their values prompted for at create time. See Table 4.
at-create-variables	String[]	For workflow type actions, if provided, the names of the at create variables, which are the only variables 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.

For more information, see Authorization requirements.

HTTP status codes

On successful completion, HTTP status code 201 (Created) is returned and the response body is provided, as described in Response content.

Otherwise, the following HTTP status codes are returned for the indicated errors. The response body is a standard error response body that provides the reason code that is indicated and associated error message.

Table 5. HTTP error response codes for a create software services instance request
HTTP error status code	Description
`HTTP 400 Bad request`	The request contained incorrect parameters.
`HTTP 401 Unauthorized`	The requester user ID is not authorized for this request.

Response content

On successful completion, the service returns the following:

URI path of the created software services instance in the Location response header.
Response body, which contains a JSON object with details about the software services instance. Table 6 lists the fields in the JSON object.

Table 6. Response from a create software services instance request
Field	Type	Description
`object-id`	String	The object ID of the newly created object. The object ID is to be used on further requests to the object.
`object-uri`	String	The object URI of the newly created object.
`object-name`	String	The object name of the newly created object.

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

Table 7. 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 Figure 1, a request is submitted to create a software services instance on the system SY1.

Figure 1. Sample request to create a software services instance

{
 "type":"DB2",
 "external-name":"DB2B",
 "vendor":"IBM",
 "version":"V5R10",
 "description":"DB2 for test1",
 "registry-type":"catalog",
 "catalog-object-id":"9f7c659e-38f5-4585-b9f9-9cd448bf9cc3", 
 "catalog-object-name":"DB2template1",
 "workflow-key":"02e1ec78-e0db-482b-8013-3d435b52e2e3",
 "workflow-clean-after-provision":"true",
 "system-nickname":"SYSTEM1",
 "system":"SY1",
 "sysplex":"PLEX1",
 "state":"being-provisioned",
 "owner":"ZOSMFAD",
 "provider":"ZOSMFAD",
 "quality-attributes":"123456789ABCDEF0",
 "user-data":"my data",
 "user-data-id":"udid1",
 "domain-id":"izu$0",
 "tenant-id":"izu$002",
 "domain-name":"default",
 "tenant-name":"default",
 "ssin":"SSIN1",
 "variables":
     [
     {
         "name":"IACTION_NAME",
         "value":"Instructions1",
         "visibility":"public"
     },
     {
         "name":"COMMAND1",
         "value":"d a,l",
         "visibility":"public"
     },
     {
         "name":"C_DETECT_TIME",
         "value":"25",
         "visibility":"public"
     },
     {
         "name":"C_SOL_K",
         "value":"VLF",
         "visibility":"public"
     },
     {
         "name":"C_UNSOL_K",
         "value":"CSV",
         "visibility":"public"
     }
     ],
 "actions":
     [
     {    
         "name":"Instructions1",
         "type":"instructions",
         "is-deprovision":"false",
         "instructions":"These are the instructions for the ${IACTION_NAME} action."
     },
     {
         "name":"command1",
         "type":"command",
         "is-deprovision":"false",
         "command":"${COMMAND1}",
         "command-detect-time":"${C_DETECT_TIME}",
         "command-run-as-user":"IBMUSER",
         "command-sol-key":"${C_SOL_K}"
         ,"command-unsol-key":"${C_UNSOL_K}"
     },
     {
         "name":"deprovision",
         "type":"instructions",
         "is-deprovision":"true",
         "instructions":"Do the deprovision manually."
     }
     ]
 }

The response is shown below.

{
"object-name": "DB2_1",
"object-id": "c7156cbf-e1ce-4f05-b7c7-96d73dfb94f9",
"object-uri": "/zosmf/provisioning/rest/1.0/scr/c7156cbf-e1ce-4f05-b7c7-96d73dfb94f9"
}