Custom UI Integration Card Development in SAP Succ...

ronaldlee · ‎10-02-2023

Do you already have an SAP SuccessFactors Work Zone instance but want to create something of your own, beyond the standard UI Integration Cards provided?

Do you wish to add MDF to SuccessFactors and interact with it in Work Zone?

Here is quick tutorial for you to start Custom UI Integration Card development.

Introduction

SAP SuccessFactors Work Zone provides bunch of out-of-box UI Integration Cards such as My Profile and Org Chart, allowing us to easily access SuccessFactors employee data in Work Zone.

However, if you want to develop custom UI integration cards which pull data from SuccessFactors by yourself, this post can be a valuable resource.

Through this post, I will share step by step guide from the beginning on how to develop a custom Work Zone UI Integration Card which consumes the SuccessFactors data via ODATA API.

As a result of this post, you can use the following custom UI Integration Card in Work Zone.

Custom UI Integration Card - My Badge

Prerequisite

Before we begin, there are a few prerequisites

SAP SuccessFactors Work Zone instance and administration console permission

SAP SuccessFactors instance

SAP Business Application Studio

Let's briefly understand the technologies mentioned in the prerequisites:

SAP SuccessFactors Work Zone is a personalized, modern, and intuitive digital workspace solution that consolidates relevant business insights and applications in one place, eliminating a poor user experience.

SAP SuccessFactors is powerful cloud HR software that empowers individuals to maximize their potential at work while strengthening HR's connection across the business.

SAP Business Application Studio is a cloud development tool based on SAP BTP, allowing online application development without separate installations.

SAP SuccessFactors Work Zone

1. Custom UI Integration Card Development

Let's go ahead and develop a UI Integration Card.
As an example, in this article, I will develop UI Integration card to pull employee's Badge data from SuccessFactors.

1.1 Create Dev Space in SAP Business Application Studio

First, let's prepare the necessary environment for development.

Launch SAP Business Application Studio.

Select "Create Dev Space." and enter the following properties
- Dev Space Name: Any name without spaces (e.g., myFirstWorkZoneUICard)
- What kind of application do you want to create?: SAP Fiori
- Additional SAP Extensions: Check "Development Tools for SAP Build Work Zone"

Click "Create Dev Space"

Create Dev Space

It may take some time for the Dev Space to be created.
Once completed, its status will change to "RUNNING." Click on the Dev Space to start your development environment.

1.2 Create UI Integration Card Project in Dev Space

Now, let's create a project for Work Zone UI Integration Card development.

Access to the Dev Space

Select "New Project from Template" (or go to the top-left menu > File > New Project from Template).

Choose "UI Integration Card" and click the "Start" button.

Enter project details and click "Finish."

Create UI Integration Card Project

Once the UI Integration Card project is created, you can browse the project files in the left Explorer area. Right-click on the Manifest.json file and select "UI Integration Card: Preview" to get a preview of the card's appearance.

Preview UI Integration Card

1.3 Craft our own UI Integration Card

To craft Work Zone UI Integration card which pull SuccessFactors Badge data,
replace the manifest.json in the project root with the code below.

{

	"_version": "1.15.0",

	"sap.app": {

		"id": "ns.UIIntegrationCard",

		"type": "card",

		"title": "My Badges",

		"subTitle": "Badges I received",

		"applicationVersion": {

			"version": "1.0.0"

		}

	},

	"sap.ui": {

		"technology": "UI5",

        "deviceTypes": {"desktop": true, "phone": true, "tablet": true},

		"icons": {

			"icon": "sap-icon://badge"

		}

	},

	"sap.card": {

		"type": "List",

		"configuration": {

            "destinations": {

                "SFSFDestination": {

                    "name": "SuccessFactors_API"

                }

            },

            "parameters": {

                "currentLoginBizxUserID": {

					"value": "{context>sap.successfactors/currentUser/id/value}",

					"type": "string",

					"visible": false

				  },

				  "SFCompanyID": {

					"value": "{context>sap.successfactors/currentCompany/id/value}",

					"type": "string",

					"visible": false

				  },

				  "maxItems": {

					"value": 15

				  },

				  "locale": {

					"value": "{{parameters.LOCALE}}",

					"type": "string",

					"visible": false

				  }

            }

        },

		"header": {

			"title": "My Badge",

			"subTitle": "Badges I received",

			"icon": {

				"src": "sap-icon://badge",

				"visible": true

			},

			"status": {

				"text": "Top {{parameters.maxItems}}"

			}

		},

		"content": {

			"data": {

				"request": {

					"url": "{{destinations.SFSFDestination}}/odata/v2/UserBadges",

					"method": "GET",

					"parameters": {

						"$format": "JSON"

					},

					"headers": {

					  "successfactors-employment-id": "{{parameters.currentLoginBizxUserID}}"

					},

					"withCredentials": true				  	

				},

				"path": "/d/results"

			},

			"maxItems": 5,

			"item": {

				"title": "{badgeTitle}",

				"description": "{comment}",

				"icon": {

					"src": "data:image/bmp;base64,{photo}",

					"visible": "{Visible}"

				},

				"info": {

					"value": "{badgeCreatorName}",

					"state": "Information"

				}

			}

		}

	}

}

UI Integration Card creation is now complete!
Before deploying it to Work Zone, let's explore the meaning of the source code.

The "sap.card" property defines the appearance, parameters, data source, and field mapping of the UI Integration Card.

Key properties of "sap.card":

"type" property: Specifies the type of Card. You can find various types of SAP UI Card samples in the UI Integration Card Explorer.
(Badge Card is defined as a List).

"configuration" property: Defines variables that can be configured by the Work Zone administrator. In this example, Destination and maxItems are defined as configurable variables. (We will show how to configure the UI Card in Work Zone later.)

"header" property: Sets the title and subtitle of the Card. You can also define an icon; in this example, it's defined as a Badge icon. You can explore all available icons in SAP Icons.

"content" property: Defines the data to be displayed in the Card.
- "data": Defines the data. Data can be defined as static JSON or dynamically by making API calls. In this case, it's defined to query the SuccessFactors OData V2 API. You can find detailed information about the SuccessFactors OData V2 API on SAP Business Accelerator Hub.
- "item": Maps the fields of the data to the fields of the UI Card. For Badge data, the Badge image comes in the form of a Base64-encoded string.
  You can add the "data:image/bmp;base64," prefix to the response data to convert it back to an image.

2. Deploy Custom UI Integration Card to SAP SuccessFactors Work Zone

Let's deploy the developed Card to Work Zone. There are two deployment options:

The first option is to directly deploy the developed UI Integration Card to SAP SuccessFactors Work Zone. To perform a direct deployment, SAP Business Application Studio and SAP SuccessFactors Work Zone must exist in the same SAP BTP Subaccount.

The second option involves packaging the developed UI Integration Card, downloading it, and then uploading it to SAP SuccessFactors Work Zone for application. This method doesn't require Work Zone and Business Application Studio to be in the same Subaccount.

In this post, we will deploy the Card using the second method.

2.1. Download UI Integration Card Package

Right-click on the "manifest.json" file and select "UI Integration Card: Package."
A ZIP file with the namespace and project name will be generated.

UI Integration Card : Package

Right-click on the generated ZIP file and select "Download" to save the file to your local PC. This file needs to be uploaded to your Work Zone instance.

Download UI Integration Card Package

2.2. Upload UI Integration Card Package in SAP SuccessFactors Work Zone

Access to SAP SuccessFactors Work Zone with administrator permission and follow the steps below to upload the UI Integration Card:

Access the Administration Console menu.

Navigate to UI Integration > Cards menu.

Click the "Upload Card" button.

Select the downloaded Package file and click the "Upload" button.

Once upload is done, you can find your Badge Card on the uploaded cards section.

Enable the card

We now need to enable users to use the Badge card on the page. When you toggle the switch button for the card, the card becomes enabled.

If you click the Configure button, you can change the values for Destination and Max Item as per the settings in the 'manifest.json' file.
(If you followed the SAP SuccessFactors Work Zone Initial Setup process, you can use SuccessFactors_API destination as the default.)

2.3. Add Custom UI Integration Card to Work Zone page

Now, let's try adding the My Badge card to the page.
Follow the steps below after accessing SAP SuccessFactors Work Zone:

Go to the Home menu and click the edit button on the right.

Click the Add Widget button.

Select Cards > My Badge

Click 'Save' to add card to page

My Badge Card on Home page

Once it is completed, employees will be able to check their SuccessFactors Badges every time they access the Work Zone home page, and they will also be able to immediately verify it in the Work Zone whenever they receive a badge from other employees in SuccessFactors.

That's it for today's tutorial!

I hope this post has been of some help to those of you reading it, and if you encounter any stumbling blocks along the way, please leave a comment!