Create a UI5 Integration Card that Displays Data from the Northwind Demo System

If you are following this tutorial as part of a workshop, please skip this step.

1. In SAP Business Application Studio, stop the dev space if it is not already stopped.

2. Edit the dev space by selecting the Edit button.

   

3. Ensure that the Development Tools for SAP Build Work Zone extension is checked and save the changes.

   

1. Open the dev space (If the dev space is not running, you first have to start it).

   

2. Select Start from template.

   

3. Choose the UI Integration Card template and select Start.

   

4. Fill-in the required project details. Use the Highlight Card template, which creates an Integration card of type List and select Finish.

   If you are following this tutorial as part of a workshop, please give your card a unique name. In this case your card name should be wz<your unique identifier>_orders_by_shipper.

   Description	Value
   Project Name	orders_by_shipper If you’re taking part in a workshop, please add your unique identifier to the project name like this: <your unique identifier>_orders_by_shipper.
   Name Space	ns
   Select a Card Sample (dropdown menu)	Highlight Card
   Title	Orders by Shipper
   Subtitle	UI5 Integration Card of Type List
   Compatible with SAP Mobile Cards (dropdown menu)	False

   

5. To see the card, right-click on manifest.json and select UI Integration Card: Preview.

   

6. Currently the card displays only static data:

   

7. Open the manifest.json file. Everything needed to render the card is described in this file.

   The manifest.json is a simple JSON file and has the following structure (check the picture below to see where each part is located):

   • sap.app namespace declaration. The type: card defines that this is a manifest for a card. Each card has a unique ID.

   • sap.card section:
     

     • Card type (List): Defines how the card is displayed. It could be one of the available content types - Adaptive, Component, Analytical, List, etc.
       
     • Header: Displays general information about the card. Using its properties, you can configure the title, subtitle, status text, and icon.
       
     • Content: This is the main section of the displayed card.

   • data sections: Define how the card handles its data. It can provide static data (see the json object below) or define required parameters for a data request to a backend system. Can be set on different levels (card, header, filter-definition, or content). The inner level data sections take precedence. In the example below the data section is defined on content level.

   

In the next steps you edit the manifest.json file to configure the card.

By connecting your card to the public Northwind demo service, you’re enabling the card to display dynamic data. Card destinations are used for outbound communication to a remote resource and contain the required connection information.

1. To set a destination, add the following configuration section in the sap.card section after the type subsection.

   JSON

   Copy

   "configuration": {
       "destinations": {
           "Northwind": {
               "name": "Northwind",
               "label": "Northwind V4 Service URL",
               "defaultUrl": "https://services.odata.org/V4/Northwind/Northwind.svc"
           }
       }
   },
   

   

2. To configure a data request pointing to the Northwind demo service, add a new data section after the configuration. In this way the data section will be defined on a card level. Note, that our destination is referred here using the double-bracket syntax {{destinations.Northwind}}.

   JSON

   Copy

   "sap.card": {
       "data": {
   	    "request": {
               "url": "{{destinations.Northwind}}/Orders"
           },
           "path": "/value"
       }
   },
   

   

IMPORTANT: Due to an issue with the UI Integration Card: Preview option, you may need to replace {{destinations.Northwind}} with “https://services.odata.org/V4/Northwind/Northwind.svc” !

Finally, to display the dynamically requested data, replace the static content section with the following one. The title, description, and info properties are now dynamically requested.

```JSON
"content": {
    "item": {
        "title": "{ShipName}",
        "description": "{ShipAddress}",
        "info": {
            "value": "{ShipCountry}"
        }
    }
}
```

  <!-- border -->![Image depicting manifest.json file – replace content section](3-3 NEW.PNG)

Results after Step 3:

The application displays dynamic data loaded from the Northwind demo service. Note, that the actual displayed products may differ depending on the current data provided by the Northwind demo service. You can also check the manifest.json file at this step. To learn more, see the Destinations and Data sections in the Card Explorer.

If you would like to deploy the card and see how it looks on SAP Build Work Zone, you can skip to Step 6 and deploy it. In the next steps you add card capabilities that can make your card more interactive.

Manifest parameters provide dynamic values for card attributes. They are replaced during manifest processing and can be used from the parameters model, for example: {parameters>/city/value}. As an example, in this step you will add parameters to set the header (title) property and the number (maxItems) of displayed items in the content.

If you are following this tutorial as part of a workshop and run out of time, you can skip steps 4,5,6 and create a simpler card. You can later read the steps you missed.

1. To define parameters - add the following parameters subsection in the manifest.json in the configuration section (note the comma which divides the entries).

   JSON

   Copy

   "parameters": {
       "title" : {
           "value": "Orders by Shipper"
       },
       "maxOrdersShown": {
           "value": "4",
           "type": "integer",
           "label": "Numbers of orders",
           "description": "How many orders to show in the list."
       }
   }
   

   

