Use cases for BMC 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 Digital Workplace Catalog REST API to be able to make the API calls described in this topic.

Importing services to BMC 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.

1. A connection with the external system is configured during the setup process. When the connector is established, the external catalog becomes available for import. 

2. Specify the services that you want to import:

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

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

3. Configure mapping templates for the services you want to import:

   1. To import a service from an external system, complete the profile details of the service in BMC Digital Workplace Catalog with values from the profile of the external service. 

   2. Review the available mappings from the profile of the external service as follows:

      Request URL: < DWP_base_uri > /catalogimport/catalogs / {
      	catalogId
      }
      /fields
      Request method: GET

   3. Complete the profile details of the service in BMC 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. 

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

5. 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 Digital Workplace Catalog

Using the BMC Digital Workplace Catalog API, you can search for services by specifying different parameters.

Run the following request:

Request URL: < DWP_base_uri >/services/search
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:

<DWP_base_uri>/services?page=1&perPage=20&search=office&sortBy=modifiedDate&sortDirection=desc

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 Digital Workplace Catalog

Perform the following operations to modify virtual marketplaces for entitling users to catalog services.

Request URL: < DWP_base_uri > /virtualmarketplaces/ < virtualmarketplace_id > /users
Request method: POST
Request body: {
	"userIDs": ["<user_id>"]
}

Request URL: < DWP_base_uri > /virtualmarketplaces/ < virtualmarketplace_id > /groups
Request method: POST
Request body: {
	"groupIDs": ["<group_id>"]
}

Request URL: < DWP_base_uri > /virtualmarketplaces/ < virtualmarketplace_id > /services
Request method: POST
Request body: {
	"serviceIDs": ["<service_id>"]
}

Request URL: < DWP_base_uri > /virtualmarketplaces/ < virtualmarketplace_id > /banners
Request method: POST
Request body: {
	"bannerIDs": ["<banner_id>"]
}

Request URL: < DWP_base_uri > /virtualmarketplaces/ < virtualmarketplace_id > /admins
Request method: POST
Request body: {
	"adminIDs": ["<admin_user_id>"]
}

Request URL: < DWP_base_uri > /virtualmarketplaces/ < virtualmarketplace_id >
	Request method: PUT
Request body: {
	"id": "<virtualmarketplace_id>",
	"name": "<virtualmarketplace_new_name>"
}

{
	"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": []
}

Where to go from here

Endpoints in the BMC Digital Workplace Catalog REST API