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

Service Request API  has the following features:

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

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

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 an user action, requestReference would refer 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 they are 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 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.
inputProperty[]	For user action, this parameter contains a list of properties that are require inputs. 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: For detailed information about inputProperty[], see the section Input 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 value is not present in the availableList, then an error is reported.

Input Properties

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

The following table describes the fields that can be used in the input 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 mandatory or if it is associated with a dynamic script, then an error is reported if the property is missing.
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 inputProperty[]) 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 is 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 can encounter are:

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

  If there is an error in the inputProperty[] 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: