Endpoints in the BMC Helix Digital Workplace Catalog REST API

BMC Helix Digital Workplace Catalog API follows the REST architectural style. JSON is used for request and response bodies. The following headers are the most common for all requests:

default-bundle-scope—myit-sb
Content-Type—application/json
X-Requested-By—<any_value>

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

Authentication
- To request an authentication token
Categories
Services
Requests and questions
Reviews
Ratings
Error handling

Required license

DWP Advanced icon.png BMC Helix Digital Workplace Advanced

Authentication

Within BMC Helix 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 BMC Helix 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 Helix Digital Workplace Catalog user login account.	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.

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	Value	Notes
HTTP code	200	Returns a category list object array.
type	application/json	Not applicable.

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

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

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.

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

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

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	Value	Notes
HTTP code	200	Successful response returns the array of category objects.
type	application/json	Not applicable.

Services

To retrieve details of a single service item

GET /services/{serviceversionId}

Parameters

Name	Required/Optional	Description	Type	Example	Notes
serviceversionId	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": "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

This API returns only published services. Search criteria can be serviceversionIds, 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. Only one search criterion must be used in the request body. Wildcards are also not supported.

{
"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.
serviceversionIds	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
serviceversionId	Required	ID of the service.	String	456	Locate this parameter in the request body.
excludedServiceversionIds	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

{
"serviceversionId" : "2417"
}

Example request body for the bulk order

{
"serviceversionId" : "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. Important: The structure of the questionnaire may vary between services, see Creating-service-questionnaires.
type	application/json	Not applicable.

Example response body

{
   "serviceversionId": "2417",
   "bundleRequestId": null,
   "requests": [
        {
           "requestId": "2920",
           "externalId": null,
           "dependencies": null,
           "questionnaire": null,
           "onStartChanges": {},
           "serviceversionId": "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": "203",
 "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": "What is your name",
 "required": false,
 "hidden": false,
 "readOnly": false,
 "answerSource": "SAVED",
 "tags": [],
 "defaultAnswer": "Peter",
 "maxLength": null,
 "confidential": false
 }
 ]
 }
 ],
 "useDefaultLanguage": false
 }
}

To send an answer to a question

This step is optional if you request a bulk order. 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/{serviceversionId}/questionnaire/answers

Parameters

Name	Required	Description	Type	Notes
serviceversionId	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

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

To submit one or multiple service requests

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 submit a specific service request

POST /services/{serviceId}/requests/{requestId}/submissions

Parameters

Name	Where	Required	Description
serviceId	URL	Yes	ID of the service
requestId	URL	Yes	ID of the request

Response

Response	Value	Notes
HTTP code	200 or 201 Created	Successfully returns an empty content body
type	application/json	Not applicable

Error handling

Failed requests return an error object with the following properties.

Argument	Type	Description
message	string	Error message with error code

To create and submit a service request in a single API call

POST /orders/requests

Parameters

Name	Required/Optional	Description	Type	Where
title	Optional	The order title of the new service request. In BMC Helix Digital Workplace, this is displayed as the Order Description.	String	Locate this parameter in the request body.
collaboratorsEnabled	Optional	If this parameter is true, the new service request is automatically shared with the user's default group of collaborators. If this parameter is false, the new service request is not automatically shared. The default is false.	Boolean	Locate this parameter in the request body.
serviceRequests	Required	A list of service requests, using the properties described in the following table.	List	Locate this parameter in the request body.

serviceRequests properties

Name	Required/Optional	Description	Type
serviceversionId	Optional	The ID of the service to be requested.	String
requestForUserIds	Optional	A list of user IDs that require the service.	List
excludedServiceversionIds	Optional	If the request is for a bundle, a list of service IDs in the bundle that should be excluded.	List
dependencies	Optional	A list of IDs of dependent (child) services that are associated with this service.	List
quantity	Optional	The order quantity for the request. If this property is not included, the default is 1.	Integer
referenceRequestId	Optional	The ID of a previously created request that is linked to this request.	String
myStuffItemId	Optional	The ID of the service request on the user's My Stuff page.	String
onBehalfOfUserId	Optional	The user ID that the service request is made on behalf of, if any.	String
requestedByUserId	Optional	The user ID that requests the service.	String
summary	Optional	A summary of the request. In BMC Helix Digital Workplace, this is displayed as the description at the top of the order page.	String
externalActivities	Required	A list of external activities from sources such as BMC Helix ITSM, using the properties described in the following table.	List

externalActivities properties

Name	Required/Optional	Description	Type	Notes
externalActivityId	Required	The unique ID of the external activity. For example, the Instance ID of a BMC Helix ITSM ticket.	String	NA
externalActivityDisplayId	Optional	The display ID, such as a work order ID, of the external activity.	String	NA
externalActivityType	Optional	The type of the external activity.	String	NA
externalSubCatalogId	Optional (but see the Notes column)	The ID of the subcatalog that the external activity uses.	String	At least one of externalSubCatalogId, connectionName, or connectionId must be provided.
connectionName	Optional (but see the Notes column)	The connection name for the BMC Helix ITSM connector.	String
connectionId	Optional (but see the Notes column)	The connection ID for the BMC Helix ITSM connector.	String

Example request body

{
   "title": "simple order request",
   "collaboratorsEnabled" : false,
   "serviceRequests": [
        {
           "serviceversionId": "2",
           "quantity": 1,
           "myStuffItemId": "",
           "externalActivities": [
                {
                   "externalActivityId": "IDGADG1AAT7X5AR7LUAUR7LUAUDC30",
                   "externalActivityDisplayId": "INC000000001101",
                   "externalActivityType": "HPD:Help Desk",
                   "connectionName": "Remedy"
                },
                {
                   "externalActivityId": "IDGADG1AAT7X5AR7LU41R7LU41DF2G",
                   "externalActivityDisplayId": "CRQ000000001103",
                   "externalActivityType": "CHG:Infrastructure Change",
                   "connectionName": "Remedy"
                }
            ]
        }
    ]
}

Response

Response	Value	Notes
HTTP code	200	NA
type	object	Returned object is of type SubmitServiceOrderResponseDto

Example response body

{
   "id": "204",
   "requestErrors": [],
   "requestDetails": [
        {
           "id": "208",
           "expectedDate": null,
           "generatesSrmRequest": false,
           "requestErrors": null,
           "collaborators": null
        }
    ],
   "expectedDate": null
}

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

GET /services/{serviceversionId}/myrequests

Parameters

Name	Required/Optional	Description	Type	Notes	Example
serviceversionId	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 request body

{
   "totalSize": 2,
   "data": [
        {
           "id": "1234",
           "serviceversionId": "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",
           "serviceversionId": "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": "test",
 "excerpt": "test",
 "price": {
 "paymentType": "Free",
 "currency": "USD"
 },
 "status": {
 "id": "4402",
 "serviceversionId": "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": "test",
 "excerpt": "test",
 "price": {
 "paymentType": "Free",
 "currency": "USD"
 },
 "status": {
 "id": "4302",
 "serviceversionId": "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": "fhyfgjhgjghghghjgh ",
 "excerpt": "yhytrtrtytryghhghhfhfh",
 "price": {
 "paymentType": "Once",
 "currency": "USD",
 "paymentSchedule": ""
 },
 "status": {
 "id": "4301",
 "serviceversionId": "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
serviceRequestIds	Required	Service request ID numbers represented as a list of string values.	String	["4402", "4302", "4301"]	Locate this parameter in the request body.
requestedFor	Optional	Filters service request IDs by requestedFor.	String	"Mary"	This is a query parameter.
requestedBy	Optional	Filters service request IDs by requestedBy.	String	"Francie"	This is a query parameter.

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

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": "test",
 "excerpt": "test",
 "price": {
 "paymentType": "Free",
 "currency": "USD"
 },
 "status": {
 "id": "4402",
 "serviceversionId": "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"
    ]
  }
]

To retrieve all comments posted to the given request

GET /services/requests/{requestId}/activities

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 an object with each comment.
type	application/json	Not applicable.

Example response body

[
    {
       "id": "10002",
       "serviceRequestId": "10012",
       "message": "Test",
       "activityLogType": null,
       "authorLoginId": "hannah_admin",
       "authorFullName": "Hannah",
       "createDate": "2022-08-24T22:29:41.000+0000",
       "modifiedDate": "2022-08-24T22:29:41.000+0000",
       "visibility": "PUBLIC",
       "attachments": []
    },
    {
       "id": "10001",
       "serviceRequestId": "10012",
       "message": "Doug",
       "activityLogType": null,
       "authorLoginId": "hannah_admin",
       "authorFullName": "Hannah",
       "createDate": "2022-08-24T22:14:43.000+0000",
       "modifiedDate": "2022-08-24T22:14:43.000+0000",
       "visibility": "PUBLIC",
       "attachments": []
    }
]

To add a comment to the given request

POST /services/requests/{requestId}/activities

Parameters

Name	Required/ Optional	Description	Type	Notes
requestId	Required	ID of the request.	String	Locate this parameter in the request URL.
text	Required	Text of the comment.	String	This is a query parameter.
visibility	Required	PUBLIC for the comment to be visible to users, or INTERNAL for the comment to be visible only to the creator.	String	This is a query parameter.
broadcast	Required	Whether to notify users subscribed to this request that a comment has been made.	Boolean	This is a query parameter.
authorLoginID	Optional	The login ID of the user making the comment.	String	This is a query parameter. The default is the currently logged-in user.

Example request body

{
       "text":"This is a comment",
       "visibility":"PUBLIC",
       "broadcast":true
}

Response

Response	Value	Notes
HTTP code	200	Successful response returns an object with each comment.
type	application/json	Not applicable.

Example response body

{
   "id": "10003",
   "serviceRequestId": "10012",
   "message": "This is a comment",
   "activityLogType": null,
   "authorLoginId": "hannah_admin",
   "authorFullName": null,
   "createDate": "2022-08-25T21:34:59.000+0000",
   "modifiedDate": "2022-08-25T21:34:59.000+0000",
   "visibility": "PUBLIC",
   "attachments": []
}

To add an attachment to the given request

POST /services/requests/{requestId}/attachments

Parameters

Name	Required/ Optional	Description	Type	Notes
requestId	Required	ID of the request.	String	Locate this parameter in the request URL.
activityLog	Required	Text of a comment associated with the attachment.	String	This is a query parameter.
visibility	Required	PUBLIC for the attachment to be visible to users, or INTERNAL for the comment to be visible only to the creator.	String	This is a query parameter.
broadcast	Required	Whether to notify users subscribed to this request that an attachment has been made.	Boolean	This is a query parameter.
authorLoginID	Optional	The login ID of the user making the attachment.	String	This is a query parameter. The default is the currently logged-in user.
file	Required	The file to be attached.	Binary	This is a query parameter.
attachmentNames	Required	The name of the file to be attached.	String	This is a query parameter.

Response

Response	Value	Notes
HTTP code	200	Successful response returns an object with each comment.
type	application/json	Not applicable.

Reviews

To retrieve all reviews

GET /reviews

Parameters

Name	Required/Optional	Description	Type	Example	Notes
serviceversionId	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",
"serviceversionId": "123",
"userId": "2345",
"title": "review title1",
"content": "review content1",
       "modifiedDate": "2015-08-20T00:24:22.000+0000"
},
{
"id": "2",
"serviceversionId": "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
serviceversionId	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

{
"serviceversionId": "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",
"serviceversionId": "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
serviceversionId	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",
"serviceversionId": "123",
"userId": "2345",
"rating": 0.8,
       "modifiedDate": "2015-08-20T00:24:22.000+0000"
},
{
"id": "2",
"serviceversionId": "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
serviceversionId	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

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

Response

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

Error handling

Failed requests return an error object with the following properties:

Name	Description	Type
message	Error message with the error code.	String

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",
"serviceversionId": "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	["000000000012912", "000000000012913"]	Locate this parameter in the request body.

Example request body

[
"000000000012912", "000000000012913", ...
]

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

Endpoints in the BMC Helix Digital Workplace Catalog REST API

Authentication

To request an authentication token

Parameters

Response

Categories

To retrieve a full category list

Response

Response properties

To retrieve descendants of a given category

Parameters

Response

Response properties

To retrieve category groups

Parameters

Response

Response properties

To retrieve categories of a given category group

Parameters

Response

Services

To retrieve details of a single service item

Parameters

Response

To search for services

Parameters

Response

To retrieve the full catalog view setting of ON or OFF

Parameters

Response

Requests and questions

To initiate a request for a service by ID

Parameters

Response

To get a service request questionnaire

Parameters

Response

To send an answer to a question

Parameters

Response

To submit one or multiple service requests

Parameters

Response

To submit a specific service request

Parameters

Response

Error handling

To create and submit a service request in a single API call

Parameters

serviceRequests properties

externalActivities properties

Response

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

Parameters

Response

To find requests

Parameters

Response

To find requests by IDs

Parameters:

Response

To find a request by its ID

Parameters

Response

To find all answers submitted for the given request

Parameters

Response

To retrieve all comments posted to the given request

Parameters

Response

To add a comment to the given request

Parameters

Response

To add an attachment to the given request

Parameters

Response

Reviews

To retrieve all reviews

Parameters

Response