2. To use the new maxOrdersShown parameter, add it as shown below:

   JSON

   Copy

   "maxItems": "{parameters>/maxOrdersShown/value}"
   

   

3. Update the data request as follows:

   JSON

   Copy

   "data": {
       "request":{
           "url": "{{destinations.Northwind_V4}}/Orders",
           "parameters": {
               "$top": "{parameters>/maxOrdersShown/value}"	
           },
       "path": "/value/"
       }
   }
   

   

IMPORTANT: Due to an issue with the UI Integration Card: Preview option, you may need to replace {{destinations.Northwind}} with “https://services.odata.org/V4/Northwind/Northwind.svc” !

Finally, let’s also use the new parameters in the header section. Use the parameters syntax and edit (or replace) the header, so it looks like this:

```JSON
"header": {
    "title": "{parameters>/title/value}",
    "icon": {
        "src": "sap-icon://desktop-mobile"
    },
    "status": {
        "text": "{parameters>/maxOrdersShown/value}"
    }
},
```

  <!-- border -->![Image depicting manifest.json file - edit header](4-3 NEW.PNG)

Results after Step 4:

In this step, you have learned how to declare configurable parameters and use them to achieve the desired dynamic behavior. The application now displays a list of 4 items according to the parameters property (maxOrdersShown value: 4).

To learn more, see the Manifest Parameters section in the Card Explorer.

You can make the card even more dynamic when using filters. Filters appear as a dropdown under the card header, and users can interact to customize the data shown by the card. The value of each filter can be used inside a data request definition by using the {filters>/myFilter/value} placeholder. When the end user selects different value from the dropdown - a new data request is made with the updated value. As an example, in this step you will add a filter that enables users to filter the orders by a selected shipper.

1. Add a filters subsection in the configuration section. It defines a dropdown list with product categories, which are received by a data request.

   JSON

   Copy

   "filters": {
       "shipper": {
           "value": "{parameters>/selectedShipperID/value}",
           "type": "Select",
           "label": "Shipper",
           "item": {
               "path": "/value",
               "template": {
                   "key": "{ShipperID}",
                   "title": "{CompanyName}"
               }
           },
           "data": {
               "request": {
                   "url": "{{destinations.Northwind}}/Shippers"
               }
           }
       }
   },
   

   

2. Add selectedShipperID subsection in the parameters section. This is the shipper that is initially selected in the filter. Later, the user can change it from the dropdown list.

   JSON

   Copy

   "selectedShipperID": {
       "value": 3,
       "label": "The default selected shipper"
   }   
   

   

3. Add parameters in the main data section > request subsection, after the url property as shown below. The $filter parameter will be used in a data request for the orders with shipper that is equal to the one selected by the user in the filter’s dropdown list.

   JSON

   Copy

   "request": {
   	"url": "https://services.odata.org/V4/Northwind/Northwind.svc/Orders",
       "parameters": {
           "$top": "{parameters>/maxOrdersShown/value}",
           "$filter": "Shipper/ShipperID eq {filters>/shipper/value}"
   	}
   }
   

   

4. Finally, replace the title in the header adding the {filters>/shipper/selectedItem/title} parameter, which will show the selected category:

   JSON

   Copy

   "title": "Orders by Shipper {filters>/shipper/selectedItem/title}",
   

   

Results after Step 5:

If you have any issues you can check the manifest.json file at this step. It is configured with destinations, parameters, and a filter.

The application displays the products from the selected category:

To learn more, see the Card Filters section in the Card Explorer.

1. Select the dt/configuration.js file (in the Explorer view on the left).

   

2. Replace the content with the code below:

sap.ui.define(["sap/ui/integration/Designtime"], function (
    Designtime
) {
    "use strict";
    return function () {
        return new Designtime({
        "form": {
          "items": {
            "maxItems": {
              "manifestpath": "/sap.card/configuration/parameters/maxOrdersShown/value",
              "type": "integer",
              "label": "Maximum Items",
              "translatable": false,
              "description": "Defines how many items will be displayed at most."
            }
          }
        },
        "preview": {
          "modes": "LiveAbstract"
        }
      });
    };
});

The dt/configuration.js now looks like:

If you are using SAP Build Work Zone, advanced edition, please continue following this tutorial to deploy your card.

If you are using SAP Build Work Zone, standard edition, you will first have to create a Content Package before you can deploy the card. Please skip this step and follow the tutorial that explains how to create the content package: Create a Content Package with Your UI Integration Card

1. Right-click on the manifest.json file (in the Explorer view on the left) and select the UI Integration Card:Deploy to SAP Build Work Zone option from the dropdown menu.

   

2. Select the target SAP Build Work Zone destination.

   

3. In the right-bottom corner, confirm to Continue and wait to see the successful message.

   

Now the basic UI5 card deployment is done!

To learn more about the Integration cards and their functionalities, see the Card Explorer page.