Use cases for BMC Helix Digital Workplace Catalog REST API
This topic describes some of the basic use cases that you can accomplish by making the REST API requests described in this topic.
Before you begin
Review Getting-started-with-the-BMC-Helix-Digital-Workplace-Catalog-REST-API to be able to make the API calls described in this topic.
Required license
Importing services to BMC Helix Digital Workplace Catalog from external systems
Before importing services from external systems, you must have an appropriate connector deployed. Then, you can import services, as described in this procedure.
- A connection with the external system is configured during the setup process. When the connector is established, the external catalog becomes available for import.
- Specify the services that you want to import:
Review a list of available catalogs as follows:
Request URL: < DWP_base_uri > /catalogimport/catalogs
Request method: GET
URL Parameters:
perPage = < integer_value > ,
page = < integer_value > ,
sortBy = < string > ,
sortDirection = < string > ,
search = < string > ,
full = < boolean >Review the available services for a specified catalog as follows:
Request URL: < DWP_base_uri > /catalogimport/catalogs / {
catalogId
}
/services
Request method: GET
URL Parameters:
perPage = < integer_value > ,
page = < integer_value > ,
sortBy = < string > ,
sortDirection = < string > ,
search = < string > ,
status = < string >
Configure mapping templates for the services you want to import:
- To import a service from an external system, complete the profile details of the service in BMC Helix Digital Workplace Catalog with values from the profile of the external service.
Review the available mappings from the profile of the external service as follows:
Request URL: < DWP_base_uri > /catalogimport/catalogs / {
catalogId
}
/fields
Request method: GETComplete the profile details of the service in BMC Helix Digital Workplace Catalog with values from the profile of the external service as follows:
Request URL: < DWP_base_uri > /catalogimport/catalogs / {
catalogId
}
/templatemapping
Request method: PUT
Example body: {
"categoryIds": ["string"],
"serviceIds": ["string"],
"workflowId": "string",
"workflowName": "string",
"serviceTypeId": "string",
"questionnaireId": "string",
"questionnaireName": "string",
"questionnaireGroupId": "string",
"importMapping": [{
"id": "string",
"guid": "string",
"modifiedDate": "2017-05-26T15:50:24.516Z",
"rxId": "string",
"summary": "string",
"serviceTypeFieldId": "string",
"connectorFieldName": "string"
}]
}
When you complete the service template mapping, the service is ready to be queued for import.
Add the mapped services to the import queue as follows:
Request URL: < DWP_base_uri >/catalogimport/catalogs/{catalogId}/selection
Request method: POST
Request body:
{
"categorySelectIds": [
"string"
],
"serviceSelectIds": [
"string"
],
"categoryDeselectIds": [
"string"
],
"serviceDeselectIds": [
"string"
]
}You can use the preceding endpoint to remove services and service categories from the import queue, and then import categories.
Import services added to the queue as follows:
Request URL: < DWP_base_uri > /catalogimport/catalogs / {
catalogId
}
/import
Request method: POST
Request body:
{
"id": "{catalogId}"
}
Searching for services in BMC Helix Digital Workplace Catalog
You can search for services by using the BMC Helix Digital Workplace Catalog API with different parameters.
Run the following request:
Request method: GET
URL Parameters:
perPage = <integer_value>,
page = <integer_value>,
serviceIds = <string_value>,
categoryId = <string_value>,
title = < string_value >,
requestedfor = <string_value>
The following example shows a request example containing parameters:
The following example shows a possible response to the request:
"pageSize": 20,
"page": 1,
"services": [
"id": "107",
"name": "Create Office 365 User [Microsoft Office 365 Developer]",
"templateName": "IT Request",
"templateId": "1",
"templateType": "SERVICE",
"modifiedDate": "2017-05-16T14:15:28.000+0000"
}
],
"total": 1
}
Updating user entitlements in BMC Helix Digital Workplace Catalog
Perform the following operations to modify virtual marketplaces for entitling users to catalog services.
- To add users to entitlements
- To add user groups to entitlements
- To add services to entitlements for services
- To add banners to entitlements
- To assign Administrator users to entitlements
- To update an entitlement name
To add users to entitlements
Run the following request:
Request method: POST
Request body: {
"userIDs": ["<user_id>"]
}
The user is added to the specified virtual marketplace.
To add user groups to entitlements
Run the following request:
Request method: POST
Request body: {
"groupIDs": ["<group_id>"]
}
The specified group is added to the specified virtual marketplace.
To add services to entitlements for BMC Helix Digital Workplace Catalog services
Run the following request:
Request method: POST
Request body: {
"serviceIDs": ["<service_id>"]
}
To add banners to entitlements
Run the following request:
Request method: POST
Request body: {
"bannerIDs": ["<banner_id>"]
}
To assign Administrator users to entitlements
Run the following request:
Request method: POST
Request body: {
"adminIDs": ["<admin_user_id>"]
}
To update an entitlement name
Run the following request:
Request method: PUT
Request body: {
"id": "<virtualmarketplace_id>",
"name": "<virtualmarketplace_new_name>"
}
When an entitlement is updated, the response to this operation is as follows:
"id": "<virtualmarketplace_id>",
"guid": < null > ,
"modifiedDate": null,
"rxId": null,
"summary": null,
"name": "<virtualmarketplace_name>",
"userCount": < integer_value > ,
"adminCount": < integer_value > ,
"serviceCount": < integer_value > ,
"groupCount": < integer_value > ,
"bannerCount": < integer_value > ,
"userIDs": [],
"adminIDs": [],
"groupIDs": [],
"serviceIDs": [],
"bannerIDs": []
}