Skip navigation
1 2 3 4 Previous Next

Digital Workplace

51 posts
Share This:

There are times when you need to be able to access DWP-C functionality through an API. This might be in order to offer a Business to Business (B2B) interface to external systems, to help automate deployments through a tool like Jenkins or some other automation support. They are many opportunities that an API can open and this post explains how to use the REST API made available for DWP-C and provides an example for one use case.

The first starting point should be the API documentation - See this page for the 20.02 documentation: Integrating BMC Digital Workplace Catalog REST API with the service catalog - Documentation for BMC Digital Workplace Ad…

Since the DWP frontend also uses an extended version of this API, it is well utilised and tested. The usage is relatively simple,  but there are a number of areas that you need to consider.

Authentication

The REST API login uses simple credentials that then generate a token that is valid for 30 minutes. The syntax is shown in the use case below, but you should be aware of the following:

  • In theory, you can submit an RSSO request to get an authentication token for DWP-C, but the RSSO REST API is not public. Therefore it Is easier to have a local account defined in DWP-C. It is recommended that you have a special interface user for this purpose.
  • This user must have a password directly configured for the user in DWP-C and should have the minimum permissions that are required to perform the actions needed in the API. This is particularly true if you are providing API access to external systems, so also think about restricting access via entitlements or other mechanisms. On Helix environments, you will need to raise a ticket with Helix Ops to get the password set for the local DWP-C user.
  • The ITSM user and password will also need to match those on DWP-C if you plan to execute ITSM requests.
  • If you are providing API access to multiple external systems, each of those systems should be given a separate interface user to ensure traceability and that the access for each system can be managed independently.
  • You can set both the requested by (at least from 19.11) and requested for users via the API, so this interface user will not be visible in any requests.
The authorisation uses a simple authentication via a POST request and returns a time-limited token that must then be provided in the header of subsequent requests.
Note that there is currently a constraint here that the bulk request update (POST api/myit-sb/requests) requires DWP-C admin rights.

General Considerations

In general the API is easy to use, but these points should help make it even easier:
  • Make sure that you use UTF-8 character content encoding on all requests unless explicitly told to use something different. We had some issues with JMeter not always setting this and special characters will break otherwise. Note that I have not tried using 16-bit character sets via the API, but if anyone does have any experience of this, please add it to the comments below!
  • If you want to work with the REST API, then you will need some tools to help you. There are a few choices here:
    • A good text editor that understands JSON. There are plenty of text editors that can handle this. Popular examples are Notepad++ and Sublime Text, or BBEdit for the Mac. Make sure you have the relevant JSON plugins.
    • Various Browser plugins that provide REST client functions for testing. These are fine for simple baseline tests, but you will soon want to switch to a more advanced tool such as one of the ones listed below.
    • Postman: A popular REST test client. It has a free version, but more advanced features require payment.
    • JMeter: Part of the Apache project, this is a very powerful and flexible test tool for testing REST interfaces and also other areas. It is public domain and so has the usual advantages and disadvantages (not the easiest to use, but very flexible and free). It is my current tool of choice as it can also easily be used for both functional and load tests.
    • JSON parsing tools: These are generally useful for DWP-C workflows, but particularly so when handling the JSON responses to the REST calls. There are plenty of online JPATH tools that you can easily find, https://jsonpath.com/ is one example.
    • There are other tools that you may also choose. Please add them in the comments so that others can benefit!

REST Headers

REST APIs make use of headers in the requests to provide standard information:

default-bundle-scopemyit-sb
X-Requested-By<Name for source application>
Authorization<The authorisation token from the login request>
content-typeapplication/json

 

Any service requests should also include the following header (only for 19.11 onwards) to ensure that the on behalf of user is set correctly, both within DWP-C requests and any subsequent Work Orders or Incidents in ITSM:

impersonated-user-id<On Behalf of User>

Note that the on behalf of (or requested by) user must include the login name and the DWP-C tenant, e.g. interface_user@bmc.com.

 

Using the API

You should now have the basic information for calling the API, but we will use a specific example to show this in more detail. Note that elements in the example shown in angled brackets and highlighted red should be replaced by appropriate values from your environment and use case. The URL shown also clearly needs to be replaced.

This is one particular use case, if you are interested in others, please add them to the comments.

 

Sample Use Case - Request a Service

A common uses case is an API request to find and submit a specific service request. In order to do this, you need to perform the following steps:

  1. Login
  2. Find the Service Request that you want to call
  3. Populate the answers to the questions
  4. Submit the Request

In detail, this works as follows:

Login

The login step is needed to provide the authorisation token for subsequent requests.

Sample Login Request

POST http://dwpc.bmcdev.localdomain:8008/api/myit-sb/users/login
Headers:
Content-Type: application/json
default-bundle-scope: myit-sb
X-Requested-By: <source application>
Data:
{ "id": "interface_user@bmc.com", "password": "password" }

 

Sample Login Response
eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJBQXR1ZXFSY0JUcVJQZVZQSk84eFwvSDVrMmlaeVpoU25ycU1NS28ydGt3dDlUTXBLS0JOYlB6TWV5Q0c0Nk91V2FHeUttQ1ZqV3VvRDc1S1FkVkUwXC92dmZma0d5dmJJT3pxMStXbmdCMVB1cFhYZnNGTVNVaEE9PSIsIm5iZiI6MTU4MzYxMzI1NSwiaXNzIjoidHNpLW15aXRzYi5ibWNkZXYubG9jYWxkb21haW4iLCJfYXV0aFN0cmluZyI6IjFCVVh6UWJYcklNMWs2WVwvekRwMkJNbHJsSFQ1REFRRmZ6UTN4U0tHeUo4MkNLMk1lRlNseEdWbmJHenpxT2lnaE1UbHBGXC93N0o0WmY4UFp3bDBqQmxHakZ6VHNFZ0JYQkFTTnBYNHU3TXhYUk1oWE5WYUVlUT09IiwiZXhwIjoxNTgzNjE2OTc1LCJfY2FjaGVJZCI6MTQ2ODI5LCJpYXQiOjE1ODM2MTMzNzUsImp0aSI6IklER0FBNVYwRkU4WTNBUUdVMVc1UUZXNFFFNkpGUSIsIl9hYnNvbHV0ZUV4cGlyYXRpb25UaW1lIjoxNTgzNjk5Nzc1fQ.eBO42c2QTdqDZSxJEGQIScM1lVMzZ8ST9_MdRqa4rWY
Note that the authorisation token is also provided as a header response cookie called AR-JWT.

Search for Service

