How to customize your SAP Customer Engagement Cent...

former_member363931 · ‎01-15-2019

Create your first custom work area view

SAP Customer Engagement Center is SAP's solution for enabling your service teams to deliver consistent, contextual, and relevant experiences regardless of channel or device. This is achieved through three main pillars. First, a unified agent experience with contact channels, customer information, and ticketing tools. Second, by providing consistent, high-quality customer service via telephone, chat, video chat in the same interface, using integrated communication channels, competency-based routing, and queue management. And last but not least with an integration into different systems e.g. SAP backend systems.

In this post we take a look at your possibilities to create your own workarea views and integrations to other systems. You will create a simple custom workarea view. There is no need to be familiar with the solution to complete the steps presented in this post. Please keep in mind that this is only a very simple example to illustrate the integration. There is no further discussion of security, internationalization or similar issues. If you are interested, we can examine this in more detail in another article.

What you will learn

You'll learn how to:

Set up the development environment for the Customer Engagement Center

Structure a basic workarea view

Create a custom workarea view that integrates natively into the Customer Engagement Center

Configure Customer Engagement Center to include your own functionality.

Get data from a SAP backend system maintained as a destination via an OData Service

Use local development for a quicker development cycle

Deploy your application to your SAP Cloud Platform Cloud Foundry Space

What you'll build

The aim is to create an easily understandable example of the extension of the Customer Engagement Center. You will implement a simple workarea view which is the first step in making your user interface accessible through the Customer Engagement Center. In the custom view, it is possible to retrieve the business partner data from the backend system by entering the business partner ID. This can be done via either an OData service or JSON-RPC. In this first example, we will only take a look at the OData variant.

The picture shows what you will have created at completion of this post.

Set up your Customer Engagement Center development environment

You'll need the following software to complete this guide:

The official command line client for Cloud Foundry with the Multi-Target Application Cloud Foundry CLI Plugin. For further information you may also visit SAP Development Tools.

The Multi-Target Application Archive Builder.

A software for calling REST-APIs, e.g. Postman.

An editor to code. This post assumes Visual Studio Code, but you can use your favorite editor.

Software to locally host your coding. This post assumes you are using the Visual Studio Code extension Live Server.

You will also need a Cloud Platform Cloud Foundry account with sufficient free resources and a subscription to the Customer Engagement Center. The Cloud Connector must also be set up and connected to the backend system.

At this point I assume that the installation and setup of the software has already been completed. The software is not specific to the Customer Engagement Center, but is generally used for working in the SAP Cloud Platform Cloud Foundry environment. Please leave a comment if you encounter any difficulties. In that case I will expand this section.

Create the project structure

First create a folder for your project. I name my folder Custom Workarea View Guide.

The structure will be similar to:

In the folder Custom Workarea View Guide create a mta.yaml file and paste this code into it:

ID: com.cec_customer.isu_business_partner

_schema-version: '2.1'

description: Extension of the Customer Engagement Center with a custom workarea view

version: 0.0.1



modules:

 - name: com.cec_customer.isu_business_partner.ui

   type: nodejs

   path: ui_module

   parameters:

     memory: "256M"

     disk-quota: "256M"

     host: ${org}-${space}-.isu_business_partner-ui

Below this folder create a folder named ui_module.

In that folder create a package.json file and paste this code into it:

{

	"name": "com.cec_customer.isu_business_partner.ui",

	"version": "0.0.1",

	"license": "UNLICENSED",

	"dependencies": {

		"cors": "^2.8.4",

		"express": "^4.16.4"

	},

	"engines": {

		"node": ">= 6.11.0"

	}

}

Also in the folder ui_module create a server.js file and paste this code into it:

const express = require('express');

const app = express();

const port = process.env.PORT || 3001;



var cors = require('cors');

app.use(cors());



app.use(express.static('public'));

app.listen(port, () => console.log(`Server listens on port ${port} - Service URL: http://localhost:${port}/`));

Create the custom Workarea View

In this step, you'll start creating the view and the corresponding controller.

After that your folder structure will look similar:

