Sample use cases

This section has sample use cases for CSA APIs.

List service offerings

Consumers can get a list of service offerings published on CSA using the offerings REST API.

HTTP method POST
REST URL https://<CSAFQDN>:<port>/csa/api/mpp/
mpp-offering/filter
Payload {"approval":"ALL"}
Headers X-Auth-Token: <token>
Accept: application/json
Content-type: application/json
Response

Returns the list of offerings

For more information on payload options, see the documentation available at https://<host>:<port>/csa/apidocs.jsp.

Sample response:

"id": "9028525b4a7aa888014a7ae4d1ad0063",
"catalogId": "90d9650a36988e5d0136988f03ab000f",
"catalogName": "Global Shared Catalog",
"displayName": "Rest Demo",
"offeringVersion": "1",
"category": {
"displayName": "Application Services",
"name": "APPLICATION SERVICES"
},

Service offering details

This REST API provide details on customer options configured during service design. These options have to be included during order of a subscription. Check Service request payloads in CSA 4.x to parse the option model details.

HTTP method GET
REST API https://<CSAFQDN>:<port>/csa/api/mpp/mpp-offering/
<serviceofferingid>?catalogId=<catalogid>&category=<category.name>
REST URL https://<CSAFQDN>:<port>/csa/api/mpp/mpp-offering/
9028525b4a7aa888014a7ae4d1ad0063?catalogId=90d9650a36988e5d0136988f03ab000f&category=APPLICATION_SERVICES
Response See sample

Sample response:

