Endpoints in the BMC Digital Workplace Catalog REST API

You can perform the following actions by using the supported API categories in the BMC Digital Workplace Catalog:

Using the Digital Workplace Catalog API Open link

Authentication

Within the Digital Workplace Catalog, users with the role permissions of asset manager and service catalog admin can see all services. The same users in external systems that link to Digital Workplace Catalog have the same access permissions.

To request an authentication token

POST /users/login

Parameters

Name	Required/Optional	Description	Type	Example	Notes
id	Required	BMC Digital Workplace Catalog user login account (with the organization domain).	String	hannah_admin@calbro.com	Locate this parameter in the request body. This parameter is not specified by default.
password	Required	Password.	String	<your_password>	Locate this parameter in the request body. This parameter is not specified by default.

Example request body

{
	"id": "<your_user>",
	"password": "<your_password>"
}

Response

Response	Value	Notes
HTTP code	200	Application returns an authentication token that is valid for about half an hour.

To retrieve a full category list

GET /categories

Parameters

Name	Required/Optional	Description	Type	Example	Notes
perPage	Optional	Page size.	Integer	20	This is a query parameter. Default for non-paginated search -1.
page	Optional	Page number.	Integer	1	This is a query parameter. Default 1.

Response

Response	Value	Notes
HTTP code	200	Returns a category list object array.
type	application/json	Not applicable.

Response properties

Name	Description	Type
pageSize	Pass through the request parameter.	Integer
page	Pass through the request parameter.	Integer
categories	Category object array.	Array

Example response body

{
  "pageSize": 5,
  "page": 1,
  "categories": [
    {
      "id": "1234",
      "guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVD",
      "name": "Accounts, Security, and IDs",
      "categoryGroupId": "1234",
      "parentId": null,
      "childCount": 5,
      "subCategories": null
    },
    {
      "id": "1234",
      "guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVE",
      "name": "User accounts and account access",
      "categoryGroupId": "1234",
      "parentId": "1234",
      "childCount": 0,
      "subCategories": null
    },
    {
      "id": "1234",
      "guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVF",
      "name": "System accounts",
      "categoryGroupId": "1234",
      "parentId": "1234",
      "childCount": 0,
      "subCategories": null
    },
    {
      "id": "1234",
      "guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVG",
      "name": "Access requests",
      "categoryGroupId": "1234",
      "parentId": "1234",
      "childCount": 0,
      "subCategories": null
    },
    {
      "id": "1234",
      "guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVH",
      "name": "IDs, badges, and facility access",
      "categoryGroupId": "1234",
      "parentId": "1234",
      "childCount": 0,
      "subCategories": null
    }
  ],
  "total": 123
}

To retrieve descendants of a given category

This API returns only categories that contain services that are entitled to the requesting user.

GET /categories/{categoryId}/categories

Parameters

Name	Required	Description	Type	Example	Notes
categoryId	Required	Category ID to retrieve.	String	1234	Locate this parameter in the request URL. This parameter is not specified by default.
depth	Optional	Depth of the category being retrieved.	Integer	2	This is a query parameter. Default 1. Allowed values: 1, 2, 3.
requestedfor	Optional	When a user is specified, the entitlement check is performed against the user. Otherwise, the entitlement check is performed against the current user.	String	"Mary"	This is a query parameter. This parameter is not specified by default.

Response

Response	Value	Notes
HTTP code	200	Returns a category array object. If the requested categoryId does not exist or does not contain descendants, then an empty array is returned.
type	application/json	Not applicable.

Response properties

Name	Description	Type	Notes
id	Category ID used by the application.	String	Not applicable.
guid	Unique ID used by the platform.	String	Not applicable.
name	Category name.	String	Not applicable.
categoryGroupId	Group to which the category belongs.	String	Currently, there is only one category group, referenced as "Type of service".
parentId	ID of the child's parent category.	String	If the parent ID is not available, null.
childCount	Number of direct descendant categories.	Integer	Not applicable.
subCategories	Null	String	Not applicable.

Example response body

[
  {
    "id": "1234",
    "guid": null,
    "name": "User accounts and account access",
    "categoryGroupId": "1234",
    "parentId": "1234",
    "childCount": 0,
    "subCategories": null
  },
  {
    "id": "1234",
    "guid": null,
    "name": "System accounts",
    "categoryGroupId": "1234",
    "parentId": "1234",
    "childCount": 0,
    "subCategories": null
  },
  {
    "id": "1234",
    "guid": null,
    "name": "Access requests",
    "categoryGroupId": "1234",
    "parentId": "1234",
    "childCount": 0,
    "subCategories": null
  },
  {
    "id": "1234",
    "guid": null,
    "name": "IDs, badges, and facility access",
    "categoryGroupId": "1234",
    "parentId": "1234",
    "childCount": 0,
    "subCategories": null
  },
  {
    "id": "1234",
    "guid": null,
    "name": "Remote access",
    "categoryGroupId": "1234",
    "parentId": "1234",
    "childCount": 0,
    "subCategories": null
  }
]