Below the folder ui_module create another folder named public. Below the folder public create a folder view with a file named SearchBusinessPartnerData.view.xml in it.

Paste the following coding into that file:

<?xml version="1.0" encoding="UTF-8"?>

<mvc:View xmlns:mvc="sap.ui.core.mvc" 

	xmlns="sap.m" 

	xmlns:f="sap.ui.layout.form" controllerName="com.cec_customer.isu_business_partner.ui.controller.SearchBusinessPartnerData">



	<Text text="This is where business partner data is retrieved via OData"/>



	<f:SimpleForm id="AccountOverview" editable="true" layout="ResponsiveGridLayout">



		<f:content>

			<Label text="Business Partner ID" labelFor="input-AccountID" design="Bold"/>

			<Input id="input-AccountID" required="true" value="{/AccountID}"/>

			<Label text="First name" labelFor="input-FirstName"/>

			<Input id="input-FirstName" editable="false" value="{/FirstName}"/>

			<Label text="Last name" labelFor="input-LastName"/>

			<Input id="input-LastName" editable="false" value="{/LastName}"/>

		</f:content>



	</f:SimpleForm>



	<Button id="btnOnSubmit" type="Emphasized" text="Submit" press="onSubmit" enabled="true"/>



</mvc:View>

Below the folder public create another folder named controller with a file named SearchBusinessPartnerData.controller.js in it.

Paste the following coding into that file:

sap.ui.define([

	"sap/ui/core/mvc/Controller",

	"com/sap/ec/engagementcontext/ui/customcontrols/WorkareaViewController"

], function (Controller, oWorkareaViewController) {

	"use strict";



	return oWorkareaViewController.extend("com.cec_customer.isu_business_partner.ui.controller.SearchBusinessPartnerData", {



		onInit: function () {

			Object

				.getPrototypeOf(com.cec_customer.isu_business_partner.ui.controller.SearchBusinessPartnerData.prototype).initWorkareaView

				.call(this, {

					"beforeCancelContext": false,

					"beforeCloseContext": false

				});



			// view initialization parameters & global object references are accessible with controller variable oViewData

			this.getBCD().subscribe(com.sap.ec.engagementcontext.ui.bcd.Events.AccountConfirmed, this.onAccountConfirmed, this);

			this.getBCD().subscribe(com.sap.ec.engagementcontext.ui.bcd.Events.AccountUnconfirmed, this.onAccountUnconfirmed, this);



		},



		onAccountConfirmed: function () {},



		onAccountUnconfirmed: function () {},





		 // Called when the Controller is destroyed. Use this one to free resources and finalize activities.

		onExit: function () {

			this.getBCD().unsubscribe(com.sap.ec.engagementcontext.ui.bcd.Events.AccountConfirmed, this.onAccountConfirmed, this);

			this.getBCD().unsubscribe(com.sap.ec.engagementcontext.ui.bcd.Events.AccountUnconfirmed, this.onAccountUnconfirmed, this);

			Object.getPrototypeOf(com.cec_customer.isu_business_partner.ui.controller.SearchBusinessPartnerData.prototype).onExit.call(this);

		},



		// return business document type

		getBusinessDocumentType: function () {

			return this.getView().getViewData().oData.businessDocumentType;

		},



		// return business document id

		getBusinessDocumentId: function () {

			return this.getView().getViewData().oData.businessDocumentId;

		},



		/*

		 * Mandatory function for the Engagement Context

		 *

		 * If you specify the opened View then the Engagement

		 * Context need to know some ID of this view. E.g. if this

		 * is a creation view of a document with the ID xy, then the

		 * Object ID is xy. The title is the title of the opened

		 * view and the tooltip is used for some feedback messages

		 * that references on this view.

		 */

		getWorkareaViewTexts: function () {

			return {

				"title": "IS-U Business Partner",

				"tooltip": "IS-U Business Partner"

			};

		},



	});

});

Now we have a basic view with an associated controller. Yet we have to integrate it into the Customer Engagement Center.

Add the local version of your workarea view to the Customer Engagement Center

To have a faster development cycle and not deploy to the SAP Cloud Platform after every change, I recommend you implement the local version of your code until you're done with your development.

To run my developments locally, I will use an extension for Visual Studio code called Live Server. You can operate your local server however you like.

Currently you'll need a program like Postman to complete all necessary configurations. This may change with a future update.

In order to be able to make any changes you'll need to acquire a token. The URL for tenants in europe currently is https://sap-cec-ec-prod-cecenter-fiorilaunchpad.cfapps.eu10.hana.ondemand.com/v1/security/access-tok.... You may request the URL applicable for your tenant via a support message.

You'll need to use basic authentication with a username and password. This user needs to have the permissions to do the configuration. In the body of your post request add your tenant id.

If you don't know your tenant id just take a look at the first part of your engagement center lauchpad url: https://yourtenantname.servicecloud.cfapps.eu10.hana.ondemand.com/sites#EngagementContext-Display

{"tenantId": "yourtenantname"}

During the next configuration steps you'll choose authorization type Bearer Token and use the token you just received back from the post request.

During the following configuration you'll need to add:

Module
The Module entity contains attributes that are relevant for loading the module, which is needed for proper display of the views.
e.g. URL: https://sap-cec-ec-prod-engagement-context-odata.cfapps.eu10.hana.ondemand.com/customizingengagement...

{

	"id": "Z_MODULE_ISU_BUSINESS_PARTNER",

	"isActive": 1,

	"description": "Module for a basic example of the integration of a custom Workarea View",

	"baseUrl": "http://127.0.0.1:5500/Custom%20Workarea%20View%20Guide/ui_module/public/",

	"path": "com.cec_customer.isu_business_partner.ui",

	"isDefault": 0,

    "namespace": "CUST",	

	"release": "0.0.1"

}

WorkareaView
The WorkAreaView is displayed in the work area of the Agent Desktop.
e.g. URL: https://sap-cec-ec-prod-engagement-context-odata.cfapps.eu10.hana.ondemand.com/customizingengagement...

{

"id": "Z_WAV_ISU_BUSINESS_PARTNER_SEARCH",

"isActive": 1,

"description": "Example of a custom Workarea View",

"path": "com.cec_customer.isu_business_partner.ui.view.SearchBusinessPartnerData",

"icon": "sap-icon://hint",

"isClosable": 1,

"isOneInstanceOnly": 0,

"namespace": "CUST",

"release": "1.0.0"

}

ActionareaView
The ActionAreaView is displayed in the Action Area of the Agent Desktop.
e.g. URL: https://sap-cec-ec-prod-engagement-context-odata.cfapps.eu10.hana.ondemand.com/customizingengagement...

{

"id": "Z_AAV_ISU_BUSINESS_PARTNER",

"isActive": 1,

"profilesLink.viewId": "Z_AAV_ISU_BUSINESS_PARTNER",

"description": "AAV for basic guide",

"viewPath": "com.sap.ec.engagementcontext.ui.view.actionarea.tiles.AAV",

"displayOrder": 5,

"isCreateLinkActive": 0,

"isSearchLinkActive": 1,

"isPopoverLinkActive": 0,

"createLinkTextId": "",

"searchLinkTextId": "Search for IS-U BP Data",

"popoverLinkTextId": "",

"needCreateLinkConfirmation": 0,

"namespace": "CUST",

"release": "1.0.0"

}

ProfileActionAreaViewLink
The ProfileActionAreaViewLink is used to link a profile to one or multiple views of type
ActionAreaView.
e.g. URL: https://sap-cec-ec-prod-engagement-context-odata.cfapps.eu10.hana.ondemand.com/customizingengagement...
```
{

"profileId": "SAP_PROFILEAAVLINK_MAIN",

"viewId": "Z_AAV_ISU_BUSINESS_PARTNER"

}
```

BusinessDocumentType
A BusinessDocumentType (BDT) represents an object in the Agent Desktop. For example, ServiceTicket, the Interaction Log, Business Partner, and so on.
e.g. URL: https://sap-cec-ec-prod-engagement-context-odata.cfapps.eu10.hana.ondemand.com/customizingengagement...

{

"id": "Z_BDT_ISU_BUSINESS_PARTNER",

"category": "",

"description": "CEC BDT for basic guide",

"module.id": "Z_MODULE_ISU_BUSINESS_PARTNER",

"actionAreaView.id": "Z_AAV_ISU_BUSINESS_PARTNER",

"workareaViewDisplay.id": "",

"workareaViewSearch.id": "Z_WAV_ISU_BUSINESS_PARTNER_SEARCH",

"workareaViewEdit.id": "",

"workareaViewCreate.id": "",

"isActive": 1,

"isInteractionLogRelevant": 0,

"recentItemsUrl": "",

"recentItemsUpdateDelay": 0,

"recentItemsDisplayOrder": 0,

"itemHandlerClass": "com.sap.ec.engagementcontext.ui.bcd.bcditem.AutoAAVBCDItem",

"textIdSingular": "ISU Business Partner",

"textIdPlural": "ISU Business Partners",

"isLeadingBDT": 0,

"isCommPopoverOpener": 0,

"viewStartupParameters": "",

"namespace": "CUST",

"release": "1.0.0"

}

Now our basic example running locally is added to our Customer Engagement Center. After refreshing the Customer Engagement Center and opening the Agent-Desktop we should be able to see it.

So we are able to take a look at our workarea view.

Yet we have not yet implemented to functionality to retrieve the data.

Add more functionality to your controller

First we need to make sure that our service is available through a destination on our Cloud Platform Account:

In this example the destination is directly pointing to our OData Service.

We have to handle the onSubmit function, instantiate the model and eventually react to errors.

Our controller could look like this:

sap.ui.define([

	"sap/ui/core/mvc/Controller",

	"com/sap/ec/engagementcontext/ui/customcontrols/WorkareaViewController"

], function (Controller, oWorkareaViewController) {

	"use strict";



	return oWorkareaViewController.extend("com.cec_customer.isu_business_partner.ui.controller.SearchBusinessPartnerData", {



		onInit: function () {

			Object

				.getPrototypeOf(com.cec_customer.isu_business_partner.ui.controller.SearchBusinessPartnerData.prototype).initWorkareaView

				.call(this, {

					"beforeCancelContext": false,

					"beforeCloseContext": false

				});



			// view initialization parameters & global object references are accessible with controller variable oViewData

			this.getBCD().subscribe(com.sap.ec.engagementcontext.ui.bcd.Events.AccountConfirmed, this.onAccountConfirmed, this);

			this.getBCD().subscribe(com.sap.ec.engagementcontext.ui.bcd.Events.AccountUnconfirmed, this.onAccountUnconfirmed, this);



			var oModel = new sap.ui.model.json.JSONModel();

			this.getView().setModel(oModel);



		},



		onAccountConfirmed: function () {},



		onAccountUnconfirmed: function () {},



		onExit: function () {

			this.getBCD().unsubscribe(com.sap.ec.engagementcontext.ui.bcd.Events.AccountConfirmed, this.onAccountConfirmed, this);

			this.getBCD().unsubscribe(com.sap.ec.engagementcontext.ui.bcd.Events.AccountUnconfirmed, this.onAccountUnconfirmed, this);

			Object.getPrototypeOf(com.cec_customer.isu_business_partner.ui.controller.SearchBusinessPartnerData.prototype).onExit.call(this);

		},



		getBusinessDocumentType: function () {

			return this.getView().getViewData().oData.businessDocumentType;

		},



		getBusinessDocumentId: function () {

			return this.getView().getViewData().oData.businessDocumentId;

		},



		getWorkareaViewTexts: function () {

			return {

				"title": "IS-U Business Partner",

				"tooltip": "IS-U Business Partner"

			};

		},



// /scc/ is the external service proxy of the customer engagement center

// we may use our destinations via /scc/destinationname/

		onSubmit: function () {

			var oDataSrvURL = "./scc/utilities_odata/Accounts('" + this.getView().getModel().getProperty("/AccountID") + "')?$format=json";



			// Get the data for the entered bp id

			$.ajax(oDataSrvURL, {

				success: $.proxy(function (data, textStatus, req) {

					this.getView().getModel().setData(data.d);



				}, this),

				error: $.proxy(function () {

					this.logMessage("OData request failed", "The OData request failed. Check what you have done ;)")

				}, this),

			});

		},



		logMessage: function (sErrorMessage, sErrorMessageLong) {



			this.raiseErrorMessage({

				"messageShort": sErrorMessage,

				"messageLong": sErrorMessageLong,

				"isGlobalMessage": false

			});

			this.updateMessageArea();

		},



	});

});