{
"id": "402894a3481c3e2f0148db2d3c540a4f",
"name": "REST_Example_ab2647eb-f140-4516-989b-3c3e45c09f16", "displayName": "REST Example",
"catalogId": "90d9650a3698e5d0136988f03ab000f",
"category": {
 "displayName": "Application Servers",
 "name": "APPLICATION SERVERS" 
},
"image": "csa/images/library/Service_Design.png",
"approvalRequired": false,
"publishedDate": "2014-10-04T12:41:54.003Z",
"initPrice": {
 "currency": "USD",
 "price": 50
},
"recurringPrice": {
 "currency": "USD",
 "price": 10,
 "basedOn": "Monthly"
},
"fields": [
 {
  "id": "field_402894a3481c3e2f0148db2d3cdf0a56",
  "displayName": "2 CPU",
  "name": "EC9B910A_82A3_B51B_744B_DB26DCD23898",
  "description": "2 CPU",
  "visible": true,
  "disabled": false,
  "hidden": false,
  "value": true,

Mapping of subscriber options to its field ID and names:

Some more details on selected option:

"fields": [
 { 
   "id": "field_9028525b4a7aa888014a7ae4d1bc006a",
   "displayName": "Number of CPUs",
   "name": "EC9B910A_82A3_B51B_744B_DB26DCD23898",
   "description": "",
   "visible": true,
   "disabled": false,
   "hidden": false,
   "value": true,
   "initPrice": {
      "currency": "USD",
	  "price": 1
	},
   "recurringPrice": {
      "currency": "USD",
	  "price": 0,
	  "basedOn": "MONTH"
	},
   "required": false,
   "encrypted": false,
   "confidential": false 
};

Details on property associated with each option:

{
   "id": "field_9028525b4a7aa888014a7ae4d1bc006e",
   "displayName": "CPUs",
   "name": "CPU",
   "description": "",
   "visible": true,
   "disabled": false,
   "hidden": false,
   "value": 0,
   "initPrice": {
      "currency": null,
	  "price": null
	},
   "recurringPrice": {
      "currency": null,
	  "price": null,
	  "basedOn": null
	},
   "maxValue": 2147483647,
   "minValue": -2147483648,
   "required": true,
   "encrypted": false,
   "confidential": false
}, 

Create subscription

Order request is a HTTP POST operation. The service request that needs to be submitted to CSA has two parts bundled as XML structure. First part is on subscription information and second is about customer options. Refer Service request payloads in CSA 4.x to check sample payloads to generate service request with or without option model.

HTTP method POST
HTTP header header Content-Type: multipart/form-data; boundary=Abcdefgh
  Accept: application/json
  X-Auth-Token: Your token value from Get token Call
REST URL

https:// <CSAFQDN>:<port>/csa/api/mpp/mpp-request/
9028525b4a7aa888014a7ae4d1ad0063?catalogId=90d9650a36988e5d0136988f03ab000f

Payload
--Abcdefgh
Content-Disposition: form-data; name="requestForm"
{
"categoryName":"APPLICATION_SERVICES",
"subscriptionName":"sampleRequest", "subscriptionDescription": "This is a sample request",
"startDate":"2015-01-24T05:32:17.000Z",
"endDate":"2016-01-23T05:32:17.000Z", "fields":{
"field_9028525b4a7aa888014a7ae4d1bc006a":true,
"field_9028525b4a7aa888014a7ae4d1bc006e":2,
"field_9028525b4a7aa888014a7ae4d1cc0071":true,
"field_9028525b4a7aa888014a7ae4d1cc0074":2048}, "pricing": {},
"action":"ORDER"
}
--Abcdefgh--
Response
{
"id": "402894a34a0397f7014a287cd96f0770"
}

Note Content-type header is a multipart formdata and requires a boundary parameter to identify form data. In this case boundary is set to Abcdefgh.

Payload should start with the boundary value set in the header prepending “--“to the value. Payload start with

-- Abcdefgh

Payload should end with the boundary value in the header prepending “--“and ending with “--“. Payload ends with

--Abcdefgh--

Get MPP Request Details

URI csa/api/mpp/mpp-request/<requestid>?catalogId=<catalogid>

Use Catalog ID - 90d9650a36988e5d0136988f03ab000f and Request ID - 8a828bbe5ac68998015ac68f28ac000a

Method GET
Parameters

"requestState":

"PENDING", "REJECTED", "APPROVED", "COMPLETED"

"PENDING" : Implies pending for approval

"REJECTED" : Approval request is rejected.

"APPROVED" : This status is returned from the time the approval is done and subscription is being realized (executing all the flows in the Reserving/Deploying phase )

The request will remain in this state if the subscription has been paused.

"COMPLETED": Once the subscription has completed the processing (both success or failure) the state is moved to COMPLETED

"status": null , "SUCCESS", "FAILURE"

The status remains as null till the state is moved to COMPLETED. The status of the completion could be success or failure.

Returns 200 - Ok, object returned
401 - Not authorized
404 - Not found
500 - Server exception

Sample response:

{
 "id": "8a828bbe5ac68998015ac68f28ac000a",
 "displayName": "Base2 (1.0.0)",
 "description": null,
 "requestState": "APPROVED",
 "status": null,
 "startDate": 1489689005000,
 "createdOn": 1489389955070,
 "updatedOn": 1489389957723,
 "requestedAction": "ORDER",
 "pending": false,
 "inProgress": true,
 "defaultAction": true,
 "reorderable": true,
 "resubmitable": false,
 "externalPricing": false,
 "service": {
  "id": "2ec652f009d84698b8edac0bcc53a7d1",
  "displayName": "Sample Subscription For Request Details",
  "offeringVersion": "1.0.0",
  "iconUrl": "csa/images/library/IT_infrastructure.png",
  "description": "",
  "approvers": [],
  "hideInitialPrice": false,
  "hideRecurringPrice": false,
  "hideInitialPriceAppr": false,
  "hideRecurringPriceAppr": false,
  "approvalRequired": false
 },
 "requestedBy": {
  "displayName": "consumer"
 },
 "category": {
  "displayName": "Accessory",
  "name": "ACCESSORY"
 },
 "baseInitPrice": {
  "price": 0,
  "currency": "USD"
 },
 "baseRecurringPrice": {
  "price": 0,
  "currency": "USD",
  "basedOn": "YEAR"
 },
 "totalInitPrice": {
  "price": 0,
  "currency": "USD"
 },
 "totalRecurringPrice": {
  "price": 0,
  "currency": "USD",
  "basedOn": "YEAR"
 },
 "fields": [
  {
   "id": "field_8a828bbe5ac68998015ac68f29600015",
   "displayName": "Option 1",
   "name": "d623bc17_539c_9274_e1f1_2d6efb30a7e1",
   "description": "",
   "visible": true,
   "disabled": false,
   "hidden": false,
   "value": true,
   "initPrice": {
   "currency": "USD",
   "price": 0
  },
  "recurringPrice": {
   "currency": "USD",
   "price": 0,
   "basedOn": "YEAR"
  },
  "required": false,
  "encrypted": false,
  "confidential": false,
  "multiplied": false,
  "multiplier": false
  }
 ],
 "layout": [
  {
   "name": "field_e2ce145c_1ed2_083c_11c7_d676cf04cd1a",
   "displayName": "Option Set 1",
   "description": "",
   "type": "FieldSetLayout",
   "displayClass": "option-container",
   "image": "/csa/images/library/default.png",
   "displayType": "option-container",
   "layout": [
    {
     "fieldId": "field_8a828bbe5ac68998015ac68f29600015",
     "type": "FieldLayout",
     "displayType": "RADIO",
     "group": "field_e2ce145c_1ed2_083c_11c7_d676cf04cd1a_group",
     "selected": true,
     "imageUrl": "",
     "name": null
    }
   ]
  }
 ],
 "subscription": {
  "id": "8a828bbe5ac68998015ac68f3b5c004e",
  "displayName": "Base2 (1.0.0)",
  "description": ""
 }
}

Subscription list

HTTP method POST
REST URL https://<CSAFQDN>:<port>/csa/api/mpp/mpp-subscription/filter
Payload {
"status":null,
"category":null,
"name":null
"healthStatus":null
}
Response

The highlighted ID is the subscription ID - ff8080814b15cb4b014b1a70cdc0012a

"members": [
  {
     "@self": "/csa/api/mpp/mpp-subscription/ff8080814b15cb4b014b1a70cdc0012a",
     "@type": "urn:x-hp:2012:software:cloud:data_model:service-subscription",
     "name": "sampleRequest",
     "ext": {
        "csa_name_key": "sampleRequest"
     },
     "id": "ff8080814615cb4b014b1a70cdc0012a",
     "owner": "consumer",
     "image": "csa/images/library/Service_Design.png",
     "status": "ACTIVE",
     "catalogId": "90d9650a36988e5d0136988f03ab000f",
     "serviceId": "9028525b4a7aa888014a7ae4d1ad0063",
     "serviceImage": "/csa/images/library/Service_Design.png",
     "serviceName": "Rest Demo",
     "cancelable": true,
     "transferable": false,
     "modifiable": false,
     "modifiableOptions": false,
     "reorderable": false,
     "deletable": false,

Subscription details

Subscription details REST call is issued to fetch Base price, Recurring price, Total price and Service Instance Id. Service Instance is retrieved to fetch components that make up the service like server, application, properties etc.

Subscription details can be used to trace back order request and offering details.

HTTP method GET
REST API https://<CSAFQDN>:<port>/csa/api/mpp/
mpp-subscription/<subscriptionid>
REST URL https://<CSAFQDN>:<port>/csa/api/mpp/
mpp-subscription/ff8080814b15cb4b014b1a70cdc0012a
Response

Following parameters will be useful for other REST calls

Catalog Id: 90d9650a36988e5d0136988f03ab000f

Instance Id: ff8080814b15cb4b014b1a70cf77014e

"members": [
  {
     "@self": "/csa/api/mpp/mpp-subscription/ff8080814b15cb4b014b1a70cdc0012a",
     "@type": "urn:x-hp:2012:software:cloud:data_model:service-subscription",
     "name": "sampleRequest",
     "ext": {
        "csa_name_key": "sampleRequest"
     },
     "id": "ff8080814615cb4b014b1a70cdc0012a",
     "owner": "consumer",
     "image": "csa/images/library/Service_Design.png",
     "status": "ACTIVE",
     "catalogId": "90d9650a36988e5d0136988f03ab000f",
     "serviceId": "9028525b4a7aa888014a7ae4d1ad0063",
     "serviceImage": "/csa/images/library/Service_Design.png",
     "serviceName": "Rest Demo",
     "cancelable": true,
     "transferable": true,
     "modifiable": true,
     "modifiableOptions": true,
     "reorderable": true,
     "deletable": false,
   + "attachments": [...],
   + "subscriptionTerm": {...},
   + "initPrice": {...},
   + "recurringPrice": {...},
   + "category":{...},
     "lastUpdated": "2015-01-24T05:36:54.347Z",
     "requiredApproval":false,
     "requestId": "ff8080814b15cb4b014b1a70bbaa00e6",
     "showViewRequest": true,
     "ownerEmail": "",
     "instanceId": "ff8080814b15cb4b014b1a70cf77014e",
     "instanceState": "ACTIVE",
     "offeringVersion": "1",
   + "history": [...]
}

Service instance details

Instance details call is used to fetch service components, public actions and its properties defined on your subscription. To get Service instance ID use Subscription details REST call.

HTTP method GET
REST API https://<CSAFQDN>:<port>/csa/api/mpp/
mpp-instance/<serviceinstanceid>?catalogId=<catalogid>
REST URL

https://<CSAFQDN>:<port>/csa/api/mpp/mpp-instance/
ff8080814b15cb4b014b1a70cf77014e?catalogId=90d9650a36988e5d0136988f03ab000f

Response

Component Id: ff8080814b15cb4b014b1a70cf770171

Public Action: My_Action_October 13, 2014 5:18:11 AM UTC

Sample response:

"serviceInstance": {
    "name": "a925721a-c0c4-4d14-8cd6-32cad2783a62",
	"displayName": "RESTSample",
	"description": "",
	"image": "csa/images/library/Service_Design.png"
},
"components": [
   { 
       "id": "ff8080814b15cb4b014b1a70cf770171",
	"name": "SERVER__Sat Oct 04 18:03:08 IST 2014",
	"displayName": "Server",
	"description": "This is the default template for the selected component type, it contains the same settings as the base component type definition.",
	"image": "csa/images/categories/component_type/server.png",
	"status": "DEPLOYED",
     + "properties": [...],
     — "serviceAction": [
     	—{
         "id": "ff8080814b15cb4b014b1a70cf770172",
         "name": "My_Action_October 13, 2014 5:18:11 AM UTC",

Cancel subscription

HTTP method POST
HTTP header Content-Type: multipart/form-data; boundary=Abcdefgh
  Accept: application/json
REST API https://<CSAFQDN>:<port>/csa/api/mpp/
mpp-request/<requestid>?catalogId=<catalogid>
REST URL https://<CSAFQDN>:<port>/csa/api/mpp/mpp-request/
ff8080814b15cb4b014b1a70cdc0012a?catalogId=90d9650a36988e5d0136988f03ab000f
Payload

--Abcdefgh
Content-Disposition: form-data; name="requestForm"
{
"action": "CANCEL_SUBSCRIPTION"
}
--Abcdefgh--

Manage your Subscription

There are two cases where you can use REST call to manage your subscription:

  1. Request customer actions (public actions).
  2. Modify a subscription to update subscription attributes or options.

Request a public action

A public action “My_Action” is defined on the component. “My_Action” takes three inputs String, Integer and a Boolean. Request payload has to include all these inputs while requesting a public action call.

From Service Instance details, get component ID where public action has been defined and the name of the public action.

Component Id: ff8080814b15cb4b014b1a70cf770171

Public Action: My_Action_October 13, 2014 5:18:11 AM UTC

HTTP method POST
HTTP header

Content-Type: multipart/form-data; boundary=Abcdefgh

Accept: application/json

REST API https://<CSAFQDN>:<port>/csa/api/ mpp/
mpp-request/ <componentid>?catalogId=<catalogid>
REST URL https://<CSAFQDN>:<port>/csa/api/ mpp/mpp-request/
ff8080814b15cb4b014b1a70cf770171?catalogId=90d9650a36988e5d0136988f03ab000f
Payload

--Abcdefgh
Content-Disposition: form-data; name="requestForm"
{
"action":"My_Action_October 13, 2014 5:18:11 AM UTC",
"subscriptionId":"ff8080814b15cb4b014b1a70cdc0012a",
"fields":{
"booleanInput":false,"stringInput":"xxx","integerInput":2
}
}
--Abcdefgh--

Note If Public action is defined on a resource Subscription, then fetch resourceSubscription ID from Service Instance details call and issue an mpp request to CSA. The URI in such a case would be:

/api/ mpp/mpp-request/<resourceSubscriptionId>?catalogId=<catalogid>

Modify subscription

To modify a subscription, fetch the required option model details from the subscription details call, as shown in the following example:

HTTP method GET
REST API https://<CSAFQDN>:<port>/csa/api/
mpp/mpp-subscription/<subscriptionid>/modify
REST URL https://<CSAFQDN>:<port>/csa/api/mpp/
mpp-subscription/ff8080814b15cb4b014b1a70cdc0012a/modify

CPU options:

"id": "field_ff8080814b15cb4b014b1a70cdef0132",
"displayName": "Number of CPUs",
"name": "EC9B910A_82A3_B51B_744B_DB26DCD23898",
"description": "",
"visible": true,
"id": "field_ff8080814b15cb4b014b1a70cdef0133",
"displayName": "CPUs",
"name": "CPU",
"description": "",
"visible": true,
"disabled": false,
"hidden": false,
"value": 2, 

Memory options:

"id": "field_f8080814b15cb4b014b1a70cdef0138",
"displayName": "Memory (GB)",
"name": "C1988678_C6C2_A878_FEEE_DB29D1FF54DF",
"description": "",
"visible": true,
"id": "field_ff8080814b15cb4b014b1a70cdef012c",
"displayName": "Total Memory",
"name": "Memory",
"description": "",
"visible": true,
"disabled": false,
"hidden": false,
"value": 2048,

Issue a subscription modify request

HTTP method POST
HTTP header Content-Type: multipart/form-data; boundary=Abcdefgh
  Accept: application/json
  X-Auth-Token: Your token value from Get token Call
REST API https://<CSAFQDN>:<port>/csa/api/ mpp/
mpp-request/<subscriptionid>?catalogId=<catalogid>
REST URL https://<CSAFQDN>:<port>/csa/api/ mpp/mpp-request/
ff8080814b15cb4b014b1a70cdc0012a?catalogId=90d9650a36988e5d0136988f03ab000f
Payload

--Abcdefgh
Content-Disposition: form-data; name="requestForm"
{
"subscriptionName":"sampleRequest",
"subscriptionDescription":"Sample",
"fields":{
"field_ff8080814b15cb4b014b1a70cdef0132":true,
"field_ff8080814b15cb4b014b1a70cdef0133":4,
"field_ff8080814b15cb4b014b1a70cdef0138":true,
"field_ff8080814b15cb4b014b1a70cdef012c":4096
},
"action":"MODIFY_SUBSCRIPTION"
}
--Abcdefgh--

Download document attached to a CSA service

Documents are attached to Service offering before publishing an offer or to an order request before ordering a subscription. An active subscription will have reference links to these attachments which can be used to download the document.

Subscription details call will fetch the URL to download documents attached to an offering.

To download document use the following REST URL:

HTTP method GET
Content type application/octet-stream
REST API https://<CSAFQDN>:<port>/csa/api/mpp/mpp-subscription/
<subscriptionid>/attachment/<documentid>/file/<filename>
REST URL https://<CSAFQDN>:<port>/csa/api/mpp/mpp-subscription/ 9028525b4a7aa888014a7ae4d1ad0063/attachment/9028525b4a7aa888014a7aed9cac013a /file/offering.txt

In order to fetch documents attached to subscription request, get the request ID and catalog ID from the Subscription details call.

To fetch attachments URL, use request details call.

HTTP method GET
REST API https://<CSAFQDN>:<port>/csa/api/ mpp/
mpp-request/<requestId>?catalog=<catalogId>
REST URL https://<CSAFQDN>:<port>/csa/api/mpp/mpp-request/
402894a34a2e77ae014a2eec8a430020?catalogId=90d9650a36988e5d0136988f03ab000f

Sample response

HTTP method GET
Content type application/octet-stream
Accept application/json
REST API https://<CSAFQDN>:<port>/csa/api/mpp/
mpp-request/<requestid>/attachment/<attachmentid>/file/<filename>
REST URL https://<CSAFQDN>:<port>/csa/api/mpp/mpp-request/
402894a34a2e77ae014a2eec8a430020/attachment/402894a34a2e77ae014a2eec8d140064/file/ sam.xml

Service request payloads in CSA 4.x

To issue an order request to CSA, send a service request payload along with order request. Let us look at necessary parameters in the payload request that makes a service request. If your service design contains subscriber options (customer options) then these options are bundled under fields { } structure into the service request.

Sample payload without optionModel

{ "action":"ORDER", "categoryName":"REPLACE_ME_SERVICE_CATEGORY", "subscriptionName":"REPLACE_ME_SUBSCRIPTIONNAME", "startDate":"REPLACE_ME_ISO_DATE", "endDate":" REPLACE_ME_ISO_DATE", "fields":{ } }

For example: {"action":"ORDER", "categoryName":"APPLICATION_SERVERS", "subscriptionName":"sampleRequest", "startDate":"2014-12-03T05:04:49.000Z", "endDate":"2015-12-03T05:04:49.000Z", "fields":{ } }

Sample payload with optionModel

{ ""categoryName":"REPLACE_ME_SERVICE_CATEGORY", "subscriptionName":"REPLACE_ME_SUBSCRIPTIONNAME", "startDate":"REPLACE_ME_ISO_DATE", "endDate":" REPLACE_ME_ISO_DATE", "fields":{ "REPLACE_ME_OPTION_FIELD_ID":REPLACE_ME_VALUE_TRUE_OR_FALSE, "REPLACE_ME_OPTION_PROPERTY_FIELD_ID":REPLACE_ME_PROPERTY_VALUE }, "action":"ORDER" }

For example: { "categoryName":"APPLICATION_SERVICES", "subscriptionName":"sampleRequest", "startDate":"2015-01-24T05:32:17.000Z", "endDate":"2016-01-23T05:32:17.000Z", "fields":{ "field_9028525b4a7aa888014a7ae4d1bc006a":true, "field_9028525b4a7aa888014a7ae4d1bc006e":2, "field_9028525b4a7aa888014a7ae4d1cc0071":true, "field_9028525b4a7aa888014a7ae4d1cc0074":2048}, "action":"ORDER" }