To retrieve category groups

GET /categories/groups

Parameters

None.

Response

Response	Value	Notes
HTTP code	200	Application returns the category array.
type	application/json	Not applicable.

Response properties

Name	Description	Type
id	Category group ID used by the application.	String
guid	Unique ID used by the platform.	String
name	Category group name.	String
description	Description of the category group.	String
systemId	System ID of the category group.	String
groupStatus	Status of of the category group.	String
childCount	Number of direct descendant categories.	Integer
categories	Null	String

Example response body

[
  {
    "id": "1234",
    "guid": "AGGADG1AANVNMAOBXYYOAAAASGWDVC",
    "name": "Type of Service",
    "description": "",
    "systemId": "type-of-service",
    "groupStatus": "ACTIVE",
    "childCount": 18,
    "categories": null
  }
]

To retrieve categories of a given category group

GET /categories/groups/{categoryGroupId}/categories

Parameters

Name	Required/Optional	Description	Type	Example	Notes
categoryGroupId	Required	Category group ID to retrieve.	String	1234	Locate this parameter in the request URL. This parameter is not specified by default.
depth	Optional	Depth of the category being retrieved.	Integer	2	This is a query parameter. Default 1. Allowed values: 1, 2, 3.
requestedfor	Optional	When a user is specified, the entitlement check is performed against the user. Otherwise, the entitlement check is performed against the current user.	String	"Mary"	This is a query parameter. This parameter is not specified by default.

Response

Response	Value	Notes
HTTP code	200	Successful response returns the array of category objects.
type	application/json	Not applicable.

Example response body

[
  {
    "id": "1234",
    "guid": null,
    "name": "User accounts and account access",
    "categoryGroupId": "1234",
    "parentId": "1234",
    "childCount": 0,
    "subCategories": null
  },
  {
    "id": "1234",
    "guid": null,
    "name": "System accounts",
    "categoryGroupId": "1234",
    "parentId": "1234",
    "childCount": 0,
    "subCategories": null
  },
  {
    "id": "1234",
    "guid": null,
    "name": "Access requests",
    "categoryGroupId": "1234",
    "parentId": "1234",
    "childCount": 0,
    "subCategories": null
  },
  {
    "id": "1234",
    "guid": null,
    "name": "IDs, badges, and facility access",
    "categoryGroupId": "1234",
    "parentId": "1234",
    "childCount": 0,
    "subCategories": null
  },
  {
    "id": "1234",
    "guid": null,
    "name": "Remote access",
    "categoryGroupId": "1234",
    "parentId": "1234",
    "childCount": 0,
    "subCategories": null
  }
]

Services

To retrieve details of a single service item

GET /services/{serviceId}

Parameters

Name	Required/Optional	Description	Type	Example	Notes
serviceId	Required	Not applicable.	String	1234	Locate this parameter in the request URL.
requestedfor	Optional	When a user is specified, the entitlement check is performed against the user. Otherwise, the entitlement check is performed against the current user.	String	"Mary"	This is a query parameter.

Response

Response	Value	Notes
HTTP code	200	Successful response returns the array of service details.
type	application/json	Not applicable.

Example response body

{
  "serviceType": "Desktop",
  "templateType": "SERVICE",
  "id": "1234",
  "name": "Adobe Illustrator",
  "description": "<p>Although during its first decade Adobe developed Illustrator primarily for Macintosh, it .....",
  "iconUrl": "/mp/media/.........0IjoicG5nIn1dXQ/file.png?sha=d706a107dc3d5cc6",
  "rating": 0.8,
  "modifiedDate": "2016-01-27T13:46:17.000+0000",
  "createdDate": "2016-01-27T13:38:50.000+0000",
  "ratingCount": 2,
  "supplier": {
    "id": "1234",
    "name": "Coke Services"
  },
  "categories": [
    {
      "id": "1234",
      "name": "Computer software",
      "categoryGroupId": "1234",
      "parentId": null,
      "childCount": 0,
      "subCategories": null
    },
    {
      "id": "1234",
      "name": "Graphics and design",
      "categoryGroupId": "1234",
      "parentId": "1234",
      "childCount": 0,
      "subCategories": null
    }
  ],
  "price": {
    "paymentType": "Once",
    "currency": "USD"
  },
  "onceCost": 120,
  "monthlyCost": 0,
  "yearlyCost": 0,
  "dynamicFields": [
    {
      "title": "Platform",
      "content": "Windows",
      "documents": []
    }
  ],
  "bundledServices": [],
  "entitled": true,
  "media": [
    {
      "type": "IMAGE",
      "url": "/mp/media/......../file.jpg?sha=0d05cab032f35a0b"
    },
    {
      "type": "IMAGE",
      "url": "/mp/media/......../file.jpg?sha=a70919ad560b236a"
    },
    {
      "type": "IMAGE",
      "url": "/mp/media/......../file.jpg?sha=adf9a4581061ead9"
    },
    {
      "type": "VIDEO",
      "url": "https://www.youtube.com/watch?v=d0LTzbksUiU"
    }
  ]
}

To search for services

Search criteria can be serviceIds, categoryId, or free text for a single service name or tag.

POST /services/search

However, multiple search criteria cannot be used in a same call. Wildcards are also not supported.

{
	"serviceIds": ["%123%","%456","789%"],
	"title": "apple"
}

Parameters

Name	Required/Optional	Description	Type	Example	Notes
perPage	Required	Page size.	Integer	20	This is a query parameter. Default for non-paginated search -1.
page	Required	Page number.	Integer	1	This is a query parameter. Default 1.
serviceIds	Required	ID of the service.	String	456	Locate this parameter in the request body.
categoryId	Required	ID of the category.	String	476	Locate this parameter in the request body.
title	Required	Title of the service.	String	"Apple"	Locate this parameter in the request body.
requestedfor	Required	When a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user.	String	"Mary"	This is a query parameter.

Response

Response	Value	Notes
HTTP code	200	Successful response receives an array of service objects.
type	application/json	Not applicable.

Example response body

{
  "services": [
    {
      "serviceType": "Cloud Software 1",
      "templateType": "SERVICE",
      "id": "1234",
      "name": "Office 365",
      "excerpt": "Get the most secure Office for your business",
      "iconUrl": "/mp/media/.../file.png?sha=b63f635628db7722",
      "rating": 0,
      "modifiedDate": "2015-12-03T18:43:35.000+0000",
      "createdDate": "2015-12-03T18:35:48.000+0000",
      "ratingCount": 0,
      "categories": [
        {
          "id": "1234",
          "name": "Collaboration tools",
          "categoryGroupId": "1234",
          "parentId": "1234",
          "childCount": 0,
          "subCategories": null
        },
        {
          "id": "1234",
          "name": "Productivity",
          "categoryGroupId": "1234",
          "parentId": "1234",
          "childCount": 0,
          "subCategories": null
        }
      ],
      "price": {
        "paymentType": "Recurring",
        "currency": "USD",
        "paymentSchedule": "Monthly"
      },
      "onceCost": 0,
      "monthlyCost": 8.25,
      "yearlyCost": 99,
      "provisioningTime": {
        "type": "ProvisioningTimeMetric",
        "value": 30,
        "timeUnit": "MIN"
      },
      "bundledServices": [],
      "entitled": true
    },
    {
      "serviceType": "Cloud Software 1",
      "templateType": "SERVICE",
      "id": "1234",
      "name": "Evernote Premium",
      "excerpt": "Evernote Premium unites writing, collection, discussion, and presentation in a single workspace. Instead of jumping between apps, keep focus in one place and your best work will follow.",
      "iconUrl": "/mp/media/..../file.png?sha=54ce415746fe5a0d",
      "rating": 0,
      "modifiedDate": "2015-12-04T01:43:03.000+0000",
      "createdDate": "2015-12-03T20:04:32.000+0000",
      "ratingCount": 0,
      "categories": [
        {
          "id": "1234",
          "name": "Computer software",
          "categoryGroupId": "1234",
          "parentId": null,
          "childCount": 0,
          "subCategories": null
        },
        {
          "id": "1234",
          "name": "Collaboration tools",
          "categoryGroupId": "1234",
          "parentId": "1234",
          "childCount": 0,
          "subCategories": null
        },
        {
          "id": "1234",
          "name": "Business",
          "categoryGroupId": "1234",
          "parentId": "1234",
          "childCount": 0,
          "subCategories": null
        }
      ],
      "price": {
        "paymentType": "Recurring",
        "currency": "USD",
        "paymentSchedule": "Yearly"
      },
      "onceCost": 0,
      "monthlyCost": 4.17,
      "yearlyCost": 49.99,
      "bundledServices": [],
      "entitled": true
    }
  ],
  "pageSize": 10
  "page": 1,
  "total": 2
}

To retrieve the full catalog view setting of ON or OFF

GET /services/fullcatalogview

Parameters

None

Response

Response	Value	Notes
HTTP code	200	Successful response returns a boolean value. True = ON, false = OFF.
type	application/json	Not applicable.

Example response body

true
false

Requests and questions

To initiate a request for a service by ID

POST /requests

Parameters