With the logic now added, the data for the Business Partner ID entered should be loaded and displayed after a click on Submit. If the request returns an error, we should receive a message in the message area.

Now that we know that the view is working as intended, we should think about deploying it.

Deployment on the Cloud Platform Cloud Foundry environment

After the development is finished it makes sense to switch from a local environment to e.g. the Cloud Platform.

In order to shift from your local development to a deployment on your cloud platform account you'll now need the mta_archive_builder. Uses the latest available version, which is currently 1.1.7..

I've put the .jar file into the same folder as my coding, therefor in Visual Studio Code I can simply right click my Custom Workarea View Guide folder and select Open in Terminal. In the terminal use the command:

java -jar mta_archive_builder-1.1.7.jar --build-target CF build

An .mtar file should be created now. In my case the name of that file is Custom Workarea View

Guide.mtar as I didn't specify any other name.With the Cloud Foundry CLI installed, I can log in with the following command in terminal:

cf login

You will need to enter your API endpoint and your email and password. After authentication, select the organization you want to upload it to and the appropriate space.

Now you can use the command to deploy your file:

cf deploy "Custom Workarea View Guide.mtar"

Once your application is started and available in your cloud platform cloud foundry environment, you should be able to see it in your space:

Now you should create another destination that refers to the URL of your application. The URL can be found under Application Route after you have clicked on the application. This is not necessary, but could make future handling of topics such as authentication easier.

Let's continue to the last step for this blog.

Updating the Customer Engagement Center Configuration

At the moment the Customer Engagement Center still obtains our view from our local server. The information about the base url is stored in the module. We have to adapt our module accordingly.

For this we open Postman again. Now we have to update the previously created module. So we don't use POST anymore, but PUT. In my case the ID of my module was Z_MODULE_ISU_BUSINESS_PARTNER. The URL is accordingly: https://sap-cec-ec-prod-engagement-context-odata.cfapps.eu10.hana.ondemand.com/customizingengagement...').

The module should now get the data from the destination just created. For this we change the baseUrl to the external service proxy of the Customer Engagement Center, followed by our destination.

For instance, this might look like the following:

{

	"id": "Z_MODULE_ISU_BUSINESS_PARTNER",

	"isActive": 1,

	"description": "Module for a basic example of the integration of a custom Workarea View",

	"baseUrl": "./scc/isu_business_partner_ui/",

	"path": "com.cec_customer.isu_business_partner.ui",

	"isDefault": 0,

    "namespace": "CUST",	

	"release": "0.0.1"

}

Next steps

Congratulations!

Your application is now uploaded to and consumed from Cloud Platform Cloud Foundry. You have completed this short example. If you'ld like to know more about this or if you've got ideas for other examples please reach out to me.

Next Steps

At this point we have now shown the minimal integration. We haven't shared much data between the Customer Engagement Center and our View yet. Next steps would be, for example:

Internationalization

Increasing security through authentication or authorization

Utilization of data from the Customer Engagement Center, e.g. the identified customer, to preset values

Saving the activity in an interaction log

Navigation between, for example, a work area view for a search and for the display.

Learn more

Learn more about the Customer Engagement Center:

SAP Customer Engagement Center Video Library

Administration Guide for SAP Customer Engagement Center

Configuring Agent Desktop Framework in SAP Customer Engagement Center

If you have any questions, suggestions or problems, please reach out.

Best regards,

Tobias

P.s. A German version is available in a guest article here.