To search for a service, the recommended approach is to use a GET request that uses FTS. Note that because of the FTS usage, the search string will be tokenised by default, unless you encapsulate the entire string in URL encoded double-quotes ("), i.e. %22. For example %22ITSM%20Demo%22 for "ITSM Demo"
See this page for more details on how search works: How search works in BMC Digital Workplace

 

Sample GET Search Request

GET http://dwpc.bmcdev.localdomain:8008/api/myit-sb/services/search?q=<encoded search string>

Headers:

Content-Type: application/json

default-bundle-scope: myit-sb

X-Requested-By: <source application>
Authorization: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJBQXR1ZXFSY0JUcVJQZVZQSk84eFwvSDVrMmlaeVpoU25ycU1NS28ydGt3dDlUTXBLS0JOYlB6TWV5Q0c0Nk91V2FHeUttQ1ZqV3VvRDc1S1FkVkUwXC92dmZma0d5dmJJT3pxMStXbmdCMVB1cFhYZnNGTVNVaEE9PSIsIm5iZiI6MTU4MzYxMzI1NSwiaXNzIjoidHNpLW15aXRzYi5ibWNkZXYubG9jYWxkb21haW4iLCJfYXV0aFN0cmluZyI6IjFCVVh6UWJYcklNMWs2WVwvekRwMkJNbHJsSFQ1REFRRmZ6UTN4U0tHeUo4MkNLMk1lRlNseEdWbmJHenpxT2lnaE1UbHBGXC93N0o0WmY4UFp3bDBqQmxHakZ6VHNFZ0JYQkFTTnBYNHU3TXhYUk1oWE5WYUVlUT09IiwiZXhwIjoxNTgzNjE2OTc1LCJfY2FjaGVJZCI6MTQ2ODI5LCJpYXQiOjE1ODM2MTMzNzUsImp0aSI6IklER0FBNVYwRkU4WTNBUUdVMVc1UUZXNFFFNkpGUSIsIl9hYnNvbHV0ZUV4cGlyYXRpb25UaW1lIjoxNTgzNjk5Nzc1fQ.eBO42c2QTdqDZSxJEGQIScM1lVMzZ8ST9_MdRqa4rWY

Sample GET Search Response

{

    "page": 1,

    "pageSize": 1,

    "services": [

        {

            "autoDependent": false,

            "available": true,

            "bulkRequestedForUserLimit": 1,

            "bundledServices": [],

            "calculatedAvailability": true,

            "categories": [],

            "createdDate": "2020-02-24T14:39:38.000+0000",

            "description": "<p>Demo Service:</p>\n<p>Requires a Work Order Template</p>",

            "entitled": false,

            "excerpt": "This service contains some example ITSM functions",

            "externalWorkflow": "OTHER",

            "fulfillmentType": "INTERNAL_WORKFLOW",

            "guid": "AGGAA5V0FE8Y3AQERV1GQDUCVOR9X9",

            "iconUrl": "/api/myit-sb/content/AGGAA5V0FE8Y3AQGHN4DQFJQ2CY18A",

            "id": "12603",

            "importedFromITSM": false,

            "isDependent": false,

            "modified": true,

            "modifiedDate": "2020-02-24T14:39:40.000+0000",

            "monthlyCost": 0.0,

            "multiRequestBundle": false,

            "name": "ITSM Demo Service 0.1",

            "onceCost": 0.0,

            "price": {

                "currency": "USD",

                "freeLabelText": "Free",

                "paymentType": "FREE"

            },

            "quantity": {

                "enabled": false,

                "max": 100,

                "min": 1

            },

            "quickRequest": false,

            "rating": 0,

            "ratingCount": 0,

            "reopenWorkflowEditEnabled": false,

            "restrictedFullCatalogView": false,

            "score": 100,

            "serviceType": "IT Request",

            "surveyEnabled": true,

            "templateType": "SERVICE",

            "translations": [],

            "unavailableRequiredServicesCount": 0,

            "useBundledServicesCosts": false,

            "version": "0.1",

            "yearlyCost": 0.0

        }

    ],

    "total": -1

}

The main entry required is the service id (JPATH: $.services[0].id).

 

Add Request with Answers

Questions are defined by a unique ID (in very early versions, this was a sequential id, but now it is a GUID). If you have a fairly static catalogue, you can read the question ids in advance and then simply populate the answers directly.

If you have a more dynamic catalogues that changes more frequently, then you also need to lookup the questions and their IDs. See below for an example of this. There was an older mechanism that required you to submit the answers to each question as individual API calls, but since about 18.08 the recommended approach is to submit all answers in one request and this is the example shown here. The question ids and answers will depend on how they are defined in the catalogue - see also the "Get Questionnaire Details" request below.

Sample Add Request with Answers with
POST http://dwpc.bmcdev.localdomain:8008/api/myit-sb/requests

Headers:

Content-Type: application/json

default-bundle-scope: myit-sb

X-Requested-By: <source application>
impersonated-user-id: <requested by login id@tenant name>

Authorization: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJBQXR1ZXFSY0JUcVJQZVZQSk84eFwvSDVrMmlaeVpoU25ycU1NS28ydGt3dDlUTXBLS0JOYlB6TWV5Q0c0Nk91V2FHeUttQ1ZqV3VvRDc1S1FkVkUwXC92dmZma0d5dmJJT3pxMStXbmdCMVB1cFhYZnNGTVNVaEE9PSIsIm5iZiI6MTU4MzYxMzI1NSwiaXNzIjoidHNpLW15aXRzYi5ibWNkZXYubG9jYWxkb21haW4iLCJfYXV0aFN0cmluZyI6IjFCVVh6UWJYcklNMWs2WVwvekRwMkJNbHJsSFQ1REFRRmZ6UTN4U0tHeUo4MkNLMk1lRlNseEdWbmJHenpxT2lnaE1UbHBGXC93N0o0WmY4UFp3bDBqQmxHakZ6VHNFZ0JYQkFTTnBYNHU3TXhYUk1oWE5WYUVlUT09IiwiZXhwIjoxNTgzNjE2OTc1LCJfY2FjaGVJZCI6MTQ2ODI5LCJpYXQiOjE1ODM2MTMzNzUsImp0aSI6IklER0FBNVYwRkU4WTNBUUdVMVc1UUZXNFFFNkpGUSIsIl9hYnNvbHV0ZUV4cGlyYXRpb25UaW1lIjoxNTgzNjk5Nzc1fQ.eBO42c2QTdqDZSxJEGQIScM1lVMzZ8ST9_MdRqa4rWY

 

data:
{
"serviceId" : "<service id from service search>",
"requestForUserIds" : ["<requested for login id>"],
"excludedServiceIds": [
],
"quantity" : 1,
"questions": [
{
"questionId": "208859ba-a5d2-51f2-e6ea-2819cce66ded",
"answers": ["Incident"]
},
{
"questionId":"6281d8fe-9058-97ca-04b4-0f48a47e608b",
"answers":["Test Incident via API"]
},
{
"questionId":"1831048b-6303-5135-f9c5-26ece02a3836",
"answers":["Messaging Issue"]
},
{
"questionId":"9266062d-e4ed-0a86-c1d7-ee86e282529a",
"answers":["AGGAA5V0FE8Y3AQGWFEXQFYHYM7I17","AGGAA5V0FE8Y3AQGWFEXQFYHYM7I19"]
}
]
}

Sample Add Request Response

{
   "bundleRequestId": null,
   "guid": "AGGAA5V0FE8Y3AQERV1GQDUCVOR9X9",
   "requestErrors": [],
   "requests": [
   {
   "dependencies": null,
   "externalId": null,
   "onStartChanges": {},
   "questionnaire": null,
   "requestId": "33529",
   "serviceId": "12603"
   }
   ],
   "serviceId": "12603"
}

Get Questionnaire Details

This request can either be used in advance to get the question ids or dynamically as part of the API to get the questions. Here using tags to define question ids may make it easier to lookup the questions in a dynamic, catalogue-driven environment.

Get Questionnaire Details Request
GET http://dwpc.bmcdev.localdomain:8008/api/myit-sb/requests/<request id>/questionnaire

Headers:

Content-Type: application/json

default-bundle-scope: myit-sb

X-Requested-By: <source application>
Authorization: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJBQXR1ZXFSY0JUcVJQZVZQSk84eFwvSDVrMmlaeVpoU25ycU1NS28ydGt3dDlUTXBLS0JOYlB6TWV5Q0c0Nk91V2FHeUttQ1ZqV3VvRDc1S1FkVkUwXC92dmZma0d5dmJJT3pxMStXbmdCMVB1cFhYZnNGTVNVaEE9PSIsIm5iZiI6MTU4MzYxMzI1NSwiaXNzIjoidHNpLW15aXRzYi5ibWNkZXYubG9jYWxkb21haW4iLCJfYXV0aFN0cmluZyI6IjFCVVh6UWJYcklNMWs2WVwvekRwMkJNbHJsSFQ1REFRRmZ6UTN4U0tHeUo4MkNLMk1lRlNseEdWbmJHenpxT2lnaE1UbHBGXC93N0o0WmY4UFp3bDBqQmxHakZ6VHNFZ0JYQkFTTnBYNHU3TXhYUk1oWE5WYUVlUT09IiwiZXhwIjoxNTgzNjE2OTc1LCJfY2FjaGVJZCI6MTQ2ODI5LCJpYXQiOjE1ODM2MTMzNzUsImp0aSI6IklER0FBNVYwRkU4WTNBUUdVMVc1UUZXNFFFNkpGUSIsIl9hYnNvbHV0ZUV4cGlyYXRpb25UaW1lIjoxNTgzNjk5Nzc1fQ.eBO42c2QTdqDZSxJEGQIScM1lVMzZ8ST9_MdRqa4rWY

 

Get Questionnaire Details Response

 

 

{
   "questionnaire": {
   "bulkRequestedForUserLimit": 1,
   "createDate": null,
   "guid": null,
   "id": "12734",
   "modifiedDate": null,
   "name": null,
   "pages": [
   {
   "externalId": null,
   "id": "fa245f88-dc92-8e22-35b2-8fdf2a066234",
   "pageItems": [
   {
   "answerSource": "DEFAULT",
   "confidential": false,
   "defaultAnswer": null,
   "description": null,
   "enabledPasswordEncryption": false,
   "externalId": null,
   "hidden": false,
   "id": "3bf9b9c8-558b-22f4-6ca9-bbb0f335df12",
   "label": "Lookup RCF",
   "lookupThreshold": null,
   "perUser": false,
   "readOnly": false,
   "required": false,
   "tags": [],
   "type": "Lookup",
   "useDefaultLocale": false,
   "visible": true
   },
   {
   "answerSource": "DEFAULT",
   "confidential": false,
   "defaultAnswer": null,
   "description": null,
   "enabledPasswordEncryption": false,
   "externalId": null,
   "hidden": false,
   "id": "a687eb56-5132-5dfa-fc84-7c17c9b31584",
   "label": "RCF-ORA Test",
   "lookupThreshold": null,
   "perUser": false,
   "readOnly": false,
   "required": false,
   "tags": [],
   "type": "Lookup",
   "useDefaultLocale": false,
   "visible": true
   },
   {
   "answerSource": "DEFAULT",
   "confidential": false,
   "defaultAnswers": [],
   "description": null,
   "enabledPasswordEncryption": false,
   "externalId": null,
   "hidden": false,
   "id": "f2afe6f7-7f87-aea3-36d7-dd119b422cdb",
   "label": "RCF-ORA Test2",
   "perUser": false,
   "questionMultiColumn": {
   "data": [],
   "metaData": []
   },
   "readOnly": false,
   "required": false,
   "tags": [],
   "type": "MultiSelectDropdown",
   "useDefaultLocale": false,
   "visible": true
   },
   {
   "answerSource": "DEFAULT",
   "confidential": false,
   "defaultAnswer": null,
   "description": "<p>Enter the Summary for this object</p>",
   "enabledPasswordEncryption": false,
   "externalId": null,
   "hidden": false,
   "id": "6281d8fe-9058-97ca-04b4-0f48a47e608b",
   "label": "Summary",
   "maxLength": null,
   "perUser": false,
   "readOnly": false,
   "required": true,
   "tags": [],
   "type": "TextField",
   "useDefaultLocale": false,
   "visible": true
   }
   ],
   "perUser": false,
   "title": "Info"
   }
   ],
   "questionnaireGroupId": null,
   "rxId": null,
   "summary": null,
   "useDefaultLanguage": false,
   "workflowId": null
   }
}

Note that since questions can also include answers to dropdown requests, this response can get quite large.

This questionnaire is also from a different service than the submitted request above, so the questions do not match!

The question ids are clearly visible for each question.

Submit Request

The final step is to submit the order with the request created previously.

Sample Submit Service Request
POST http://dwpc.bmcdev.localdomain:8008/api/myit-sb/orders

Headers:

Content-Type: application/json

default-bundle-scope: myit-sb

X-Requested-By: <source application>

Authorization: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJBQXR1ZXFSY0JUcVJQZVZQSk84eFwvSDVrMmlaeVpoU25ycU1NS28ydGt3dDlUTXBLS0JOYlB6TWV5Q0c0Nk91V2FHeUttQ1ZqV3VvRDc1S1FkVkUwXC92dmZma0d5dmJJT3pxMStXbmdCMVB1cFhYZnNGTVNVaEE9PSIsIm5iZiI6MTU4MzYxMzI1NSwiaXNzIjoidHNpLW15aXRzYi5ibWNkZXYubG9jYWxkb21haW4iLCJfYXV0aFN0cmluZyI6IjFCVVh6UWJYcklNMWs2WVwvekRwMkJNbHJsSFQ1REFRRmZ6UTN4U0tHeUo4MkNLMk1lRlNseEdWbmJHenpxT2lnaE1UbHBGXC93N0o0WmY4UFp3bDBqQmxHakZ6VHNFZ0JYQkFTTnBYNHU3TXhYUk1oWE5WYUVlUT09IiwiZXhwIjoxNTgzNjE2OTc1LCJfY2FjaGVJZCI6MTQ2ODI5LCJpYXQiOjE1ODM2MTMzNzUsImp0aSI6IklER0FBNVYwRkU4WTNBUUdVMVc1UUZXNFFFNkpGUSIsIl9hYnNvbHV0ZUV4cGlyYXRpb25UaW1lIjoxNTgzNjk5Nzc1fQ.eBO42c2QTdqDZSxJEGQIScM1lVMzZ8ST9_MdRqa4rWY

 

data:

{ "requests":[ { "id" : "<request id>" } ] }

 

Sample Submit Service Response

{"id":"11438","requestErrors":[],"requestDetails":[],"expectedDate":null}

 

Sample Submit Request Error Response

Since the input parameters are not checked until the order is submitted, the most likely errors are issues with the input parameters. All errors are returned in the requestErrors array. A sample parameter errors is shown below:

{ "expectedDate": null, "id": null, "requestDetails": [], "requestErrors": [ { "id": "33529", "message": "Required question \"Template\" hasn't been answered", "requestedFor": null, "type": "UNCLASSIFIED" } ] }
Share This:

Many of our customers have raised the question on how we can expose Digital Workplace to the remote workforce.

 

High level steps

  1. Create Web Server in the corporate DMZ to ITSM solution
  2. Configure Single Sign On for the Web Server
  3. Complete User Testing of new Web Server with the ITSM solution
  4. Announce deployment of solution to your workforce

 

Architectural Diagram

ITSM @2x.png

Resources

Securing Tomcat Server For Remedy Single Sign-On

Add pfx certificate to tomcat (MidTier, SmartIT, Smart Reporting)

RSSO Configuring & Troubleshooting SAML Authentication

RSSO Kerberos Configuration & Troubleshooting

Available Resources to Ensure your Environment is Configured for Peak Performance

 

See also: COVID-19 Response Resources

Have a question, make a comment below

Share This:

BMC Software announces the 20.02 release of the BMC Digital Workplace product. This release delivers significant new functionalities that customers have requested, including enhancements to the end user experience and catalog capabilities.

 

All of the following enhancements are available for BMC Digital Workplace Advanced. Enhancements marked with an asterisk (*) are also available for BMC Digital Workplace Basic

External User Portal

 

Create a portal for users who are not internal to your organization.

 

Control access and enforce security policies.

Manage sub-tenants*

 

Manage sub-tenants in the BMC Digital Workplace Admin console.

 

 

Table question enhancements

 

Simultaneously view multiple rows across different pages and swipe across to view more columns on your mobile phone.

 

 

Smart IT cross launch*

 

Cross launch into Smart IT from a Change Approval. Additional fields are also available in a Change Approval Request.

 

Collaborate with People Groups

 

Configure multiple groups of users that end users can add as collaborators to a Service Request.

 

 

 

Category-based navigation*

 

Change navigation to tile based and optionally use a branded primary color.

 

Launch to a Category from a banner (advanced only).

Launch External URL

 

Configure a banner to launch in new window or existing one.

 

Bundle dependencies

 

Add dependent Services to Bundles.

Knowledge Management enhancements*

 

Improved search and localization for knowledge articles.

 

 

 

Update Service Request name

 

Map context or question data to Request title on submission.

 

Workflow attachments

 

Create separate work log attachment entries for Work Orders, Incidents and Change Requests.

 

Catalog Application Cache

 

Quickly reset the application Cache from the menu.

 

 

Attachment configuration*

 

Block attachment formats or increase size.

 

Run attachment script to instantly update your changes.

 

 

Compatibility

 

 

For version details of Remedy ITSM Remedy AR System  HR Case ManagementClient Management Atrium CMDB Cloud Lifecycle Mgmt please refer to our Compatibility Matrix.

 

 

Next Steps

 

For a comprehensive summary of all enhancements please refer to our Digital Workplace Advanced and Basic documentation.

Share This:

In this blog I'm going to explain how we can create a relationship between two Work Orders on Request submission. When both Work Orders have been completed the Service Request will also complete and if either Work Order has been cancelled, so in turn will the Service Request. To illustrate a common use case we'll set up a Service Request for a new employee to order a Laptop and Laptop carry case. Each Laptop type and Case will be represented as individual Work Orders.

 

Figure 1

 

First of all, create your service broker context and text variables which will be used to map your questions to relevant fields in the Work Orders.

 

Figure 2

Drag in two "Create Remedy with Identifiers" actions and map your questions to the relevant fields. In this case I'm adding some preceding text for each question response to make it clear who we need to ship the items to and at what address.

 

Figure 3

 

Now we need to create the relationship between both Work Orders by adding the relevant data to the "WOI:Associations" form. We can achieve this by using a combination of  "Build Input Set" and "Create Entry" Actions. The following table represents the first build input set where we populate the required fields and associate the Work Order ID to the Request ID01 & Request ID02 fields by using variables. We add another "Build Input Set" and "Create Entry Action" for each relationship switching the variables for the Request ID01 and Request ID02 fields.

Make sure to use the database name (found in Developer Studio) for each field and surround the key & values with double quotes 

 

Key (1-7)
Value (1-7)
Form Name01WOI:WorkOrder
Request ID01<Create Remedy with ID1><Output><Work Order ID>
Request Type01Work Order
Request Description01<Context ><Service><Service Name>
Form Name02WOI:WorkOrder
Request ID02<Create Remedy with ID2><Output><Work Order ID>
Association Type01Related to

 

When the mappings for "Build Input Set" are done we'll use the "Create Entry" action to map all of the data to the "WOI:Associations" form. We can achieve this by adding the output to "Field Values"  (Build Input1 >Output>Inputs) and finally adding the "Process Correlation ID" to "Correlation ID" (General > Process Correlation ID).

 

Figure 4

 

Next we'll add a "Receive Task" to wait for a signal from either Work Order before continuing and two separate "Track External Activity" actions to capture a "Completed" or "Cancelled" status from both Work Order in Smart IT.

For each "Track External Activity", make sure to use the relevant Work Order ID variable from the "Create Remedy with identifiers" actions (ID1 & ID2). The Track External Activity action is only supported with ITSM Applications (Incident, Work Order, Change, SRM Request).

Figure 5

 

Finally, we'll add an exclusive gateway with two conditions. The first condition will complete the Service Request in the event both Work Orders have been completed. Make sure to use "Activity Sub Status" from "Track External Activity1" and "Track External Activity2" here.

To end the workflow we use the "Set Service Request" status action which will reflect either the "Completed" or "Cancelled" possibilities.

 

 

Figure 6

 

The second condition will cancel the Service Request in the event either Work Order has been cancelled.

 

Figure 7

 

Now that we have our Workflow ready, let's add our questions. In this example I'm going to set up conditional questions which will automatically pick the relevant laptop case depending the type of laptop we're choosing. In this example I have hidden the "Case Type" question from the end user and only use it as a reference to map to the summary field of the Work Order. I have also created an open questionnaire action (see BMC doc link below for instructions) which will automatically populate the users address and map to the Work Order details field along with the full name.

Scroll above to "Figure 3" for the field mapping Illustration

Figure 8

 

Let's see this workflow in action by opening the Request, choosing our laptop type and submitting the Request !

 

Figure 9

 

 

Once it's submitted, we should see both Work Order in Smart IT.

 

Figure 10

 

If we open either Work Order, we'll see the relevant relationship in the "Related Items" tab and further up in the description field, we'll see our end users full name and address ready for shipping.

 

Figure 11

 

If we only complete one of these Work Orders, the Service Request will stay in the "In Progress" state but if we complete both, the Request will also complete (or do whatever you want to do in the workflow after that point). Similarly, if either Work Order has been cancelled, the Service Request change into a "Cancelled" state.

 

In summary, by leveraging Remedy workflow actions in combination with the Digital Workplace Catalog "Track External Activity" action we can establish relationships between applications while controlling the flow based on a defined status from multiple sources !

Depending on what you'd like to do, there are many ways to design workflow. This Blog is intended as an example to help anyone who's new to the Catalog !

If you have any Catalog workflow questions, please raise them as seperate questions so the whole DWP Community can see and respond collectively

 

Further Reading

 

Workflows for service fulfillment

Exploring the Question Designer

 

DWP Catalog Workflow: Dynamic status

DWP Catalog Workflow: Passing question responses to custom fields within BMC Remedy ITSM

 

Remedy AR System Remedy ITSM

Share This:

At BMC, we’ve been transforming Digital Workplace and it centers directly on how we help define the employee experience of the future. BMC Helix Digital Workplace is a self-service application for business users to connect with IT and HR anywhere, anytime, on any device.

 

Overview:

Entitlement enables you to control user access to services in your organization. Enterprise customers or service providers who use multi-tenancy to manage several companies can use entitlement rules to ensure that users can view only the available services that they are entitled to request.

 

 

In DWP Catalog, as a service catalog administrator, internal service supplier, internal service supplier administrator, or asset manager, you create virtual marketplaces to associate services, bundles, and banners that appear in a BMC Helix Digital Workplace user's catalog with users who can access them.

 

Now before you start working on DWP Entitlements, you should be aware of the permission levels and groups that specify the capabilities of the account by assigning a permission group in user form of DWP Catalog. You can access the AR system of DWP Catalog from Remedy Mid Tier.

 

Doc reference: Assigning BMC Helix Digital Workplace Catalog roles to user accounts

  • sbe-catalog-admins > Enables a user account to manage all aspects of the service catalog.
  • sbe-asset-managers > Enables a user to manage user entitlements by creating virtual marketplaces.
  • sbe-internal-suppliers > Enables a user to create, modify, and send services and bundles for approval.
  • sbe-internal-supplier-admins > Enables a user to create, modify, approve, and publish services and bundles.
  • sbe-agents > Enables a user to access the BMC Digital Workplace Catalog console to view service requests.
  • Administrator > Enables a user to any administrative user account to enable the user to log in to Remedy Mid Tier.
  • sbe-myit-users > Enables a user to request BMC Digital Workplace Catalog services from BMC Digital Workplace.

 

 

Entitlements for Services and Banners

 

  • Login to Digital Workplace Catalog as Administrator.
  • Go to Services > Entitlements and you will notice Virtual Marketplaces , Entitlements by User and Restricted Services.

 

  • Entitlements can be created based on following ways:
    1. User
    2. DWP Catalog User Group
    3. Dynamic filter by ITSM Core attributes
  • Note: Enable full catalog view allows all the users to access all the services and banners.
  • Once you have the requirement to personalize your business need with regards to various departments and employees, entitlements can be created.
    • Click on New Virtual Marketplaces

    • Add Users (You will notice all the users here from Remedy ITSM integrated with DWP Catalog)

    • Add Banner (Only published Banners will be available to add in this section)

    • Add Catalog (Only Published Catalogs will be available to add in this section)

    • All the Entitlement will be available which you created for the organization.

 

    • Login with user Bob Baxter and you will notice 2 Banner and 3 Services entitled for this user to access and view.

    • So, now if you want to use ITSM Remedy Core attributes, you will notice option available under Attributes.

    • ITSM integrated to DWP Catalog > CTM:People form (You must ensure these users are available in User form of DWP Catalog AR Server)
      • Note: The advantage of using ITSM core allows you to select user and groups as per Remedy ITSM > CTM:People form.

 

    • Login with any user who belong to Benefits department will see services and banner based on above entitlement.

 

Troubleshooting Tips:

 

Case1: Some entitlements do not work intermittently.

      • Rebuild Cache by accessing the DWP Catalog install location.

 

Case2: Specific user when login to DWP do not see the service based on entitlement.

      • When you add a user in the marketplace it add a string in the Group list of the user profile on DWP Catalog User form.
        e.g.
        5176d72f-88e8-4697-b686-83fc2e8fc667
      • Ensure this group is added to this user and also verify if the password is same for both Remedy integrated ITSM User to DWP Catalog User.
      • Remove the user from entitlement and re-add.

Case3: After upgrade or database copy entitlement stopped working.

      • Add logging to DWP in /opt/apache/tomcat8.0/external-conf/logback.xml change this (no restart is needed)

<property name="LOG_DWP_CATALOG" value="false"/>

 

to

 

  <property name="LOG_DWP_CATALOG" value="true"/>

 

Add the org.apache.http.wire section here:

  <!--Optional DWP Catalog logger-->

  <if condition='${LOG_DWP_CATALOG}'>

    <then>

      <logger name="org.apache.http.wire" level="DEBUG">

         <appender-ref ref="DWP_CATALOG_FILE"/>

      </logger>

      <logger name="com.bmc.bsm.myit.service.sb" level="DEBUG" >

        <appender-ref ref="DWP_CATALOG_FILE"/>

      </logger>

      <logger name="com.bmc.bsm.myit.rest.v2.assistance" level="WARN" >

        <appender-ref ref="DWP_CATALOG_FILE"/>

      </logger>

      <logger name="com.bmc.bsm.myit.service.social.activity_stream" level="WARN" >

        <appender-ref ref="DWP_CATALOG_FILE"/>

      </logger>

    </then>

  </if>

      • It will log the rest api calls that go between DWP and DWP Catalog. When the server gets into this state, investigate on dwp-catalog.log on the dwp side, arerror.log and bundle.log on the DWP Catalog.

 

Ideas:

  1. Enhance On-Behalf-Of (OBO) behavior in SRM and MyIT to be able to see Request from own Company/Organization/Department
  2. DWP Advanced: Possibility to add Custom-Fields for Entitlements/Market Places
  3. Requested for Marketplaces in DWPC

 

I hope that you find this useful as an example on how to get started with entitlements in DWP Catalog. I welcome any comments, feedback and suggestions that you may have regarding this blog post.  I also encourage you to use Ideas on BMC Communities to submit and vote on features that you would like to see in BMC Helix Digital Workplace Catalog.

Share This:

BMC Helix Digital Workplace 19.11 is now generally available. With this latest release, we have added enhancements to user surveys to enrich feedback, localized notifications for automatic translation based on user location, and more! Additionally, get an exclusive first look at our external user mode and natural language search, both of which are now available in beta.

 

All of the following enhancements are available for BMC Digital Workplace Advanced. Enhancements marked with an asterisk (*) are also available for BMC Digital Workplace Basic

Global search*

 

Browse through search categories and select an Approval or Request shortcut.

 

 

Specify a maximum of 100 results per search source.

 

 

 

Label customization*

 

Customize Activity Labels.

 

 

 

Complex Surveys

 

Create a Survey and associate conditional questions based on end user response.

 

 

 

Reopen Catalog Requests

 

Attach workflow to create a new fulfillment application when a Request has been reopened.

 

 

Sub-catalog Workflow assignment

 

Add or assign workflow to Sub-catalogs.

 

 

 

Localized notifications*

 

Receive localized notifications by email or phone.

 

The following features are available as Beta only

 

Natural Language Processing*

 

Optionally enable Natural Language Processing to refine search results.

 

 

 

External User Portal

 

To enable the External User Portal please contact Billy Yuen

 

Grant unregistered users access to a subset of your Catalog via an external Portal. These users are automatically created in BMC Remedy ITSM.

 

 

Associate the Portal with an external Company and control access.

 

Table response selections

 

Create a Static or Dynamic selection table.

Select table hyperlink for more details on user selection.

 

 

 

Compatibility

 

 

For version details of Remedy ITSM Remedy AR System  HR Case ManagementClient Management Atrium CMDB Cloud Lifecycle Mgmt please refer to our Compatibility Matrix.

 

 

Next Steps

 

For a comprehensive summary of all enhancements please refer to our Digital Workplace Advanced and Basic documentation

Share This:

The scenarios detailed below are common ones that can occur within DWP/DWPC along with some basic troubleshooting steps. If a Support case is needed, the logging to supply when creating the case is mentioned. The documentation links referenced below are for version 19.08. If you're running a previous version, similar links will exist for those versions as well (unless there was some change/addition to functionality in that specific area).

 

In the information below:

 

DWP = Digital Workplace Basic/Advanced

DWPC = Digital Workplace Catalog

 

1) Problem with items displaying in DWP views (i.e. Catalog/Timeline)

 

- For items not appearing in the Catalog, make sure the user is entitled to the item via SRM or DWPC.

- For native DWP Catalog items not appearing, confirm the integration between DWP and DWPC is configured properly:

 

Enabling and configuring the enhanced catalog for BMC Digital Workplace - Documentation for BMC Digital Workplace Advanc…

 

- For Timeline items check to see if any custom queries were added to the SRM Provider

 

- Capture the dwp.log in debug mode when reproducing the issue:

 

           DWP Advanced/Basic - Troubleshooting

 

- Collect F12 (browser logging) or Fiddler capturing the issue:

 

               F12 logging - How to capture network traffic using F12 (Developer Tools) when Fiddler is not an option

               Fiddler logging - How to capture a problem using Fiddler

 

2) Notifications not occurring as expected from DWP

 

- Make sure the event/action is one that will result in a notification:

 

Configuring status updates and notifications - Documentation for BMC Digital Workplace Advanced 19.08 - BMC Documentatio…

 

- Confirm email has been configured properly for DWP:

 

Configuring email notifications - Documentation for BMC Digital Workplace Advanced 19.08 - BMC Documentation

 

- Capture the dwp.log in debug mode when the notification should be occurring

 

3) Post installation steps for DWP Catalog

 

             - Most post-install issues are related to user not having permissions or correct passwords for the DBs/tablespaces. Post-install information below:

 

             Loading the BMC Digital Workplace Catalog tenant setup data - Documentation for BMC Digital Workplace Advanced 19.08 - B…

 

            - For additional troubleshooting/validation steps for the install/post-install, please see the blog below:

 

               Vinay Mane's Blog

 

4) Trouble connecting to DWP/DWPC using RSSO

 

- Documentation link for configuring RSSO and DWP:

 

https://docs.bmc.com/docs/digitalworkplaceadvanced/1908/configuring-bmc-digital-workplace-for-remedy-single-sign-on-8719…  

 

- Follow steps detailed in this article (also mentions logging needed to troubleshoot issues):

 

DWP Advanced-How to Integrate DWP Advanced with RSSO?

 

- An RSSO diagnostic tool for DWPC detailed here:

 

https://communities.bmc.com/community/bmcdn/digital-workplace/blog/2016/12/22/troubleshooting-myit-service-broker-wip#ji…

 

5) Trouble connecting to DWP/DWPC when SSL is used

 

- Ensure that Tomcat is configured properly for SSL:

 

Configuring SSL for the Tomcat server - Documentation for BMC Digital Workplace Advanced 19.08 - BMC Documentation

 

- For DWP Catalog the following two resources need to be utilized to ensure SSL is configured properly:

 

            Configuring access to the BMC Digital Workplace Catalog server over SSL - Documentation for BMC Digital Workplace Advanc…

 

            DWP Catalog -We have enabled SSL on the DWP Catalog and now we are getting this "PKIX path building failed" error in the DWP Enhanced Catalog Section/ Authentication failed in bundle.logs

 

6) Fulfillment request not getting created from native DWP Catalog service, workflow not completing as expected, but not in a Failed/Error state

 

            - DWP Catalog Console => Reports => Service Requests => View Process => Details pane => Exceptions/Process Inputs

 

- When the issue is reproduced, obtain the bundle.log as detailed below:

 

DWP Catalog - Troubleshooting

 

7) DWP Catalog Approval not working as expected

 

- There could be several items affecting a DWPC Approval, a good set of steps for troubleshooting them is detailed here:

 

https://communities.bmc.com/community/bmcdn/digital-workplace/blog/2016/12/22/troubleshooting-myit-service-broker-wip#ji…

 

- Key items for the remoteaction configuration detailed in the above link:

 

      • Confirm ITSM integration patch is installed properly (Server-Side Filter/API logging from the ITSM server can help here)
      • Correct Java path in remoteaction.bat/sh
      • Correct path to remoteaction SB ApprovalConfiguration forms

 

8) Status from ITSM ticket not syncing properly with DWP Catalog workflow

 

- The items mentioned in #7 will apply here as well since remoteaction is being utilized to sync the status between ITSM and DWPC

 

9) Problems searching within DWP

 

- There are several sources that can be searched within DWP - DWP items, ITSM items, DWP Catalog items. For more details see below:

 

            https://docs.bmc.com/docs/digitalworkplaceadvanced/1908/how-search-works-in-bmc-digital-workplace-871981579.html 

 

- Troubleshooting problems with search will depend on what type of item is being searched. Details on each item below:

 

      • DWP items - dwp.log and F12 (browser logging) or Fiddler logging capturing the issue
      • ITSM Items - Make sure FTS is working as expected within ITSM, and if searching for SRDs make sure it's working when searching for the SRDs within Request Entry. For logging needed to troubleshoot further, the same logging as for DWP items would be suitable along with Server-Side SQL/API logging from ITSM when the search is done
      • DWP Catalog items - Make sure FTS has been configured, and the search cache has been refreshed for the DWP Catalog server as is detailed in the links below (For logging needed to troubleshoot further, the same logging as for DWP items would be suitable along with Server-Side SQL/API logging, and the bundle.log from the DWPC server when the search is done):

 

                      Configuring search for enhanced catalog items in BMC Digital Workplace - Documentation for BMC Digital Workplace Advance…

 

                       DWP - Catalog search is not working for SRDs, Services, Tags

 

 

Additional reference material:

 

Logging available in DWPC - https://communities.bmc.com/community/bmcdn/digital-workplace/blog/2016/12/22/troubleshooting-myit-service-broker-wip#jive_content_id_Logging_Table

Share This:

Today, we are excited to announce BMC Digital Workplace 19.08. The latest release of Digital Workplace includes exciting new end user and administrator enhancements to help bring organizations into the Future of Work !

 

All of the following enhancements are available for BMC Digital Workplace Advanced. Enhancements marked with an asterisk (*) are also available for BMC Digital Workplace Basic

End User Experience

 

Active Events*

 

 

Filter and search against active Events.

 

Page Size*

 

Control the volume of records being displayed

 

Administration

 

 

Managed Services

 

Add and manage additional customers.

 

 

Credit Management

 

Optionally replace currency with a credit based system.

 

 

Once a Service Request is submitted the assigned credit is deducted from the balance above.

 

Default Language*

 

Control the default language of your organization

 

 

Order ID*

 

Order ID is no longer associated with an individual request and has been replaced with Request ID. Order ID's are now applicable to multiple items only.

 

Password Question

 

Create a password question and enforce a regular expression. Optionally choose whether to encrypt the password.

 

 

Counter Question

 

Add a counter question and choose your increment.

 

Conditions across questionnaire pages

 

Conditions are now supported across subsequent pages.

 

Default Requested Login Name

 

Set the default answer to requested "For" or "By" Login name.

 

 

Compatibility

 

 

For version details of Remedy ITSM Remedy AR System  HR Case ManagementClient Management Atrium CMDB Cloud Lifecycle Mgmt please refer to our Compatibility Matrix.

 

 

Next Steps

 

For a comprehensive summary of all enhancements please refer to our Digital Workplace Advanced and Basic documentation                                                                  

Share This:

BMC Software announces the 19.05 release of BMC Digital Workplace. This release delivers significant new functionalities requested by customers.

 

All of the following enhancements are available for BMC Digital Workplace Advanced. Enhancements marked with an asterisk (*) are also available for BMC Digital Workplace Basic

End User Experience

 

 

Satisfaction Surveys*

 

Single question surveys are now also available for Catalog Requests.

 

 

To view the rating simply open the Report in the Catalog Administration Console.

 

Enhanced Email Templates*

 

Cross launch into Digital Workplace using HTML Templates.

 

 

 

Notification settings*

 

Change notification preferences.

 

 

Progress Bar

 

Quickly view the progress of a Service Request.

 

 

Auto Dependent Services

 

Add dependent Services automatically.

 

Administration

Branding*

 

An additional grey navigation style is now available.

 

 

Change the name of the Browse Category button or modify the default search placeholder and result filters.

 

Catalog Dashboard

 

Browse dashboard categories and view Connector health.

 

 

Self-Help

 

Click for guided assistance and links to help topics & videos.

 

 

Bypass permissions

 

End users can now transparently access forms with special permissions.

 

 

 

Compatibility

 

 

For version details of Remedy ITSM Remedy AR System  HR Case ManagementClient Management Atrium CMDB Cloud Lifecycle Mgmt please refer to our Compatibility Matrix.

 

 

Next Steps

 

For a comprehensive summary of all enhancements please refer to our Digital Workplace Advanced and Basic documentation                                                                              

Share This:

Integrating the Digital Workplace Catalog with BMC Asset Management allows users to view their Assets from the "MyStuff" Tab. We can also add Asset Actions to launch Service Requests and dynamically populate them with Asset information.

 

A common example would be reporting a problem against an existing asset or requesting a new one.

 

 

To enable this integration in the Catalog, click the gear icon on the top right hand corner of the Administration page.

 

 

Only Assets which belong to the logged in user (owned or used by) can be displayed in MyStuff. To add or modify ownership open the Asset Console and update the People tab with the owner/user.

 

 

 

Before we can view these assets in Digital Workplace we also need to add the associated classes into a new or existing group within the "Asset Groups" section in the Catalog.

 

Now that we have grouped our assets we can associate an action to retrieve asset information and optionally launch a Request with this information in BMC Digital Workplace. To achieve this functionality create a Service Action and add a questionnaire with whatever fields you may be interested in from Asset Management.

 

 

Next, open the question designer and create questions for each of the fields you'd like retrieve data from. In the example below we have a drop down menu which is linked to three possible sets of Asset questions.

 

 

Now let's create an action to automatically fill in each of these questions from Asset management as soon as the questionnaire is opened. To do this we use the "Open questionnaire" Trigger" with the "AST:BaseElement" form with a qualification of 'Reconciliation Identity' is 'Asset External ID'. This means only information against the Asset I choose will be returned.

 

 

By selecting fields from the "AST:BaseElement" form we can map asset data against each of our text questions.

 

Finally, we're ready to associate this action with each of our Asset Classes.

 

 

 

In order to view and launch actions we simply navigate to the "MyStuff" page and choose whatever action has been defined.

 

As soon as we select "Report Asset problem" the Request opens and automatically populates with the relevant data from BMC Asset Management !

 

In summary, not only are we giving users more visibility about their Assets we're also reducing the level of effort to retrieve and accurately report against dynamic Asset Data !

Share This:

The new branding interface replaces the previous process, and eliminates the procedure that required you to update and copy the CSS to apply your branding changes. Use a convenient interface to customize the logo, name, and colors as per your requirements. The new responsive user interface allows your changes to be seamlessly made available across various desktop and mobile devices. Since the previous tenant.css is no longer applicable, you will need to apply your branding using the new branding interface.

Rebrand_preview.png

In addition to the above branding options, you can use the BMC Digital Workplace Admin Console to easily hide the following features from your end users:

  • Shopping Cart
  • Catalog Ratings and Reviews
  • Knowledge Article Feedback
  • Similar Knowledge Articles
  • Social Activities
  • Posts

For more information, see Rebranding BMC Digital Workplace - Documentation for BMC Digital Workplace Advanced 19.02. For a complete list of new and updated features that have been released, see 19.02.00 enhancements - Documentation for BMC Digital Workplace Advanced.

Share This:

BMC Digital Workplace provides a new responsive user interface in the 19.02 release. The new UI is designed based on the Progressive Web App that supports desktop and mobile devices.

  • All features and branding changes are seamlessly made available on desktop and mobile devices.
  • An iOS native app that supports push notifications and QR code scanning is available.

Client deployment flowchart

Use the following chart to see the available client deployment routes.

Clients deployment options in 19.02.png

Mobile device options

All features such as push notifications, and QR code scan will continue to work with this release on the supported mobile clients. Please see below for a consolidated list of available options on your mobile devices:

Mobile deployments.png

For a complete list of new and updated features that have been released, see 19.02.00 enhancements - Documentation for BMC Digital Workplace Advanced.

Share This:

BMC Digital Workplace 19.02 is Now Available. This release delivers significant new functionalities that customers have requested, including enhancements to the end user experience and catalog capabilities.

 

All of the following enhancements are available for BMC Digital Workplace Advanced. Enhancements marked with an asterisk (*) are also available for BMC Digital Workplace Basic.

Revamped User Interface

 

 

Progressive Web Application (PWA)*

 

Dynamic "app-like" experience on your Device browser or Desktop.

 

 

Active and Past Events*

 

Quickly view current and past events via the My Activity page.

 

 

Bundle details

 

View in-depth bundle details.

 

 

Multiple approval view*

 

View all pending approvals simultaneously.

 

 

Search functionality*

 

Select previous search results and refine by filtering.

 

 

Optional Social functionality*

 

Open application preferences to view social activity.

 

 

 

Service health tab

 

Services now have their own dedicated tab.

 

 

 

Digital Workplace Admin enhancements

 

Rebrand the PWA User Interface*

 

Quickly rebrand the PWA User Interface and changes will be automatically reflected across desktop and mobile clients.

 

 

PWA on iOS doesn't currently have the ability to receive push notifications. Please download the "Digital Workplace" app from the App Store

to enable this functionality. The rebranding changes will be visible on login.

Mobile view

 

 

Desktop view

 

 

Build a custom home page

 

Build your own custom page and modify layouts.

 

 

Hide functionality*

 

Hide additional functionality via the DWP Client Administration console.

 

 

Collaborator preferences

 

Create and load a default collaboration Group.

 

Change Log Level*

 

Quickly change the log level in both the DWP Client* and Catalog

 

 

Questionnaire Tags

 

Add internal tags for use in workflow.

 

 

 

Copy Catalog questionnaire

 

Optionally copy questionnaires with workflow.

 

 

Date restrictions for questionnaires

 

Choose active duration.

 

 

Compatibility

 

For version details of Remedy ITSM Remedy AR System  HR Case ManagementClient ManagementAtrium CMDB Cloud Lifecycle Mgmt please refer to our Compatibility Matrix.

Next Steps

 

For a comprehensive summary of all enhancements please refer to our Digtal Workplace Advanced and Basic documentation

Share This:

This article follows up on a previous article where we looked at setting up the API to integrate DWP Catalog with remote servers. We looked at the connector description and the various calls that need to be defined. If you followed along you hopefully ended up with a working interface.

 

But that’s all it is for now: an interface. A lot of the values we’re returning are hardcoded and it doesn’t do anything at the moment. What I want to do next is explain how to build a full integration. We’ll use the same interface, so if you haven’t already done so, make sure to read my first blog article.

 

What are we going to build? It can’t be too complicated, so what I propose building is a simple ping activity. The basic idea is that you can invoke the action to check if a server is online. It will send out a ping request and report back if the server can be reached or not. You could use this in your workflow to check if a server can be reached, and depending on the outcome you can engage a specific team or escalate it further. We’re going to output a Boolean so that will work nicely with Exclusive Gateways.

 

Just to remind ourselves, this is how the integration works:

 

 

What we are interested in is the connector logic. Our action will return a Boolean indicating if the machine is alive or not. Using the same overview, these are the relevant components:

 

 

Notice I’m not going to an external server, I’m just executing code to do the ping which is all Java. Let’s first write a simple Java class, just so we know what the code looks like and how it works. This is what I came up with:

 

package pingservicetest;

import java.io.IOException;
import java.net.InetAddress;


public class PingServiceTest {

  public static boolean isMachineAlive (String machineName, int machinePort) {
    try {
      InetAddress inet;
      inet = InetAddress.getByName(machineName);
      return inet.isReachable(500);
    } catch (java.net.UnknownHostException e) {
    } catch (IOException e) {
    }  
        
    if (machinePort == 0) {
      machinePort = 111;
    }        
        
    try (Socket s = new Socket(machineName, machinePort)) {
      return true;
    } catch (IOException ex) {
    }
    return false;
  }


  public static void main(String[] args) {
    System.out.println(isMachineAlive("clm-aus-01234"));
  }
}

 

I want to check if servers are available or not, so I need to execute some form of ping command to confirm that they're alive. There's no TCP ping command in Java, but I can just use InetAddress. If I don’t get a response I try an additional Socket call. If I can get a successful connection I return true, if not I return false. I included the example at the end of this article, which you can run if you want to. It’s nothing fancy but it’s a good example of the way you can extend Catalog’s functionality.

 

I don’t like to put everything in one big file, so to make it manageable (and mirror the original diagram) I’m splitting this in two classes:

 

  • RCFController handles the interface. Its primary role is to accept HTTP requests from Catalog and respond with the correct JSON code.
  • RCFLogic is new, this is the class containing the code which does the actual processing. In our case that’s the isMachineAlive method.

 

 

Let’s start with RCFLogic. We already wrote and tested our code so we just need to define the class:

 

package rcf;

import java.io.IOException;
import java.net.*;

public class RCFLogic {

  public static boolean isMachineAlive(String machineName, int machinePort) {
         …
  }
}

 

Nothing new there, it’s a typical Java class, no references to Spring or Catalog. All of this is separate, but needs to be referenced properly. We need to know what the service accepts, what goes out and what format this is in. The interface we used in the first article can stay largely unchanged but I need to add the Port as an input and return a Boolean instead of a String. Here’s the action part of descriptor:

 

"name": "isMachineAlive",
"displayName": "isMachineAlive",
"path": "isMachineAlive",
"inputs": [
  {
    "name": "machineName",
    "type": "String",
    "required": true
  }
  {
    "name": "tcpPort",
    "type": "Integer",
    "required": false
  }
],
"outputs": [
  {
    "name": "Result",
     "type": "Boolean"
  }
]

 

I accept machineName and tcpPort and I return a Boolean called Result. I use the same code based on org.json as last time. Based on this I know I get this HTTP request in from Catalog:

 

POST http://server:8080/jbconnectivity/pingMachine HTTP/1.1

{
  "inputs": {
    "machinePort": null,
    "machineName": "clm-test-12345"
  },
  "connectionInstanceId": "jbconnectivity-1"
}

 

The request is generated by Catalog, but it bases this on the definition which I supplied and uses the values set during workflow creation. I write my code in the controller to handle this. I also know what the HTTP response should be:

 

HTTP/1.1 200

{
  "outputs":
  {
    "result":true
  }
}

 

With some help from org.json and Spring this is the code I came up with:

 

@RequestMapping(value = "/jbconnectivity/pingMachine", method = RequestMethod.POST)
@ResponseBody
public String checkPing(@RequestBody String payload) {
  JSONObject jsonPayload = new JSONObject(payload);
  String machineName = jsonPayload.getJSONObject("inputs").getString("machineName");
  int machinePort = 0;

  try {
    machinePort = jsonPayload.getJSONObject("inputs").getInt("machinePort");
  } catch (JSONException e) {}

  JSONObject jsonInputs = new JSONObject();
  jsonInputs.put("result", RCFLogic.isMachineAlive(machineName, machinePort));
  JSONObject jsonPing = new JSONObject();
  jsonPing.put("outputs", jsonInputs);


  return jsonPing.toString();
}

 

I first accept the payload from the POST request which I convert into a JSON object (jsonPayload). I then extract the machine name and the port (the try/catch clause is just to deal with the null value). Once I have all the values I create the JSON I want to respond with (jsonPing and jsonInputs). The point where I call my method in RCFLogic is line 13.

 

That’s all I’m going to do. Because I don’t connect to an external system, I don’t have to do any health checks, so I’m just going to keep the hardcoded values for checkHealth. Sure, there are things that could be improved, I’ve done some housekeeping in the actual example which I’ve attached at the end of the article, but I hope you get the principle.

Okay, let’s give it a go! I’m keeping the workflow as simple as possible, no fancy conditions, just two questions and one activity.

 

 

Curious if it’s going to work? Let’s log into DWP and create a new service request:

 

 

Because my workflow doesn’t actually create any requests in a backend system, I’m just going to have a look at the Service Requests report on the Catalog side:

And lo and behold, it works! Catalog executed the action, sent a POST request to the API as per the definition. My code picked up the POST request and called the isMachineAlive method in the RCFLogic class. And that was all passed back to DWP.

 

I know, this is fairly basic but I hope you agree that it works quite well. We’re separating Catalog from the external integration by using an API which adheres to strict standards. As long as I make sure I define the interface correctly, it’s up to me to respond to the incoming HTTP requests. It doesn’t really matter what you do in the backend to process the request. It can be as simple as extending the functionality by adding a few custom actions to calculate a week number based on a date, or it can be as complicated as integrating using SOAP-based web services. But keep in mind that this doesn't allow you to interact with DWP, you can't write a service which pushes values to DWP directly, it's all in the background. But it’s up to you and I look forward to seeing what you will come up with. Any questions or feedback? Leave a comment below.

 

Best wishes,

Justin

Share This:

It won’t come as a surprise to you that Catalog integrates seamlessly with ITSM. It’s easy to create work order and incident records. As a backend fulfilment system, integration is key and Catalog interacts with various systems using out-of-the-box connectors like Active Directory, Flexera or MS Office. For most other needs Catalog uses Integration Service which makes it possible to interact with a whole range of other connectors and even allows you to write your own.

 

This should take care of the majority of your integration needs, so is there a need for the ability to integrate directly with remote servers? It’s a recent feature, added only in 18.11, which makes it possible for Catalog to connect to external servers using a HTTP-based interface. Is there any benefit to this? I’d argue there is: while there’s greater work involved in building your own interface, there is also greater flexibility.

 

I really like the solution for connecting different cloud-based applications, but it has its drawbacks: Integration Service is a cloud-based solution, so even if you want to connect your on-premise Catalog server to your local application, it requires you to do this via the cloud. Integration Service also requires a license, and the solution might not be right for you if you’re looking for a small integration or extension.

 

Direct integration with remote servers resolves this. It puts you in control of the integration, both in terms of design and development, but also the hosting location, without any need for an intermediate connection to the cloud. It also suits small-scale extensions, if you want to add some specific functionality or want to integrate with a local application, this might be the solution for you.

 

True, in most cases the combination of out-of-the-box connectors plus Integration Service is enough. But for a backend fulfilment system, integration is paramount and we’ll make every effort to ensure you’re successful.

 

Does this mean that it’s going to be easy to set up? I can’t promise you that. The truth is that you have to build everything yourself, there’s no framework and there are no connectors. You build the server, design the API and all of this has to adhere to a strict standard. Daunting? I agree, but still doable. And I’m here to help.

 

Let’s first talk about the various components. I’m going to deviate slightly from the official documentation as I find it easier to explain it this way. Here’s how I see the integration:

DWP uses Catalog as its backend fulfilment system: users submit requests and Catalog handles the workflow process as part of the service. Catalog has the ability to integrate using out-of-the-box components, Integration Service and Remote Connectors. The Remote Connector is a web-based application which runs on a web server. The key part of this is the HTTP-based API, that’s the part Catalog interacts with. The interface adheres to a specific standard: there are certain requests that will be made and Catalog expects responses in a certain format. The API in turn uses the connector logic to do whatever is required to process: calculate something, return data, create requests, etc. It’s up to you how you want to do this. Notice I used a dashed line for the external system. The primary reason would to communicate with the external system, but this doesn’t necessarily have to be the case. If you want to return week numbers based on a date, that’s absolutely possible.

 

As far as Catalog is concerned it’s communicating with the API, it doesn’t really matter to Catalog what’s happening further upstream, so what we need to do first is define this interface. I’m going to show you how to build a full connector, but I will spread this over two articles, in this first article I’m only going to build the API part. I’m not actually building the connector logic or integrate with an external system, this will just overcomplicating things and stand in the way of explaining the connector properly. We’ll leave this to the second article. This what we’re going to build:

We have to do everything from scratch, in order to get this API working we need to write a web based application which accepts certain HTTP requests and responds in a certain way. These are the calls we need to get the service registered:

 

GET /rcf/description

 

This request will be sent when you set up a remote connector in the Catalog configuration, it’s the first request that goes out. If you’re familiar with SOAP web services, then this is the equivalent of a WSDL: it describes the service, lists what is on offer, what it expects and what it will send back in return. Catalog will use this information to build the service. As with the WSDL, the format is specific and you need to make sure you follow the format exactly.

 

GET /rcf/health

 

This is the second call that goes out when registering the server, it validates the server. It should respond with a simple OK.

 

Those are all the calls we need to get everything registered. So before we go any further let’s get these calls defined. I’m using the Spring framework for the web server. It’s easy enough to spin up and it offers the flexibility I am looking for. I am using Maven as my build tool-of-choice, but just to clarify, there are no requirements here, if you want to use something else, you can. My interface communicates via JSON and to keep it simple and readable I decided to use the org.json library, there are of course different options.

 

If you decide to follow me, download/install Maven from here and set up an empty project with the appropriate Spring references (see below for references). Then run these commands to build and start everything:

 

mvn clean package
java -jar target/gs-rest-service-0.1.0.jar 

 

This starts a web server which I can access via http://myserver:8080/

 

Here are the files I am using:

  • src\main\java\rcf\RCFController.java: main controller, contains request definitions
  • src\main\java\rcf\Application.java: Boot application, used by Spring to start application

 

In Spring HTTP requests are handled by a controller identified by the @RestController annotation. My controller handles the various requests for the RCF web application. Let’s start with the simplest call, /rcf/health:

 

@RequestMapping(value = "/rcf/health", method = RequestMethod.GET)
@ResponseBody
public String getHealth() {
  return "OK";
}

 

I specified that I accept a GET request, I define the URL and I set the response. In our case a simple ‘OK’. That’s enough for this to work.

Let’s turn our attention to /rcf/description. This is an important call, here’s the overview of what we need:

 

{
  "connectors": [
    {
      "name": "Machine Connectivity",
      "version": "0.1",
      "type": "com.example.jb.connectivity",
      "path": "jbconnectivity",
      "capabilities": [],
      "activeConnectionInstances": [],
      "actions": [
        "name": "pingMachine",
        "displayName": "pingMachine",
          "path": "pingMachine",
          "inputs": [
            {
              "name": "machineName",
              "type": "String",
              "required": true
            }
          ],
          "outputs": [
            {
              "name": "Result",
              "type": "String"
            }
          ],
      ]
    }
  ]
}

 

We start with an element called connectors which is an array of the different connectors. Each connector translates to a category in the workflow palette.

 

There are a few properties you need to set, notice the path which you’ll need to use later during run-time. Capabilities is a list of tags describing what the API offers, we’ll look into this later. ActiveConnectionInstances is a list of the available instances like Dev and Prod, this is used in case you use different environments. Next, we've got the actions, this is an array so each connector can have more than one action. This part is fairly self-explanatory: there's the name and you've got the inputs and the outputs. Here's what this looks like on the workflow panel:

 

 

Like the health check we need to define the request as part of the controller. Since we’re dealing with json code I am using org.json. Here’s the code:

 

@RequestMapping(value="/rcf/descriptor", method = RequestMethod.GET)
  public String descriptor() {

  JSONObject jsonDescription = new JSONObject();
  JSONArray jsonArrConnectors = new JSONArray();

  JSONObject jsonConnectionInstance = new JSONObject();
    jsonConnectionInstance.put("id", "jbconnectivity-1");
    jsonConnectionInstance.put("name", "Production");
  JSONArray jsonArrConnectionInstance = new JSONArray();
    jsonArrConnectionInstance.put(jsonConnectionInstance);

  JSONArray jsonArrCapabilities = new JSONArray();
    jsonArrCapabilities.put("com.bmc.dsm.catalog:datasetProvider");

  JSONObject jsonAction = new JSONObject();
    jsonAction.put("name", "pingMachine3");
    jsonAction.put("displayName", "pingMachine3");
    jsonAction.put("path", "pingMachine3");
  JSONArray jsonArrAction = new JSONArray();
  jsonArrAction.put(jsonAction);

  JSONObject jsonActionInput = new JSONObject();
    jsonActionInput.put("name", "machineName");
    jsonActionInput.put("type", "String");
    jsonActionInput.put("required", true);
  JSONArray jsonArrActionInput = new JSONArray();
    jsonArrActionInput.put(jsonActionInput);
  JSONObject jsonActionOutput = new JSONObject();
    jsonActionOutput.put("name", "Result");
    jsonActionOutput.put("type", "String");
  JSONArray jsonArrActionOutput = new JSONArray();
    jsonArrActionOutput.put(jsonActionOutput);

  jsonAction.put("inputs", jsonArrActionInput);
  jsonAction.put("outputs", jsonArrActionOutput);

  jsonAction.put("com.bmc.dsm.catalog", JSONObject.NULL);

  JSONObject jsonIndividualConnector = new JSONObject();
    jsonIndividualConnector.put("name", "Machine Connectivity 3");
    jsonIndividualConnector.put("version", "0.1");
    jsonIndividualConnector.put("type", "com.example.jb.connectivity");
    jsonIndividualConnector.put("path", "jbconnectivity");
    jsonIndividualConnector.put("capabilities", jsonArrCapabilities);
    jsonIndividualConnector.put("activeConnectionInstances", jsonArrConnectionInstance);
    jsonIndividualConnector.put("actions", jsonArrAction);
    
  jsonArrConnectors.put(jsonIndividualConnector);
  jsonDescription.put("connectors", jsonArrConnectors);

  return jsonDescription.toString();
}

 

I’m hardcoding a lot of the values, that’s a deliberate choice to make it readable. In the next blog post we’ll add the connector logic. For now, let’s have a look at some of the details of the API:

 

If we access the URL via /rfc/description, this is the JSON code I get back:

 

{
  "connectors": [
    {
      "name": "Machine Connectivity",
      "version": "0.1",
      "type": "com.bmc.example.jbconnectivity",
      "path": "jbconnectivity",
      "capabilities": [
        "com.bmc.dsm.catalog:datasetProvider"
      ],
      "activeConnectionInstances": [
        {
          "id": "jbconnectivity-1",
          "name": "Production"
        }
      ],
      "actions": [
        {
          "name": "pingMachine",
          "displayName": "pingMachine",
          "path": "pingMachine",
          "inputs": [
            {
              "name": "machineName",
              "type": "String",
              "required": true
            }
          ],
          "outputs": [
            {
              "name": "Result",
              "type": "String"
            }
          ],
          "com.bmc.dsm.catalog": null
        }
      ]
    }
  ]
}

 

That’s enough for Catalog to identify the connector and add it to the workflow. Obviously, it won’t do anything as we haven’t defined any requests for the actions yet, but let’s add it anyway to see what it does:

The name is just for you to identify the server, notice that the URL uses the root. The username and password are used in case of Basic HTTP authentication. If you’re not using them, just enter some dummy values. If all goes well, the actions are added to the palette and I can use it in my workflow. You might have noticed the field Connection Instance Id which is a required field added automatically. This has to have the ID of the active connection instance (not the path) as defined in the descriptor, it needs to be an exact match, else the requests will be not be sent. In my example it’s jbconnectivity-1.

 

That takes care of the design, Catalog can read everything and we can start building our workflow.

 

 

But we’re not there yet, we haven’t anything defined that’s happening at run-time. When Catalog processes the workflow it executes the actions we defined, this results in Catalog sending out requests to our API and we need make sure the API responds appropriately. Here are the calls:

 

POST /{connector_path}/com.bmc.dsm.catalog:checkHealth

 

This is called periodically on each connection to verify its availability. The server is supposed to run a check to see if everything is okay and reports back to Catalog. An Administrator can trigger the check as well.

 

POST /{connector_path}/${action_path}

 

If the activity is executed, this call will go out. The action_path matches the path you defined in the description JSON for the respective action.

 

Let's look at this in more detail. checkHealth is a POST request so there’s a HTTP Body with the payload:

 

POST /jbconnectivity/com.bmc.dsm.catalog:checkHealth 

{  
  "connectionInstanceId": "jbconnectivity-1",  
  "request": {}  
}  

 

Notice that this isn't part of /rcf anymore. The server is supposed to check the connectionInstanceId (you defined this in description) and verify if everything is okay. Always respond with HTTP200 and with the following JSON:

 

{
  "connectionInstanceId": "jbconnectivity-1",
  "response": {
    "status": "CONNECTION_SUCCESS", //CONNECTION_FAILURE if there’s a problem.
    "message": null
  }
}

 

Here’s how I coded this in the controller. To keep it simple I’m returning always CONNECTION_SUCCESS. We’ll work this out in more detail later.

 

@RequestMapping(value = "/jbconnectivity/com.bmc.dsm.catalog:checkHealth", method = RequestMethod.POST)
@ResponseBody
public String checkHealth() {

  JSONObject jsonResponse = new JSONObject();
  jsonResponse.put("status", "CONNECTION_SUCCESS");
  jsonResponse.put("message", JSONObject.NULL);

  JSONObject jsonHealth = new JSONObject();
  jsonHealth.put("connectionInstanceId", "DEV");
  jsonHealth.put("response", jsonResponse);

  return jsonHealth.toString();
}

 

Which leaves us with the connector actions. This is what my Ping action request looks like. This will be generated by Catalog:

 

POST /jbconnectivity/pingMachine

{
  "inputs": {
    "machineName": "clm-aus-12345"
  },
  "connectionInstanceId": "jbconnectivity-1"
}

 

Notice again that there's no /rcf prefix. Catalog bases the values on the values of the input fields. What I need to do is respond with the following JSON:

 

{
  "outputs": {
    "result": "OK"
  }
}

 

The exact format depends on what you defined in descriptor. I just have one field defined here, a field of type String called result.

 

Here’s the code in the controller. Again, the hardcoded values are purely for illustrative purpose. We’ll make this more dynamic in the next article.

 

@RequestMapping(value = "/jbconnectivity/pingMachine", method = RequestMethod.POST)
@ResponseBody
public String checkPing() {

  JSONObject jsonInputs = new JSONObject();
  jsonInputs.put("result", "OK");

  JSONObject jsonPing = new JSONObject();
  jsonPing.put("outputs", jsonInputs);

  return jsonPing.toString();
}

 

That’s all you need to get this working. My examples are all fairly straightforward but I hope you appreciate the flexibly and more importantly the possibilities the connector offers. It can be as simple as a TCP ping and as complicated as the front for a SOAP integration with a custom payroll system. The principles remain the same.

 

What would you do with Remote Server Integration? It’s very versatile, if you define the API correctly you can get it to execute your Java code. It doesn’t necessarily have to be a connection to an external system, it could also be an extension of the functionality. All you need to define are inputs and outputs.

 

The API we’ve written so far is basic and mostly contains hardcoded values, we’d needs to build the logic to get it to do anything. Let’s continue with the example we’ve been using so far: a network ping to determine if machines are alive or not. I’ve used this example before for an Innovation Suite action, let’s check how this would work for a Remote Server integration. But we need to leave this for the next article.

 

I am interested in your feedback. What do you think of the integration possibilities? Would you use this, does this article help you on your way? Maybe you have different or better use cases. I’d love to hear from you, leave a comment below.

 

Best Wishes,

Justin

 

Further Reading:

Filter Blog

By date:
By tag: