Service Request API

Service Request API is a simplified API for handling requests. You can use this API to:

• Submit a service request to create, modify or cancel a subscription

• Issue user actions on a subscription

• Resubmit a modify request that has failed

• Submit a request based on an existing request

Features

Following are the features of Service Request API:

  • To make the API portable across different environment, you can reference the Option Sets, Options and Properties by their display names instead of IDs.
  • Inputs are specified in the following hierarchy: Option Set -> Option -> Property.

    For child Option Sets nested within an Option Property, it is not necessary to maintain the hierarchy. The Option Sets are flat array regardless of whether the Option Set is at the top level or nested.

  • You can reference the Option Sets, Options and Properties by their display names.
  • Instead of passing all option properties to the request body, you can pass only the options that are selected and the properties that have values different form the default value.
  • The API has thorough error handling capabilities with clear error codes. A detailed message about the problem is provided so that the caller can take corrective action.
  • The API thoroughly validates the request body input and sends errors with details.
  • APIs are versioned according to the semantic versioning scheme.
  • If the value for the dynamic property is not sent as a part of the POST body, the first value from the dynamic script will be set for the Property.

Base URL

https://<csa url>:8444/csa/api/urest/v1.0.0/serviceRequest

Request Header and Authorization Parameters

Name Description
Content Type application/json
Authorization Base64 encoded username/password of the user who has the access to execute a REST call.
X-AUTH-TOKEN Authorization token obtained from IDM.

Details

URI csa/api/urest/v1.0.0/serviceRequest
Method POST
Returns

200 - Success

400 - Invalid inputs

403 - Unauthorized or invalid user

For more information, see the section Response and Error Handling.

Request Body Parameters

Name Description
action

You can perform the following actions:

  • ORDER
  • MODIFY_SUBSCRIPTION
  • CANCEL_SUBSCRIPTION
  • RESUBMIT_REQUEST
  • UPGRADE_SUBSCRIPTION
  • [ name of the PUBLIC ACTIONS ]
requestReference

You can use this API to create an order, modify a subscription or cancel a subscription.

Depending on the action, the requestReference either takes the name of the offering or the value of the subscriptionId/ componentId/ resourcesubscriptionId .

While creating an order, this parameter refers to the name of the offering based on which the order is created. While modifying or canceling a subscription, this parameter refers to the subscription ID.

For a user action, requestReference refers to the component ID or the resource subscription ID depending on where the actions are attached in the original design.

catalogName

This parameter specifies the internal name of the catalog in which the offering is published (in case of ORDER request).

Note This parameter does not refer to the display name.

catalogId This parameter specifies the ID of the catalog that is associated with the Service Offering. If there are multiple catalogs with the same name, then it is mandatory to specify this parameter. If the catalog name is unique in an environment, then this parameter is not mandatory.
basedOn Use this parameter if you are creating a service request based on an existing service request.
onBehalf Use this parameter to execute a request on behalf of the specified user. Only a Consumer Administrator can perform this operation.
onBehalfOrg Use this parameter to execute a request on behalf of the specified user (specified using the OnBehalf parameter) in a specified organization. If the user or organization does not exist then the parameter is created. Only a CSA administrator can perform this operation.
subscriptionName This parameter specifies the name of the subscription that this request will create or update.
subscriptionDescription This parameter specifies the description for the subscription that this request will create or update
startDate

This parameter specifies the start date of the subscription. It only accepts Coordinated Universal Time (UTC). You cannot modify the start date.

For example: 2017-06-20T11:37:19.000Z

endDate

This parameter specifies the end date of the subscription. It only accepts UTC. If an end date is not specified then it is considered to be a recurring subscription.

ownerGroup[]

This parameter specifies the canonical name of the group. If this parameter is not specified, then it is assumed that this subscription is owned individually and not available to a group.

Syntax: [{ "groupName":"<canonical name of the group>"}]

upgradeServiceOfferingName This parameter specifies the name of the offering to which the subscription is to be upgraded. Use this parameter only if the action performed is UPGRADE_SUBSCRIPTION.
actionProperty[]

For user action, this parameter contains a list of properties that require input.

If the action is ORDER or MODIFY_SUBSCRIPTION, this would be a single property of name 'OPTION_SETS' and the value would contain the flattened list of option sets. For ORDER or MODIFY_SUBSCRIPTION, you do not have to specify the entire Option Model. You can only provide the Option Sets that have changed values along with the Options and Properties.

You need not specify the hierarchy of the Option Set. In an Option Model, if there are child Option Sets, then you can specify them as a list.

You can either specify the display name or the internal name of the Option set, Option or Properties as shown in the following example:

For example:

"actionProperty": [{
"name": “OPTION_SETS”,
"values":[{
"value" : [{
"name": "<internal name of the optionSet> " ,
(or)
"displayName”: “<displayName of optionSet>",
"options": [{
"name" : "<internal name of the option>" ,
(or)
"displayName": “<displayName of option>",
"property": [{
"name" : "<internal name of the property>",
(or)
"displayName" : "<displayName of prop>",
"values": [{
"displayName":"<displayName of value>",
"value": "<internal value>"
}]
}]
}]
}]
}]
}]

For detailed information about actionProperty[], see the section Action Properties.

validateDynamicPropFromReq

This parameter is used to turn off the check of dynamic values against the available values returned by the dynamic scripts associated with a property.

By default this parameter is set to ‘true’. If the incoming request has properties that has dynamic scripts associated with it, the scripts is executed with appropriate parameters and the availableList is computed. The ‘displayName’ and ‘value’ of the Value is compared against this ‘availableList’.

If the dynamic property is not specified, the scripts will be executed with appropriate parameters and the first value will be set for the property.

This check can be turned off with this flag. However, no validation of the input value will be done. Both ‘displayName’ and ‘value’ for a value of the property needs to be provided.

Action Properties

The action properties for ORDER and MODIFY requests are organized in the following hierarchy:

The following table describes the fields that can be used in the action properties parameter:

Field Description
Option Set
name

This parameter denotes the internal name of the Option Set associated with the offering. This name does not change even when the offering is exported or imported to a different machine.

Note You can either specify the name or the display name.

displayName

This parameter denotes the display name of the Option Set.

Note You can either specify the name or the display name.

Caution In the Option Model, if the display name is not unique then an error is reported.

options[] This parameter is used to specify one or multiple options.
Option
name This parameter denotes the internal name of the Option. This name does not change even when the offering is exported or imported to a different machine.
displayName

This parameter denotes the display name of the Option.

Note You can either specify the name or the display name.

Caution In the Option Set, if the display name is not unique then an error is reported.

isSelected This parameter is used to specify if the option is selected or not. The default value is true.
property[] If there is a change in the value of properties that are associated with the Option, then use this parameter to list such properties. If you do not specify the property, then the default value associated in the offering is used. If the property is dynamic and is not specified, then the default value (first value returned by dynamic script ) is associated to the offering.
Property
name This parameter denotes the internal name of the Property.
displayName

This parameter denotes the display name of the Property.

Note You can either specify the name or the display name.

Caution In the Option, if the display name is not unique then an error is reported.

values[] This parameter is used to list the values associated with the Property.
Values
name This parameter denotes the internal value associated with the Value of the property.
displayName This parameter denotes the display name associated with the Value. This is used only when a static or dynamic list is associated with the Property. For a non-dynamic property, you need not specify the display name.

Response

If serviceRequest is created successfully, then the response message contains the URI of the newly created resource along with the following details:

Field Description
@uri The URI of the created service request
@type Service request
Name Name of the created service request
Description Description associated with the service request
Created Time (in UTC) when the resource was created

For example:

{
"@uri": "/mpp/mpp-request/8a828faf5cc47c75015cc95d61fd11e3",
"@type": "serviceRequest",
"name": "Sample Request for Demo ",
"description": "This is a sample request that is created for demoing the simplified API",
"created": "2017-06-17T06:35:59.357Z"
}

Error Handling

Every HTTP Error code that matches with 2XX will have the following fields:

Field Description
@uri The URI of the created service request
@type Service request
Name Name of the created service request
Description Description associated with the service request
Created Time (in UTC) when the resource was created
  • HTTP Status Code 400

    If one or more input parameters (other than actionProperty[]) are invalid, then a generic error code INVALID_DATA is returned with the following description: One or more inputs are not valid.

    The details of the each error encountered are provided within the nestedErrors array field.

    For example:

    {
    "errorCode" : "INVALID_DATA",
    "message" : "One or more inputs are not valid",
    "nestedErrors" : [{
    "errorCode" : "INVALID_CATALOG_NAME",
    "details" : "Unable to find the catalog with the name:’CPE Catalog’. Ensure that the ‘name’ (not the displayName) of the catalog is specified",
    "message" : "Catalog name is invalid"
    }, {
    "errorCode" : "INVALID_DATE",
    "details" : "Start Date specified: Sun Jun 11 17:07:19 IST 2017 is in the past. Please specify a current date or a date in the future",
    "message" : "Start date in the past"
    }, {
    "errorCode" : "INVALID_GROUP_OWNER",
    "details" : "User with id: 8a828faf5c53b3e2015c57abbddf0776 not part of the group: skfskdf",
    "message" : “Invalid owner group”
    } ]
    }

    Note The API consolidates as many errors as possible under nestedErrors before reporting the INVALID_DATA error.

    Some of the other errors that you might encounter are:

    • INVALID_ACTION_NAME
    • INVALID_ON_BEHALF
    • INVALID_CATALOG_NAME
    • INVALID_OFFERING
    • INVALID_PARAM
    • INVALID_DATE

    If there is an error in the actionProperty[] field, then errors are not consolidated, instead the first encountered exception is reported.

    For example:

    {
    "errorCode" : "INVALID_OPTION_MODEL",
    "message" : "The value for dynamic property 'AppOwner' not found in request.",
    "data" : "com.hp.ccue.mpp.dao.util.MPPException: com.hp.csa.exception.InvalidOptionModelException: The value for dynamic property 'AppOwner' not"
    }
    Error Code Error Description
    INVALID_OPTION_MODEL Error in processing the Option Sets The value provided for the name of Option Set or Option is invalid or incorrect.
    INVALID_PROPERTY Invalid Property or invalid Value for the Property A required property was not specified or the provided values do not comply with the constraints.
  • HTTP Status Code 403

    You may get one of the following errors:

    Error Code Error Description
    UNAUTHORIZED_USER Unauthorized user User cannot create subscription based on the offering
    INVALID_USER Invalid user Cannot find the user

For any other errors, INTERNAL_ERROR is reported with the message, details and data field along with additional information.

Examples

Example for creating a service request with OptionSet, Option, Property referenced with display Name:

Example for creating a service request with OptionSet/Option/Property referenced with internal name:

Example for creating a service request where the property takes in a dynamic value:

Example for modifying a subscription:

Example for canceling a subscription:

Example for upgrading a subscription:

Example for resubmitting a subscription in failed modification state:

Example for submitting a public action: