This documentation supports the 20.02 version of BMC Digital Workplace Advanced.

To view an earlier version, select the version from the Product Version menu.

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

Getting Service Health services 

Note

To get the Service Health services, you must use DWP as a base URL.

Service Health services are also referred to as ServiceAvailability in BMC Digital Workplace. To get all the available services, set the JESSIONID cookie value that is retrieved during the login call and specify the request details as follows:

Request URL: < DWP_base_uri >/services/serviceavailability
Request method: POST
Request body:
 {
    "queryName" : "MYIT_ALL_SERVICES",
    "attributes" : {
       "ServiceAvailability" : [
        "id",
        "linkedServiceId",
        "linkedServiceName",
        "name",
        "annotation",
        "status",
        "externalStatus",
        "isEnabled",
        "statusIsManual"
      ]
  }
}

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.

To add users to entitlements

Run the following request:

Request URL: < DWP_base_uri > /virtualmarketplaces/ < virtualmarketplace_id > /users
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 URL: < DWP_base_uri > /virtualmarketplaces/ < virtualmarketplace_id > /groups
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 Digital Workplace Catalog services

Run the following request:

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

To add banners to entitlements

Run the following request:

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

To assign Administrator users to entitlements 

Run the following request:

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

To update an entitlement name

Run the following request:

Request URL: < DWP_base_uri > /virtualmarketplaces/ < virtualmarketplace_id >
	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": []
}


 




Where to go from here

Endpoints in the BMC Digital Workplace Catalog REST API

Was this page helpful? Yes No Submitting... Thank you

Comments

  1. Johannes Richter

    Hi!

    Is it possible to delete users from a virtual marketplace via API?

    Thanks, Johannes

    Feb 03, 2021 03:24
    1. Ravee Panjwani

      Thanks for your comment Johannes Richter. Please confirm what's the use case you are trying to achieve? It seems like you might need to contact BMC Support.

      Thanks,
      Ravee

      Feb 22, 2021 06:25