Exploring UI Integration Cards

UI Integration Cards allow you to consume business content from SAP and third-party solutions. They are stored and managed in the so-called host environment – SAP Build Work Zone or SAP SuccessFactors Work Zone in the context of this learning course.

The concept of UI Integration Cards belongs to the SAPUI5 framework and follows SAP Fiori design language.

From a technical point of view, UI Integration Cards are represented as a set of client-side files (JavaScript, CSS, XML, JSON, and so on). While UI Integration Cards are stored and rendered in the context of SAP Build Work Zone, they are executed on the client-side – web browsers like Microsoft Edge, Google Chrome, or Firefox.

Note

UI Integration Cards are not unique to SAP Build Work Zone. They belong to the SAPUI5 framework. SAP Build Work Zone provides the necessary infrastructure to store UI Integration Cards, configure and place them in various home pages and workspaces in the Digital Workplace Service (DWS) component.

The development of UI Integration Cards starts from SAP Business Application Studio. SAP Business Application Studio is the recommended integrated development environment (IDE) for UI Integration Cards because it simplifies the development experience drastically:

It is not required to have SAP Business Application Studio in the same subaccount with SAP Build Work Zone or SAP SuccessFactors Work Zone. The design and development can be done in any SAP Business Application Studio where a space with the extension Development Tools for SAP Build Work Zone is created.

It is not necessary to have any prior programming experience to start with the design and development of UI Integration Cards, thanks to a low-code development paradigm. SAP Business Application Studio allows you to create UI Integration Cards by following configuration steps in the Project Wizard: when these are steps completed, SAP Business Application Studio creates two files – manifest.json and Configuration.js. The first file is the starting point for the UI Integration Card: it defines the name and description of the card, tags, how content should be displayed, various parameters, and so on. The second file helps to define how the configuration parameters of the UI Integration Card should be rendered, for example, dropdown list with pre-defined set of values, toggle, and so on. Since there are different types of UI Integration Cards supported, typically 80% of requirements for UI Integration Cards can be covered by the low-code development paradigm by working with manifest.json and Configuration.js files.

Besides that, experienced developers can benefit from pro-code development for UI Integration Cards. Since UI Integration Cards are part of SAPUI5 framework, you can implement advanced business logic by utilizing Component.js, Controller.js, View.xml, and other familiar SAPUI5 components.

When a UI Integration Card is designed and developed with SAP Business Application Studio and deployed to SAP Build Work Zone or SAP SuccessFactors Work Zone, it can be managed from the Administration Console and used in home pages, workspaces, and chatbots.

Note

UI Integration Cards cannot be used in the launchpad component of SAP Build Work Zone (that is, they are unavailable in the menu Applications).

The next sections will explain the design, development, deployment, and administration of UI Integration Cards in more detail.

The design and development of UI Integration Cards for SAP Build Work Zone starts with answers to the following fundamental questions:

• What kind of information is required to show?
• Is it static or dynamic information?
• Where is this information stored today: SAP or third-party systems?
• Does the SAP or third-party system provide the necessary API to work with information?
• Is it necessary to have identity propagation from the UI Integration Card (executed in context of SAP Build Work Zone) back to the SAP or third-party system?
• How to display information to the user (table view, list view, form, and so on)?

These questions help to understand the complexity of the target architecture for UI Integration Cards. For instance, there might be a need to introduce SAP API Management or SAP Cloud Integration for integration purposes: in this case, UI Integration Cards will communicate with the SAP or third-party system through these middleware solutions.

When the questions are answered, it's time to prepare the cloud development environment by setting up a Dev Space in SAP Business Application Studio.

But let's figure out where to find SAP Business Application Studio first. Typically, SAP Business Application Studio is enabled in the SAP BTP subaccount within the onboarding procedure for SAP Build Work Zone or SAP SuccessFactors Work Zone. Then, it's just a matter of providing access to the required persons. On the other hand, it's not mandatory to have SAP Business Application Studio in the same subaccount with SAP Build Work Zone. UI Integration Cards and other SAP Build Work Zone development artifacts can be designed and developed in SAP Business Application Studio activated in any subaccount (even outside of your Global Account)!

Coming back to the Dev Space, it is important to enable it with an additional SAP extension called Development Tools for SAP Build Work Zone. It brings features and functions to SAP Business Application Studio, allowing it to work with SAP Build Work Zone specific artifacts:

• Create UI Integration Cards, Content Packages, and Workspace Template from a template and using a wizard-based method.
• Run real-time preview of UI Integration Cards without leaving SAP Business Application Studio.
• Generate deployable archive as well as deploy it to SAP Build Work Zone right from SAP Business Application Studio.

Note

The same Dev Space can be used for multiple development projects of UI Integration Cards: all such projects can be combined in one Dev Space.

When the Dev Space is up and running, it is time to set up the Project.

The Project is nothing special but provides a well-structured directory with the required files for the UI Integration Card. The definition of a UI Integration Card is described in the mandatory file called manifest.json. There are various options to set up a Project in a Dev Space in SAP Business Application Studio:

Let's create a Project from a template. There are two project templates available:

Note

Mobile Transaction Bridge belongs to SAP Mobile Services. Typically, it is enabled outside of the SAP Build Work Zone implementation project. See more details about Mobile Transaction Bridge on the SAP Help Portal.

Depending on the selected project template, there will be a set of configuration steps with mandatory and optional parameters. This is the power of the low-code/no-code paradigm, where UI Integration Cards can be created with no programming skills!

Let's move forward with the project template UI Integration Card. The next step requires you to provide Project Details (Project Name, Namespace, Card Sample, and so on).

While most of the parameters are straightforward, it makes sense to stop for a minute and highlight the following ones:

The easiest way to get your first design and development experience of UI Integration Cards is to choose Work Zone Custom Feed as the Card Sample (as highlighted in the figure). In this case, the wizard generates a Project that uses the pre-defined SAP BTP destination JAM (pointing to the Digital Workplace Service component and its OData services).

When the project is generated, it will contain a set of standard subdirectories and files regardless of the type of card.

Note

While the project structure and development process is pretty straightforward, UI Integration Cards are still considered as apps. Therefore, it is recommended to use all software development best practices. For instance, it makes sense to set up and store source code in a git repository.

The file manifest.json defines the architecture of the UI Integration Card: name, description, keywords, user parameters, use of SAP BTP destinations, end points to retrieve business data from SAP or third-party systems, look and feel, and more. It also connects the UI Integration Card with other development artifacts, for example, JavaScript files (configuration design time, controller, and so on), images, and so on.

The file manifest.json for UI Integration Cards and SAP Build Work Zone development projects provides the following additional items in the context menu:

Note

The options to deploy UI Integration Cards to SAP Build Work Zone are covered in the next section.

The preview of the UI Integration Card in SAP Business Application Studio is very useful because it allows you to see the result without deploying the UI Integration Card to SAP Build Work Zone or running any local infrastructure:

Note

While UI Integration Cards can be previewed in SAP Business Application Studio, it is still recommended to have the proper development and/or quality assurance environment (represented as SAP BTP subaccounts) with SAP Build Work Zone where custom developed UI Integration Cards can be validated following a test management process (for example, regression testing or UAT).

By default, the preview is triggered automatically when changes are made and saved in the file manifest.json. In some cases, this functionality may distract, especially when there is a need to make a lot of changes in the file. Fortunately, the SAP extension Development Tools for SAP Build Work Zone comes with additional settings. The settings are available under the group Uicarddk in the menu Preferences → Open Preferences in SAP Business Application Studio:

Using preferences, both options Auto Preview on Manifest Changed and Auto Preview On Manifest Saved can be switched off for the cases where it is necessary to make a lot of changes in the file manifest.json. These settings do not remove the preview functionality from SAP Business Application Studio – it can be still triggered manually (and when necessary) from the context menu of the file manifest.json.

The preview functionality relies on the subdirectory .card in the root of project directory. It is used to store temporary content, for example, the preview file for SAP Business Application Studio. When this subdirectory is unavailable, SAP Business Application Studio raises the error "This is not a UI Integration Card". It can happen when a UI Integration Card development project is cloned from a remote git repository (typically a lot of files and directories having "." at the beginning are excluded). It can be easily fixed by creating an empty subdirectory .card in the root of the project directory with the UI Integration Card.

UI Integration Cards can work with business information from SAP and third-party systems through SAP BTP destinations. It prevents bad practice of hard coding connection details in UI Integration Cards. From a technical point of view, connections are defined in the file manifest.json of the UI Integration Card.

It is possible to define as many connections as necessary, as shown in the following figure:

The destination must be maintained in the SAP BTP subaccount where SAP Business Application Studio is used (for development purposes) and SAP Build Work Zone is enabled.

Note

Since the connection with SAP and third-party systems goes through the SAP BTP Destination service, the integration architecture patterns are relevant. For instance, the destination can point directly to an SAP or third-party system, or an integration platform like SAP API Management or SAP Cloud Integration.

As outlined in the figure, the connection is made by maintaining the technical name of the SAP BTP destination in the file manifest.json. But when a UI Integration Card is deployed to SAP Build Work Zone, an administrator can choose other SAP BTP destinations in the settings in the Administration Console. This allows you to use different BTP destinations in different environments.

Note that SAP BTP destination in the settings of the UI Integration Card can be changed from the Administration Console of SAP Build Work Zone only. The settings of SAP BTP destinations are not visible when the UI Integration Card is placed to home pages or workspaces by users.

There are two ways that individual UI Integration Cards can be deployed to SAP Build Work Zone:

The deployment of UI Integration Cards to SAP Build Work Zone requires administration permissions. Depending on the landscape for SAP Build Work Zone and software change management processes at the company, citizen developers or professional developers may or may not be able to deploy UI Integration Cards directly to SAP Build Work Zone – this will define the preferred option.

Watch the following video to learn more about the deployment of UI Integration Card.

But how can SAP Business Application Studio find information about this service instance? To do so, it is necessary to maintain the destination in the SAP BTP subaccount where SAP Business Application Studio is used.

In real live scenarios, there are two options:

The details on how to set up the service instance for SAP Build Work Zone and destination are described on the SAP Help Portal. The steps are relevant for both SAP Build Work Zone and SAP SuccessFactors Work Zone.

When everything is configured and ready, the UI Integration Card can be deployed by choosing the respective option in the context menu of the file manifest.json. From a technical point of view, SAP Business Application Studio still generates a deployable archive and then automatically sends (and deploys) it to SAP Build Work Zone using the API.

When the UI Integration Card is deployed to SAP Build Work Zone from SAP Business Application Studio or manually the first time, it is set to an inactive state. This means that the UI Integration Card is unavailable for use in home pages and workspaces. It gives the administrator sufficient time to maintain all necessary mandatory and default parameters before users start placing the UI Integration Card to home pages and workspaces. When everything is maintained, the UI Integration Card can be enabled for wide use.

Note

Keep in mind that if the UI Integration Card is activated, all future versions will be deployed and available as active too. Users will see changes in home pages and workspaces (where the UI Integration Card is added) immediately in this case.

The next big question is how to move and deploy UI Integration Cards to follow-up environments (represented as SAP BTP subaccounts with SAP Build Work Zone).

Note

At the date of course publication, there are no mechanisms to move the artifacts of the Digital Workplace Service (DWS) from one SAP BTP subaccount with SAP Build Work Zone to another one in automated and controlled fashion. It includes artifacts as UI Integration Cards, Content Packages, Workspace Templates, Home Page, and Workspace content.

While there are no mechanisms to move UI Integration Cards from one SAP BTP subaccount with SAP Build Work Zone to other one, it's still important to respect the software change management process: the changes should be documented, tested, and approved for the use in the production environment. It is also important for internal and external audit processes. SAP Solution Manager or SAP Cloud ALM can be considered for these purposes.

When a UI Integration Card is finally developed and deployed to SAP Build Work Zone, Company Administrators can enable the UI Integration Card and maintain settings in the Administration Console. By default, a UI Integration Card is deployed as inactive – this means that it cannot be used across SAP Build Work Zone by end users.

The Company Administrator has the following options to manage a UI Integration Card in SAP Build Work Zone:

UI Integration Cards help to enrich the digital experience without any doubts. They allow us to build bridges by connecting SAP and third-party systems, have more business information at our fingertips, and speed up the decision-making process.

But poorly architected UI Integration Cards can wipe out all of the highlighted benefits and work against people efficiency at the company. Besides that, poorly architected UI Integration Cards may open security gaps in the IT landscape.

While it is easy to design and develop UI Integration Cards, it is still necessary to consider the common best practices and guidelines from the world of SAP BTP and software development.

There are 7 design principles for the design and development of UI Integration Cards: