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.

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 comes with Project Wizard, allowing you to prepare the Project Template – define the type of UI Integration Card, choose the destination, and so on.
• It provides a real-time preview of the UI Integration Card without deploying it to SAP Build Work Zone and leaving the development environment.
• When the design and development completed, it allows you to prepare a deployable archive and deploy the UI Integration Card to SAP Build Work Zone right from SAP Business Application Studio.

It is not required to have SAP Business Application Studio in the same subaccount with SAP Build Work Zone, advanced edition, 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 steps are 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, a 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 the 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 workpages, and workspaces.

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 must be shown?
• 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 the information?
• Must there be identity propagation from the UI Integration Card (executed in the context of SAP Build Work Zone) back to the SAP or third-party system?
• How do we display the information to the user (for example, table view, list view, or form)?

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

When the questions are answered, prepare the cloud development environment by setting up a dev space in SAP Business Application Studio.

However, let's work out first where to find SAP Business Application Studio. Typically, SAP Business Application Studio is enabled in the SAP Business Technology Platform (SAP BTP) subaccount in the onboarding procedure for SAP Build Work Zone or SAP SuccessFactors Work Zone. Then, you need only provide access to the required persons. Yet, 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.

Returning to the dev space, it's 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, enabling it to work with SAP Build Work Zone specific artifacts:

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

When the dev space is up and running, it’s time to set up the project.

The project 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 for setting up a Project in a dev space in SAP Business Application Studio:

• The project can be created from scratch using the Start from template option on the home screen. If the home screen is closed, this option can also be triggered from File → New Project from Template.

  This option is the best and is recommended for all new developments of UI Integration Cards.

• There can be cases where a UI Integration Card is already developed and stored in a corporate source code repository, for example, Microsoft Azure DevOps, GitHub, and GitLab. In this case, the source code can be cloned using the Clone from Git option available on the home screen. If the home screen is closed, the git clone operation can also execute from the terminal: Terminal → New Terminal.

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

• UI Integration Card: This enables you to design static and dynamic content from SAP and third-party systems.
• UI Integration Card for Mobile Transaction Bridge: This enables you to consume exposed OData services for SAP transactions (with support of SAP Mobile Services infrastructure).

Depending on the selected project template, there's 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.

Continuing with the UI Integration Card project template, the next step requires you to provide project details, for example, project name, namespace, and card sample.

While most of the parameters are easy to understand, some require further explanation:

The Card Sample parameter enables you to define the appearance of the UI Integration Card by card type (template). SAP has a website: Card Explorer focused on the architecture of UI Integration Cards. It also provides a preview of all available and supported card types.

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. This is highlighted in the figure, Developing UI Integration Cards - Developing the Project. In this case, the wizard generates a project that uses the predefined SAP BTP destination JAM (pointing to the Digital Workplace Service component and its OData services).

When the project generates, it contains a set of standard sub-directories and files regardless of the type of card.

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

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

• UI Integration Card: Preview – This enables you to run a preview of the UI Integration Card right in SAP Business Application Studio and without any deployment to SAP Build Work Zone.
• UI Integration Card: Edit – This enables you to open a user-friendly editor of the manifest.json file.
• UI Integration Card: Package – This enables you to generate a deployable archive with the UI Integration Card in the root of the project directory. Then, you can download this archive and manually deploy it through the Administration Console of SAP Build Work Zone.
• UI Integration Card: Deploy to SAP Build Work Zone – This enables you to generate a deployable archive with the UI Integration Card and deploy it to SAP Build Work Zone without leaving SAP Business Application Studio.

The preview of the UI Integration Card in SAP Business Application Studio is useful. It enables you to view the result without deploying the UI Integration Card to SAP Build Work Zone or running any local infrastructure:

By default, the preview triggers automatically when changes are made and saved in the manifest.json file. Sometimes, this functionality can be distracting, especially when there must be many 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 SAP UiCardDK Extension in the menu Preferences → Open Preferences in SAP Business Application Studio:

Using preferences, both the Auto Preview on Manifest Changed option and the Auto Preview On Manifest Saved option can be switched off when many changes must be made in the manifest.json file. These settings don’t remove the preview functionality from SAP Business Application Studio. It can still be triggered manually (and when necessary) from the context menu of the manifest.json file.

The preview functionality relies on the sub-directory .card in the root of the project directory. It stores temporary content, for example, the preview file for SAP Business Application Studio. When this sub-directory 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 many files and directories having "." at the beginning are excluded). It can be easily fixed. Create an empty sub-directory .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 the bad practice of hard coding connection details in UI Integration Cards. From a technical point of view, connections are defined in the manifest.json file of the UI Integration Card.

As shown in the figure, Developing UI Integration Cards - Referencing Multiple Destinations, you can define as many connections as necessary.

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.

As outlined in the figure, Developing UI Integration Cards - Reference Between SAP BAS and BTP Cockpit, the connection is made by maintaining the technical name of the SAP BTP destination in the manifest.json file. However, 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 enables you to use different BTP destinations in different environments.

Note that SAP BTP destination in the settings of the UI Integration Card can only be changed from the Administration Console of SAP Build Work Zone. When the UI Integration Card is placed to home pages or workspaces by users, the settings of SAP BTP destinations don’t display.

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

• Option 1: by generating a deployable archive with the UI Integration Card in SAP Business Application Studio, exporting it to your local machine, and importing it to SAP Build Work Zone via the Administration Console.
• Option 2: by deploying the UI Integration Card to SAP Build Work Zone right from SAP Business Application Studio (using the context menu of the file manifest.json).

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:

• SAP Build Work Zone and SAP Business Application Studio are configured and used in the same SAP BTP subaccount. In this case, both service instance and destination are created in the same SAP BTP subaccount. It is the easiest option.
• SAP Build Work Zone and SAP Business Application Studio are configured in different SAP BTP subaccounts. Then, the service instance is created in the SAP BTP subaccount with SAP Build Work Zone while the destination is created in the SAP BTP subaccount with SAP Business Application Studio.

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, advanced edition 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 workpages and workspaces. When everything is maintained, the UI Integration Card can be enabled for wider use.

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).

While there are no mechanisms to move UI Integration Cards from one SAP BTP subaccount with SAP Build Work Zone to another 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:

• The Where Used option allows you to track where a specific UI Integration Card is used. It includes home pages and workspaces. By default, private workspaces are hidden due to standard compliance and security settings. If there is a need to see a list of private workspaces (where the UI Integration Card is used), it can be enabled in the menu Compliance & Security → Content Administration in the Administration Console. In general, the Where Used option helps you to understand the adoption of the UI Integration Card in the company (and answer the question "Is the UI Integration Card really used in the company?") as well as understand what home pages and workspaces might be impacted by the next update of the UI Integration Card (and answer the question "Who and what can be impacted, and where to validate?"). The option is disabled when the UI Integration Card is not yet used on any home pages or workspaces.
• The Card Access List option allows you to restrict the usage of UI Integration Cards in SAP Build Work Zone by allowing you to add to home pages or specific workspaces only. By default, there are no restrictions: UI Integration Cards can be added to any home page or workspace. The typical use case for this option is restricting usage of UI Integration Cards with a focus on a specific line-of-business or domain: for instance, UI Integration Cards for HR-related topics should be available on respective HR-related home pages and workspaces only. Sometimes, there might also be cases where the UI Integration Card should not be available to end users in the menu My Workspace – this is where this option becomes useful, too!
• The Delete option allows you to delete a UI Integration Card from SAP Build Work Zone. It does not impact any data on back end systems like SAP S/4HANA, SAP SuccessFactors, and so on. Note that there is no option to restore a UI Integration Card deleted accidentally. A UI Integration Card can be deleted even if it is used in various home pages and workspaces – in this case, it will be replaced by an error message. It is recommended to check where the UI Integration Card is used before deletion (by utilizing the already mentioned Where Used option). When a UI Integration Card is well-architected, it does not store any business data – thus, deletion of the UI Integration Card does not impact it.
• The Download option allows you to download a ZIP archive with source code of the UI Integration Card. One of the use cases for this option is the extension of the UI Integration Cards pre-delivered with SAP SuccessFactors Work Zone: the copy of standard UI Integration Cards can be adjusted with SAP Business Application Studio and then deployed to SAP Build Work Zone as a new artifact. The option to download source code can be used for backup purposes (if the original source code is lost for some reason, for example).

UI Integration Cards help to enrich the digital experience. 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.

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:

• At the beginning of your development journey, try to re-use the existing REST API of back end systems. The development of REST APIs for back end systems may lead to unexpected delays, due to lack of resources and expertise. It also extends your support scope and effort.
• Avoid re-development of already available SAP Fiori apps – try to enrich them instead. SAP Fiori apps can be placed and accessed from any page of the digital workplace – it does not bring value to fully re-develop them in the form of UI Integration Cards.
• Introduce reasonable functionality and avoid over-engineered UI Integration Cards. While UI Integration Cards allow you to use JavaScript and implement any kind of complexity, they should not replace back end systems. UI Integration Cards are loaded and rendered in the web browser: complex cards can slow down the loading and rendering of the overall page and impact user experience.
• Develop UI Integration Cards as independent units, without technical dependencies on each other. There are no standard mechanisms to track dependencies between UI Integration Cards and force users to place some of them together on the same page.
• Use existing mechanisms and services to connect to back end systems – do not hardcode connections. While you can use the full power of JavaScript and do direct HTTP requests from UI Integration Cards to back end systems, it is strongly recommended to use the standard API available for UI Integration Cards and do calls through the SAP BTP Connectivity service and SAP BTP Destination service.
• Use proper authentication and authorization processes – avoid so-called service or technical users. Users should be able to consume and work on data to which they have access in respective back end systems. Remember that UI Integration Cards and code are executed on the client side (in the web browser).
• Respect standard UX patterns and follow guidelines available for SAP Fiori and SAPUI5. UI Integration Cards are shown as embedded elements of the digital workplace. They should fit well on any page without shifting the user's attention and focus.