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

Details

Request Body Parameters

"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>"
                                        }]
                                  }]
                           }]
                      }]
                }]
          }]

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:

Response

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

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:

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