This documentation supports the 20.08 version of BMC Digital Workplace Advanced, which is available only to BMC Helix subscribers (SaaS).
To view an earlier version, select the version from the Product Version menu.

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:

Related topics

Integrating BMC Digital Workplace Catalog REST API with the service catalog

Using the Digital Workplace Catalog API Open link

Important

Unless an API endpoint requires a different header, the following header is required for all requests:

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

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

NameRequired/OptionalDescriptionTypeExampleNotes
idRequired

BMC Digital Workplace Catalog user login account (with the organization domain).

Stringhannah_admin@calbro.comLocate this parameter in the request body. This parameter is not specified by default.
passwordRequiredPassword.String<your_password>Locate this parameter in the request body. This parameter is not specified by default.
{
	"id": "<your_user>",
	"password": "<your_password>"
}

Response

ResponseValueNotes
HTTP code200Application returns an authentication token that is valid for about half an hour.

Categories

To retrieve a full category list

GET /categories

Parameters

NameRequired/OptionalDescriptionTypeExampleNotes
perPageOptionalPage size.Integer20This is a query parameter. Default for non-paginated search -1.
pageOptional

Page number.

Integer1This is a query parameter. Default 1.

Response

ResponseValueNotes
HTTP code200Returns a category list object array.
typeapplication/jsonNot applicable.


Response properties

NameDescriptionType
pageSizePass through the request parameter.Integer
pagePass through the request parameter.Integer
categoriesCategory object array.Array
{
  "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
categoryIdRequiredCategory ID to retrieve.String1234Locate this parameter in the request URL. This parameter is not specified by default.
depthOptional

Depth of the category being retrieved.

Integer2This is a query parameter. Default 1. Allowed values: 1, 2, 3.
requestedforOptionalWhen 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 code200Returns a category array object. If the requested categoryId does not exist or does not contain descendants, then an empty array is returned.
typeapplication/jsonNot applicable.


Response properties

NameDescriptionTypeNotes
idCategory ID used by the application.StringNot applicable.
guid

Unique ID used by the platform.

StringNot applicable.
nameCategory name.StringNot applicable.
categoryGroupId

Group to which the category belongs.

StringCurrently, there is only one category group, referenced as "Type of service".
parentIdID of the child's parent category.StringIf the parent ID is not available, null.
childCountNumber of direct descendant categories.IntegerNot applicable.
subCategoriesNullStringNot applicable.
[
  {
    "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 code200Application returns the category array.
typeapplication/jsonNot applicable.


Response properties

Name
Description
Type
idCategory group ID used by the application.String
guidUnique ID used by the platform.String
nameCategory group name.String
descriptionDescription of the category group.String
systemId

System ID of the category group.

String
groupStatusStatus of of the category group.String
childCountNumber of direct descendant categories.Integer
categoriesNullString
[
  {
    "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

categoryGroupIdRequiredCategory group ID to retrieve.String1234Locate this parameter in the request URL. This parameter is not specified by default.
depthOptionalDepth of the category being retrieved.Integer2This is a query parameter. Default 1. Allowed values: 1, 2, 3.
requestedforOptionalWhen 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.
[
  {
    "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/{serviceversionId}

Parameters

Name

Required/Optional

Description

Type

Example

Notes

serviceversionIdRequiredNot applicable.String 1234Locate this parameter in the request URL.
requestedforOptionalWhen 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.
{
  "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 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. Wildcards are also not supported.

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

Parameters

Name

Required/Optional

Description

Type

Example

Notes

perPageRequiredPage size.Integer20This is a query parameter. Default for non-paginated search -1.
pageRequired

Page number.

Integer1This is a query parameter. Default 1.
serviceversionIdsRequiredID of the service.String456Locate this parameter in the request body.
categoryIdRequiredID of the category.String476 Locate this parameter in the request body.
titleRequiredTitle of the service.String"Apple"Locate this parameter in the request body.
requestedforRequiredWhen 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.
{
  "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.


true
false


Requests and questions

To initiate a request for a service by ID

POST /requests

Parameters

Name

Required/Optional

Description

Type

Example

Notes

serviceversionIdRequiredID of the service.String 456Locate this parameter in the request body.
excludedserviceversionIdsRequiredA list of service revision IDs that will be excluded from the request bundle.String457Locate 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.
dependenciesRequiredNot applicable.String{serviceRequestId: string}Locate this parameter in the request body.
quantityRequiredThe service request quantity.Integer1Locate this parameter in the request body. Default 1.
referenceRequestIdOptionalA prior request ID, if relevant.String5678Locate this parameter in the request body.
myStuffItemIdRequiredThe My Stuff item ID.String9012Locate this parameter in the request body.
onBehalfOfUserIdRequiredThe user ID on behalf of which the service request is being made.String9013Locate this parameter in the request body.
questionsOptionalA list of common answers for relevant service request questions.List of strings
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.

{
  "serviceversionId" : "2417"
}


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

idRequiredThe service request ID of a new request.StringLocate this parameter in the request URL.
prefillRequestIdsOptional

A list of completed service request IDs to search for saved answers while re-requesting a service.

StringThis a query parameter.

Response

Response

Value

HTTP code

200

type

application/json

{
    "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/{serviceversionId}/questionnaire/answers

Parameters

Name

Required

Description

Type

Notes

serviceversionIdRequiredThe ID of the service.StringLocate this parameter in the request URL.
questionnaireIdOptionalThe ID of the questionnaire.StringLocate this parameter in the request body.
questionIdOptionalThe ID of the question.StringLocate this parameter in the request body.
answersOptionalAnswers to the questionnaire.List of stringsLocate this parameter in the request body.
serviceRequestIdOptionalThe ID of the service request.StringLocate this parameter in the 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.

{
    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 stringsLocate this parameter in the 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.


{
    "id": "2916",
    "requestErrors": [],
    "requestDetails": [],
    "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

serviceversionIdRequiredID of the service.StringLocate this parameter in the request URL.456
perPageOptional

Page size.

IntegerThis is a query parameter. Default 10.20
pageOptionalPage number.IntegerThis is a query parameter. Default 1.1

Response

Response

Value

HTTP code

200

type

application/json

{
    "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"

sinceRequiredFilter requests that are updated since the specified date.StringThis is a query parameter.

Tue, 08 Mar 2016 17:49:05 GMT

maxRequiredMaximum amount of requests that will be retrieved.IntegerThis is a query parameter.30

Response

Response

Value

Notes

HTTP code

200

Successful response returns a requests object array.

type

application/json

Not applicable.
[
  {
    "id": "4402",
    "requestingUserId": "Allen",
    "requestForUserId": "Allen",
    "name": "New environment test",
    "description": "<p>test</p>",
    "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": "<p>test</p>",
    "excerpt": "test",
    "price": {
      "paymentType": "Free",
      "currency": "USD"
    },
    "status": {
      "id": "1234",
      "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": "<p>fhyfgjhgjghghghjgh<br/></p>",
    "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

serviceversionIdRequiredService request ID numbers represented as a list of string values.String
["4402", "4302", "4301"]
Locate this parameter in the 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.
[
  {
    "id": "4402",
    "requestingUserId": "Allen",
    "requestForUserId": "Allen",
    "name": "New environment test",
    "description": "<p>test</p>",
    "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": "<p>test</p>",
    "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": "<p>fhyfgjhgjghghghjgh<br/></p>",
    "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 a request by its ID

GET /services/requests/{requestId}

Parameters

Name

Required/Optional

Description

Type

Example

Notes

requestIdRequiredID 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.
  {
    "id": "4402",
    "requestingUserId": "Allen",
    "requestForUserId": "Allen",
    "name": "New environment test",
    "description": "<p>test</p>",
    "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

requestIdRequiredID of the request.StringLocate 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.
[
  {
    "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

serviceversionId

Optional

Retrieves reviews of a given service.

String

123

This is a query parameter.
userIdOptionalRetrieves 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.
requestedforOptionalWhen 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.
{
  "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

serviceversionIdRequiredID of the service.String"123"Locate this parameter in the request body.
titleRequired

Title of the review.

String"review title1"Locate this parameter in the request body.
contentRequiredContent of the review.String"review content1"Locate this parameter in the request body.
{
  "serviceversionId": "123",
  "title": "review title1",
  "content": "review content1"
}

Response

Response

Value

Notes

HTTP code

201

Successful response returns no content.


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

To retrieve a review by its ID

GET /reviews/{reviewId}

Parameters

Name

Required/Optional

Description

Example

Notes

reviewIdRequiredID of the review. 465Locate this parameter in the request URL.
requestedforOptionalWhen 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.
{
  "id": "1",
  "serviceversionId": "123",
  "userId": "2345",
  "title": "review title1",
  "content": "review content1",
  "modifiedDate": "2015-08-20T00:24:22.000+0000"
}
{
  "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

reviewIdRequiredID of the review to be updated.String 675Locate this parameter in the request URL.
titleOptional

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.
contentOptionalUpdated 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.
{    
  "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

reviewIdRequiredID of the review to be deleted.StringLocate 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.
requestedforOptionalWhen 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.
{
  "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

serviceversionIdRequiredID of the service to be rated.String"123"Locate this parameter in the request body.
ratingRequiredRating value submitted as a percentage (number between 0 and 1).Float0.8Locate this parameter in the request body.
{
  "serviceversionId": "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

ratingIdRequiredID of the rating to retrieve.String 456Locate this parameter in the request URL.
requestedforRequiredWhen 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.
{
  "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

ratingIdRequiredThe ID of the rating to update.String"4321"Locate this parameter in the request URL.
ratingRequired

The rating value submitted as a percentage (number between 0 and 1).

Float0.6Locate this parameter in the 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

NameRequired/OptionalDescriptionTypeExampleNotes
(array list) YesList of the service IDs to be exported.String["1234", "1234"]Locate this parameter in the 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

NameRequired/OptionalDescriptionTypeNotes
(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:

NameDescriptionType
messageError message with the error code.String
dataError message description.String
HTTP codeAn object with the requested ID is not found.404
Was this page helpful? Yes No Submitting... Thank you

Comments

  1. Ashish Pandey

    There is a small correction required under the "To submit a single service request" section, the Path Params should be like below below POST /services/{serviceId}/requests/{requestId}/submissions

    Currently, it's missing the "/services" part.

    Jun 25, 2021 06:50
  2. Matthew Watts

    When authenticating with the API, the header "X-Requested-By" is required or the API request fails. This documentation doesn't mention this - please can it be updated?

    Feb 21, 2023 10:32
    1. Meenal Kulkarni

      Hi Matthew Watts ,

      Have you had a chance to look at the Getting started with the BMC Digital Workplace Catalog REST API topic?

      The topic lists basic information to help you get started with using the Catalog REST APIs and contains a section on the header required for all requests, which includes the X-Requested-By header value

      Let me know if you think the information needs to be repeated in this topic to avoid an API failure.

      Thanks.

      Meenal Kulkarni

      Feb 21, 2023 10:34
      1. Matthew Watts

        Hi Meenal,

        I think it would be helpful even to have a small note somewhere on this page stating this - having all the technical API documentation in one place would have definitely helped me and saved me from raising a ticket with BMC support :)

        Thanks

        Matt

        Feb 22, 2023 02:13
        1. Meenal Kulkarni

          Hi Matthew Watts ,

          I have added a note to this topic.

          Let us know if you need any other information to work with the APIs.

          Thanks,

          Meenal Kulkarni

          Feb 24, 2023 04:01