Name	Required/Optional	Description	Type	Example	Notes
serviceId	Required	ID of the service.	String	456	Locate this parameter in the request body.
excludedServiceIds	Required	A list of service revision IDs that will be excluded from the request bundle.	String	457	Locate this parameter in the request body.
requestForUserIds	Required	A list of user IDs for which the service is requested. Best practice: We recommend limiting the number of users per request to 20.	List of strings	["Mary", "Peter"]	Locate this parameter in the request body. By default, the current user is displayed.
dependencies	Required	Not applicable.	String	{serviceRequestId: string}	Locate this parameter in the request body.
quantity	Required	The service request quantity.	Integer	1	Locate this parameter in the request body. Default 1.
referenceRequestId	Optional	A prior request ID, if relevant.	String	5678	Locate this parameter in the request body.
myStuffItemId	Required	The My Stuff item ID.	String	9012	Locate this parameter in the request body.
onBehalfOfUserId	Required	The user ID on behalf of which the service request is being made.	String	9013	Locate this parameter in the request body.
questions	Optional	A list of common answers for relevant service request questions.	List of strings	Example request body Example { ID: string id Example: AGGADGG8ECDC0AP5X5L1P5A76XAIJO guid: string GUID Example: AGGADGG8ECDC0AP5X5L1P5A76XAIJO createDate: date-time When the record was created Example: 2018-09-27T18:37:18.000+0000 modifiedDate: date-time When the record was last modified Example: 2018-09-27T18:37:18.000+0000 rxId: string The request identifier in the server database (value is auto-generated) Example: 1 QuestionnaireId: string The questionnaire ID, provided the question belongs to a questionnaire (value is auto-generated). Example: 12803 Question Id: string* The question ID for the question being answered. Example: 97f8a510-4281-f441-888b-682eaf7c340e serviceRequestId: string The service request ID Example: 40597 displayValueOfAnswers: [ A list of answer display values corresponding to answers entries string ] answers: [ A list of acceptable answers for the question identified by questionId. ]* }	Locate this parameter in the request body. If you choose to include it in the response, you must provide at least the questionId and the associated answer. If your service request is for multiple users, they all must have provided the same answer. Multiple answers for a single question are typically only relevant for the multiple-choice questions string.

Example request body

{
  "serviceId" : "2417"
}

Example request body for the bulk order

{
  "serviceId" : "202",
  "requestForUserIds":["hannah_admin"],
  "questions":[{
  	"answers": ["Peter"],
  	"questionId": "7f5c973a-9faa-54a8-0806-f756c7cfb13e"
  }]
}

You can obtain the question ID in advance.

Response

Response	Value	Notes
HTTP code	200	Successful response returns the array of questions. Note: The structure of the questionnaire may vary between services, see Creating service questionnaires.
type	application/json	Not applicable.

Example response body

{
    "serviceId": "2417",
    "bundleRequestId": null,
    "requests": [
        {
            "requestId": "2920",
            "externalId": null,
            "dependencies": null,
            "questionnaire": null,
            "onStartChanges": {},
            "serviceId": "2417"
        }
    ],
    "requestErrors": []
}

To get a service request questionnaire

This step is optional if you request a bulk order.

GET /requests/{id}/questionnaire

Parameters

Name	Required/Optional	Description	Type	Notes
id	Required	The service request ID of a new request.	String	Locate this parameter in the request URL.
prefillRequestIds	Optional	A list of completed service request IDs to search for saved answers while re-requesting a service.	String	This a query parameter.

Response

Response	Value
HTTP code	200
type	application/json

Example response body

{
    "questionnaire": {
        "id": "1234",
        "guid": null,
        "createDate": null,
        "modifiedDate": null,
        "rxId": null,
        "summary": null,
        "workflowId": null,
        "questionnaireGroupId": null,
        "name": null,
        "bulkRequestedForUserLimit": 1,
        "pages": [
            {
                "id": "662576ab-d01d-ba5c-fffd-380e7aacbb00",
                "externalId": null,
                "perUser": false,
                "title": "",
                "pageItems": [
                    {
                        "type": "TextField",
                        "id": "7f5c973a-9faa-54a8-0806-f756c7cfb13e",
                        "externalId": null,
                        "perUser": false,
                        "visible": true,
                        "useDefaultLocale": false,
                        "label": "Your name",
                        "description": "<p>What is your name</p>",
                        "required": false,
                        "hidden": false,
                        "readOnly": false,
                        "answerSource": "SAVED",
                        "tags": [],
                        "defaultAnswer": "Peter",
                        "maxLength": null,
                        "confidential": false
                    }
                ]
            }
        ],
        "useDefaultLanguage": false
    }
}

To send an answer to a question

If you request a bulk order, this step is not used. Respond to a question ID from the list returned from the request. Each required question must be answered before the request can be submitted.

POST /services/{serviceId}/questionnaire/answers

Parameters

Name	Required	Description	Type	Notes
serviceId	Required	The ID of the service.	String	Locate this parameter in the request URL.
questionnaireId	Optional	The ID of the questionnaire.	String	Locate this parameter in the request body.
questionId	Optional	The ID of the question.	String	Locate this parameter in the request body.
answers	Optional	Answers to the questionnaire.	List of strings	Locate this parameter in the request body.
serviceRequestId	Optional	The ID of the service request.	String	Locate this parameter in the request body.

Example request body

{
  "questionnaireId": "1234",
  "questionId": "0",
  "answers": ["My First Name"],
  "serviceRequestId": "1234" 
}

Response

Response	Value	Notes
HTTP code	200	Successful response shows the changes of visibility by ID based on answers submitted.
type	application/json	Not applicable.

Returned values indicate how the answer being submitted impacts answers, options, and visibilities of other questions by ID.

Example response body

{
    1:[
		"answers": ["aa", "bb"],
		"options": [ {"dataValue": "1","displayValue": "ONE"},
					{"dataValue": "2","displayValue": "TWO"}
				],
		"visible": true
	]
}

To submit a bulk service request order

POST /orders

Parameters

Name	Required/Optional	Description	Type	Where
requests	Required	A list of request IDs representing the requests being placed.	List of strings	Locate this parameter in the request body.

Example request body

{
  "requests" : [{"id" : "2920"},{"id" : "2921"},{"id" : "2922"}]
}

Response

Response	Value	Notes
HTTP code	200	Successful response returns an empty content body.
type	application/json	Not applicable.

Example response body

{
    "id": "2916",
    "requestErrors": [],
    "requestDetails": [],
    "expectedDate": null
}

To retrieve all requests of a specific service by the current user

GET /services/{serviceId}/myrequests

Parameters

Name	Required/Optional	Description	Type	Notes	Example
serviceId	Required	ID of the service.	String	Locate this parameter in the request URL.	456
perPage	Optional	Page size.	Integer	This is a query parameter. Default 10.	20
page	Optional	Page number.	Integer	This is a query parameter. Default 1.	1

Response

Response	Value
HTTP code	200
type	application/json

Example response body

{
    "totalSize": 2,
    "data": [
        {
            "id": "1234",
            "serviceId": "1234",
            "status": "COMPLETED",
            "startTime": "2015-08-24T20:58:06.581+0000",
            "lastModifiedTime": "2015-08-24T20:58:06.606+0000",
			"completeTime": "2015-08-24T20:58:06.606+0000"
        },
        {
            "id": "1234",
            "serviceId": "1234",
            "status": "COMPLETED",
            "startTime": "2015-08-24T21:06:00.244+0000",
            "lastModifiedTime": "2015-08-24T21:06:00.245+0000",
            "completeTime": "2015-08-24T21:06:00.245+0000"
        }
    ]
}

To find requests

Use this endpoint to display a list of service requests on the user's request timeline. If a user is not specified, all requests are displayed.

GET /services/requests

Parameters

Name	Required/Optional	Description	Type	Notes	Example
requestedfor	Required	Filter requests that are requested for the specified user.	String	This is a query parameter.	"Mary"
requestedby	Required	Filter requests that are requested by the specified user.	String	This is a query parameter.	"Francie"
since	Required	Filter requests that are updated since the specified date.	String	This is a query parameter.	Tue, 08 Mar 2016 17:49:05 GMT
max	Required	Maximum amount of requests that will be retrieved.	Integer	This is a query parameter.	30

Response

Response	Value	Notes
HTTP code	200	Successful response returns a requests object array.
type	application/json	Not applicable.

Example response body

[
  {
    "id": "4402",
    "requestingUserId": "Allen",
    "requestForUserId": "Allen",
    "name": "New environment test",
    "description": "<p>test</p>",
    "excerpt": "test",
    "price": {
      "paymentType": "Free",
      "currency": "USD"
    },
    "status": {
      "id": "4402",
      "serviceId": "1234",
      "status": "ACTIVE",
      "startTime": "2016-03-08T20:32:12.000+0000",
      "lastModifiedTime": "2016-03-08T20:32:12.000+0000"
    },
    "quantity": 1,
    "logoUrl": "/mp/media/.../file.png?sha=c9eb1a96d6eea52f",
    "onceCost": 0,
    "monthlyCost": 0,
    "yearlyCost": 0
  },
  {
    "id": "4302",
    "requestingUserId": "Allen",
    "requestForUserId": "Allen",
    "name": "New environment test",
    "description": "<p>test</p>",
    "excerpt": "test",
    "price": {
      "paymentType": "Free",
      "currency": "USD"
    },
    "status": {
      "id": "1234",
      "serviceId": "1234",
      "status": "FAILED",
      "startTime": "2016-03-08T19:21:27.000+0000",
      "lastModifiedTime": "2016-03-08T19:21:27.000+0000"
    },
    "quantity": 1,
    "logoUrl": "/mp/media/.../file.png?sha=c9eb1a96d6eea52f",
    "onceCost": 0,
    "monthlyCost": 0,
    "yearlyCost": 0
  },
  {
    "id": "4301",
    "requestingUserId": "Allen",
    "requestForUserId": "Allen",
    "name": "SJ Bundle 1",
    "description": "<p>fhyfgjhgjghghghjgh<br/></p>",
    "excerpt": "yhytrtrtytryghhghhfhfh",
    "price": {
      "paymentType": "Once",
      "currency": "USD",
      "paymentSchedule": ""
    },
    "status": {
      "id": "4301",
      "serviceId": "1234",
      "status": "COMPLETED",
      "startTime": "2016-03-08T19:12:08.000+0000",
      "lastModifiedTime": "2016-03-08T19:12:08.000+0000"
    },
    "provisioningTime": {
      "type": "ProvisioningTimeMetric",
      "value": 10,
      "timeUnit": "DAY"
    },
    "quantity": 1,
    "logoUrl": "/mp/media/.../file.png?sha=3e8a0899fe7e867f",
    "onceCost": 200,
    "monthlyCost": 200,
    "yearlyCost": 2400
  }
]

To find requests by IDs

POST /services/requests/search

Parameters

Name	Required/Optional	Description	Type	Example	Notes
serviceId	Required	Service request ID numbers represented as a list of string values.	String	["4402", "4302", "4301"]	Locate this parameter in the request body.

Example request body

["4402", "4302", "4301"]

Response

Response	Value	Notes
HTTP code	200	Successful response returns the array of service request objects.
type	application/json	Not applicable.

Example response body

[
  {
    "id": "4402",
    "requestingUserId": "Allen",
    "requestForUserId": "Allen",
    "name": "New environment test",
    "description": "<p>test</p>",
    "excerpt": "test",
    "price": {
      "paymentType": "Free",
      "currency": "USD"
    },
    "status": {
      "id": "4402",
      "serviceId": "1234",
      "status": "ACTIVE",
      "startTime": "2016-03-08T20:32:12.000+0000",
      "lastModifiedTime": "2016-03-08T20:32:12.000+0000"
    },
    "quantity": 1,
    "logoUrl": "/mp/media/.../file.png?sha=c9eb1a96d6eea52f",
    "onceCost": 0,
    "monthlyCost": 0,
    "yearlyCost": 0
  },
  {
    "id": "4302",
    "requestingUserId": "Allen",
    "requestForUserId": "Allen",
    "name": "New environment test",
    "description": "<p>test</p>",
    "excerpt": "test",
    "price": {
      "paymentType": "Free",
      "currency": "USD"
    },
    "status": {
      "id": "4302",
      "serviceId": "1234",
      "status": "FAILED",
      "startTime": "2016-03-08T19:21:27.000+0000",
      "lastModifiedTime": "2016-03-08T19:21:27.000+0000"
    },
    "quantity": 1,
    "logoUrl": "/mp/media/.../file.png?sha=c9eb1a96d6eea52f",
    "onceCost": 0,
    "monthlyCost": 0,
    "yearlyCost": 0
  },
  {
    "id": "4301",
    "requestingUserId": "Allen",
    "requestForUserId": "Allen",
    "name": "SJ Bundle 1",
    "description": "<p>fhyfgjhgjghghghjgh<br/></p>",
    "excerpt": "yhytrtrtytryghhghhfhfh",
    "price": {
      "paymentType": "Once",
      "currency": "USD",
      "paymentSchedule": ""
    },
    "status": {
      "id": "4301",
      "serviceId": "1234",
      "status": "COMPLETED",
      "startTime": "2016-03-08T19:12:08.000+0000",
      "lastModifiedTime": "2016-03-08T19:12:08.000+0000"
    },
    "provisioningTime": {
      "type": "ProvisioningTimeMetric",
      "value": 10,
      "timeUnit": "DAY"
    },
    "quantity": 1,
    "logoUrl": "/mp/media/.../file.png?sha=3e8a0899fe7e867f",
    "onceCost": 200,
    "monthlyCost": 200,
    "yearlyCost": 2400
  }
]

To find a request by its ID

GET /services/requests/{requestId}

Parameters

Name	Required/Optional	Description	Type	Example	Notes
requestId	Required	ID of the request.	String	"4402"	Locate this parameter in the request URL.

Response

Response	Value	Notes
HTTP code	200	Successful response returns a service request object.
type	application/json	Not applicable.

Example response body

  {
    "id": "4402",
    "requestingUserId": "Allen",
    "requestForUserId": "Allen",
    "name": "New environment test",
    "description": "<p>test</p>",
    "excerpt": "test",
    "price": {
      "paymentType": "Free",
      "currency": "USD"
    },
    "status": {
      "id": "4402",
      "serviceId": "1234",
      "status": "ACTIVE",
      "startTime": "2016-03-08T20:32:12.000+0000",
      "lastModifiedTime": "2016-03-08T20:32:12.000+0000"
    },
    "quantity": 1,
    "logoUrl": "/mp/media/.../file.png?sha=c9eb1a96d6eea52f",
    "onceCost": 0,
    "monthlyCost": 0,
    "yearlyCost": 0
  }

To find all answers submitted for the given request

GET /services/requests/{requestId}/answers

Parameters

Name	Required/Optional	Description	Type	Notes
requestId	Required	ID of the request.	String	Locate this parameter in the request URL.

Response

Response	Value	Notes
HTTP code	200	Successful response returns a question object with completed answers.
type	application/json	Not applicable.

Example response body

[
  {
    "questionnaireId": "1",
    "questionId": "0",
    "questionType": "TextField",
    "label": "text field 1",
    "options": [
      {
        "dataValue": "text 1",
        "displayValue": "text 1"
      }
    ],
    "answers": [
      "text 1"
    ]
  },
  {
    "questionnaireId": "1",
    "questionId": "1",
    "questionType": "TextField",
    "label": "text field 2",
    "options": [
      {
        "dataValue": "text 2",
        "displayValue": "text 2"
      }
    ],
    "answers": [
      "text 2"
    ]
  }
]

Reviews

To retrieve all reviews

GET /reviews

Parameters

Name	Required/Optional	Description	Type	Example	Notes
serviceId	Optional	Retrieves reviews of a given service.	String	123	This is a query parameter.
userId	Optional	Retrieves reviews of a given user. The platform variable $USER$ can be sent as the userId of the current user.	String	"hannah"	This is a query parameter.
perPage	Optional	Page size.	Integer	20	This is a query parameter. Default -1 for non-paginated search.
page	Optional	Page number.	Integer	1	This is a query parameter. Default 1.
sortBy	Optional	Sorting criteria.	String	modifiedDate	This is a query parameter. Currently, only "modifiedDate" is available.
sortDirection	Optional	Sorting direction: either ascending or descending.	String	asc	This is a query parameter. Default asc.
requestedfor	Optional	When a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user.	String	"Mary"	This is a query parameter.

Response

Response	Value	Notes
HTTP code	200	Successful response returns the array of reviews objects.
type	application/json	Not applicable.

Example response body

{
  "reviews": [
    {
		"id": "1",
		"serviceId": "123",
		"userId": "2345",
		"title": "review title1",
		"content": "review content1",
        "modifiedDate": "2015-08-20T00:24:22.000+0000"
	},
	{
		"id": "2",
		"serviceId": "124",
		"userId": "2346",
		"title": "review title2",
		"content": "review content2",
        "modifiedDate": "2015-08-21T00:24:22.000+0000"
	}
  ],
  "pageSize": 10,
  "page": 1,
  "total": 2
}

To create a review for a given service

POST /reviews

Parameters

Name	Required/Optional	Description	Type	Example	Notes
serviceId	Required	ID of the service.	String	"123"	Locate this parameter in the request body.
title	Required	Title of the review.	String	"review title1"	Locate this parameter in the request body.
content	Required	Content of the review.	String	"review content1"	Locate this parameter in the request body.

Example request body

{
  "serviceId": "123",
  "title": "review title1",
  "content": "review content1"
}

Response

Response	Value	Notes
HTTP code	201	Successful response returns no content.

Example error handling

{
  "message": "Service of id {id} not found."
}

To retrieve a review by its ID

GET /reviews/{reviewId}

Parameters

Name	Required/Optional	Description	Example	Notes
reviewId	Required	ID of the review.	465	Locate this parameter in the request URL.
requestedfor	Optional	When a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user.	"Mary"	This is a query parameter.

Response

Response	Value	Notes
HTTP code	200	Successful response returns a review object.
type	application/json	Not applicable.

Example response body

{
  "id": "1",
  "serviceId": "123",
  "userId": "2345",
  "title": "review title1",
  "content": "review content1",
  "modifiedDate": "2015-08-20T00:24:22.000+0000"
}

Example error response

{
  "message": "ERROR (302): Entry does not exist in database"
}

To update a review

Reviews can be updated only if the review was originally entered under the current user's account. Admin users cannot update reviews submitted by other users.

PUT /reviews/{reviewId}

Parameters

Name	Required/Optional	Description	Type	Example	Notes
reviewId	Required	ID of the review to be updated.	String	675	Locate this parameter in the request URL.
title	Optional	Updated title.	String	"new title"	Locate this parameter in the request body. If both the title and the content parameters are empty, change will be ignored.
content	Optional	Updated content.	String	"new content"	Locate this parameter in the request body. If both the title and the content parameters are empty, change will be ignored.

Example request body

{    
  "title": "new title",
  "content": "new content"
}

Response

Response	Value	Notes
HTTP code	200	Successful response returns no content.

To delete a review

Reviews can be deleted only if the review was originally entered under the current user's account. Admin users cannot delete reviews submitted by other users.

DELETE /reviews/{reviewId}

Parameters

Name	Required/Optional	Description	Type	Notes
reviewId	Required	ID of the review to be deleted.	String	Locate this parameter in the request URL.

Response

Response	Value	Notes
HTTP code	200	Successful response returns no content.

Ratings

Rating is given as percentage (between 0 and 1).

To retrieve all ratings

GET /ratings

Parameters

Name	Required/Optional	Description	Type	Example	Notes
serviceId	Optional	Retrieves ratings of a given service.	String	123	Locate this parameter in the request body.
userId	Optional	Retrieves ratings from a given user. $USER$ can be used for current user.	String	20	Locate this parameter in the request body.
perPage	Optional	Page size.	Integer	20	Locate this parameter in the request body. Default -1 for non-paginated search..
page	Optional	Page number.	Integer	1	Locate this parameter in the request body. Default 1.
requestedfor	Optional	When a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user.	String	"Hannah"	This is a query parameter.

Response

Response	Value	Notes
HTTP code	200	Successful response returns an array of ratings objects.
type	application/json	Not applicable.

Example response body

{
  "ratings": [
    {
		"id": "1",
		"serviceId": "123",
		"userId": "2345",
		"rating": 0.8,
        "modifiedDate": "2015-08-20T00:24:22.000+0000"
	},
	{
		"id": "2",
		"serviceId": "124"
		"userId": "2345",
		"rating": 0.7,
        "modifiedDate": "2015-08-20T00:24:22.000+0000"
}
  ],
  "pageSize": 10,
  "page": 1,
  "total": 2
}

To create a rating for a service

POST /ratings

Parameters

Name	Required/Optional	Description	Type	Example	Where
serviceId	Required	ID of the service to be rated.	String	"123"	Locate this parameter in the request body.
rating	Required	Rating value submitted as a percentage (number between 0 and 1).	Float	0.8	Locate this parameter in the request body.

Example request body

{
  "serviceId": "123",
  "rating": 0.8
}

Response

Response	Value	Notes
HTTP code	201	Successful response returns no content.

To retrieve a rating by its ID

GET /ratings/{ratingId}

Parameters

Name	Required/Optional	Description	Type	Example	Notes
ratingId	Required	ID of the rating to retrieve.	String	456	Locate this parameter in the request URL.
requestedfor	Required	When a user is specified, the entitlement check is performed against the user. Otherwise, entitlement is checked on the current user.	String	"Mary"	This is query parameter.

Response

Response	Value	Notes
HTTP code	200	Successful response returns a rating object.
type	application/json	Not applicable.

Example response body

{
  "id": "1",
  "serviceId": "123",
  "userId": "2345",
  "rating": 0.8
}

To update a rating

Ratings can be updated only if the rating was originally entered under the current user's account. Admin users cannot update ratings submitted by other users.

PUT /ratings/{ratingId}

Parameters

Name	Required/Optional	Description	Type	Example	Notes
ratingId	Required	The ID of the rating to update.	String	"4321"	Locate this parameter in the request URL.
rating	Required	The rating value submitted as a percentage (number between 0 and 1).	Float	0.6	Locate this parameter in the request body.

Example request body

{
  "rating": 0.6
}

Response

Response	Value	Notes
HTTP code	200	Successful response returns no content.

Service migration

To export selected services

This endpoint packages service data and media files into a binary .zip archive that includes full catalog profiles, images, workflows, and questions.

POST /services/export

Parameters

Name	Required/Optional	Description	Type	Example	Notes
(array list)	Yes	List of the service IDs to be exported.	String	["1234", "1234"]	Locate this parameter in the request body.

Example request body

[
  "1234", "12345", ...
]

Response

A .zip file with the exported services.

To import a service .zip file

This endpoint extracts an uploaded binary .zip file and creates services with full catalog profiles, images, workflows, and questions.

POST /services/import

Parameters

Name Required/Optional Description Type Notes

(uploaded file)

Required

The service IDs to be imported.

Binary data (.zip file)

Locate this parameter in the request body.

The following form setting is required:

Content-Disposition: form-data; name="file"; filename="{file name}" Content-Type: application/x-zip-compressed

Response

Response	Value	Notes
HTTP code	200	Import is successful.

Error handling

Failed authentication requests return an error object with the following properties:

Name	Description	Type
message	Error message with the error code.	String
data	Error message description.	String
HTTP code	An object with the requested ID is not found.	404