Visualization Viewer templates and Info Card templates

[slavko_snjegota]

Info Cards

Introduction to info cards

Info card is UI section displayed in Info Card UI panel which is designed to show additional information about selected object or links to external applications that include selected object identification so that external app can prepopulate itself with data about such object. Info cards are highly configurable and flexible which can be little problematic for initial setup as system administrator has to have deep understanding of its possible configurations. But once configured, it is very easy to use and end users will not have any trouble to see and use these functionalities.

It is one of the main extensibility features of SPA IPD Visualization applications and allows close integration with any other SAP application, or even most of third party applications and services.

Info card configurator is application under “Manage Templates” tile in the Visualization section of SAP IPD Fiori launchpad. There are two tabs in this section “Viewer Templates” and “Card templates”. We are now working with “Card Templates” tab.

Please note that Info Card UI panel in Viewer can include multiple Info Card templates. In most cases single template is enough to show all information that customer needs but keep in mind that this is supported scenario. That can be useful if the same card will be reused in several places, then we can combine cards in UI panel for additional flexibility. We’ll talk about this more later when we discuss Viewer Template.

While user is editing info card it can be saved as draft. Such info cards cannot be used in Viewer templates. Info card must be published in order to allow their use in viewer templates.

Creating new Info Card – UI layout

When you add new Info Card you first have to provide a card name. It must be unique and also should be something meaningful that you can remember.

Buttons in top right corner allow us to save this card as draft and there is also Publish button which we will use to make info card available in viewer templates.

There are three sections in Manage Card Templates app. Left section “Card Preview” shows how your card will look at run time once it is published.

Middle section “Card Design” is where the card design is done. Here you can specify what content will be displayed in the car and in what order.

Right section “Usage and Metadata” is where you can provide sample data which will be used in Card Preview section. At runtime this data will be extracted from selected object, but while we are designing the card we provide sample data here.

Substitution texts

Some parts of info card allow text substitution which is specially formatted text which will be replaced at runtime with text based on selected object. There are two possible substitution texts, metadata and Usage Ids. Metadata substitution is string in this form:

{meta:source|category|name}

This means that at runtime when user selects a 3D object, system will look for metadata with specified source, category and name on this object and, if found, it will take value from such metadata field and replace text in curly brackets with it.

Curly brackets and meta: prefix are required. In SAP IPD Visualization metadata consists of three fields: source, category and name. Source part is optional, but category and name are required. Value for metadata is free text. Such metadata can be assigned to visualizations themselves or to specific objects inside of visualization. In case of 3D models each object in scene can have its own metadata. In Authoring app you can edit such object’s metadata and there you can specify metadata source, category, name and its value. If source is not required then it can be omitted but vertical bar still has to be present, for example like this:

{meta:|category|name}

Usage Ids are special way of tagging objects which is different from metadata. It provides a well-known structure to be assigned to selected objects, visualizations or folder and they are specified in “System Administration” tile of IPD Visualization. Usage Ids are supposed to represent keys from other applications which is very useful feature for integrations. For example, if APM system is integrated with IPD Visualization they can add special Usage Id to 3D objects which will carry equipment number. This way APM does not need to store any internal identifier of IPD Visualization and still will be able to open correct visualization which is connected to particular equipment record in their system by just providing their own equipment id. The same applies to any other integration. Usage Ids can have multiple keys, or example Usage Id “As-Sold” has two keys: “Material” and “Customer Order”.

We provide several Usage Ids out of the box, but more can be added in System Administration app.

Usage Id substitution is similar to metadata, but it starts with prefix usage: in curly brackets, like this

{usage:As-Sold|Material}

This means that at runtime when user selects a 3D object the system will look for Usage Id “As-Sold” on such object and if it finds it will take value from the “Material” key and replace text in curly brackets with it. I used this example because “As-Sold” has two keys so this is the way to specify what Usage Id and what key will be used to get substitution value.

In addition to these two substitution texts (meta and usage) there is one more which is used only in few specific cases. It is data source substitution, and it is in this form

{ds:name}

This can be used only if section allows data source to be selected and then the “name” in this text specifies name of parameter of data source which we want to use.

Info Card title

Let’s provide a name for the new card and then we’ll look into the Card Design section. To show real time preview of real data we allow users to load a sample visualization in card template designer. Click on “Load Visualization” and find a visualization in your system which will be good representation of 3D models that we expect to be used with this info card.

The first thing to decide is what we want to be used as card title. Card title can be the name of the selected object, or it can come from some of selected object’s metadata. For example, if we have loaded 3D model of a rocket and if user selects a single object (1st Stage Middle) we can display name of that object as card header. 

But we can as well select some of metadata assigned to that object which we want to be used as card title. To do so in card designer we will select title to be “Metadata Selected”. Now in the text box we will provide substitution string which will be used to construct card title. If we want to use objects metadata, then we will provide a substitution text which is in this form:

{meta:source|category|name}

Curly brackets with meta: indicates that we want to take metadata from selected object which has particular source, category and name. For example if we open properties panel and select these objects we will see what metadata exists on them. In case of the rocket model we have these metadata fields:

If I want to show JT_PROP_NAME as my card title I will specify substitution string like this:

{meta:|CADMetadata|JT_PROP_NAME}

Note that for this metadata we don’t have value for source so it’s skipped and there is nothing before the first pipe character (‘|’). To check metadata in detail, we can open Author app, load this model there and then use Metadata panel on the right hand side toolbar to examine existing metadata and see what parts are present. In this case source is missing, category is “CADMetadata” and filed we are interested in is “JT_PROP_NAME”. At runtime, when user selects this part, this text will be replaced with “1st Stage Middle.asm;36;31:” as this is content of specified metadata field.

It is possible to combine static text and metadata so we can have something like this:

Object name: {meta:|CADMetadata|JT_PROP_NAME}

This will resolve in info card title like this:

Object name: 1st Stage Middle.asm;36;31:

To test how this will look like we need to provide an example data in the right-hand side panel. So, in the Metadata tab, click on Edit Metadata and add metadata record like this:

Note that card preview (the UI panel on left hand side) has reflected this change and is now showing how this title will look like at runtime. It includes static text (“Object name:”) and content of metadata defined with text substitution (“My object name”). Again, at runtime content of this metadata will be extracted from selected object and placed in info card.

Note that this text field can contain just static text without any substitution string, in which case the same text will be used for all objects.

Info Card content

Next let’s consider content of the info card. We add content by adding new section. In Card Design section press “Add Section” button. There are five possible sections:

• Link URL
• Fiori Intent Navigation
• Data Source
• Properties
• Visualization

Link URL

This is the simplest section of info cards. It can include one or more links which can be configured to open sites with parameters based on a selected object.

We will first specify name of this section. I’ll call it “My set of links”. Section name is optional and can be turned off by clearing “Display Section Name” checkbox. Another option is to expand this section when info card is opened or keep it closed. User can always change state of this section, but this determines the default state.

Now press “Add Link URL” button. This adds set of fields required for the first link. There are only two fields that we have to fill. What will be displayed in this section of info card and where this link will take us. Both fields allow static text and text substitutions.

For example, I set “Display Name” to be “Search Google for object” and URL to be this:

http://www.google.com/search?q={meta:|CADMetadata|JT_PROP_NAME}

Note that link is not enabled until texts substitutions in both fields can be successfully resolved. If you specify metadata that does not exist in sample data, the link will not be enabled. At runtime the link will be enabled only if selected object contains required metadata.

In this case my link in card preview is enabled and it will navigate me to Google site and search for the name of selected object. Similarly, we can construct URL to any other site where we can pass selected object’s name or metadata.

If the text which I want to use for search is stored in Usage Id instead in metadata, then I will use usage: substitution text:

Now we can add more URL links in this section or just leave it with single link.

Fiori Intent Navigation

This section allows us to create links based on Fiori Intent Based Navigation. As for Link URL section we can provide section name and specify if we want to name to be displayed and if we want this section to be expanded or collapsed when user opens info card.

Now let’s press “Add Link URL” button, I will explain “Autogenerated List” option later.

This inserts three fields in Card Design UI: text to be displayed for this link, semantic object and action for Fiori intent navigation. I will skip details about these parameters as this is available in other resources related to Fiori Intent Based Navigation but what we are interested in is what we can place in these text fields. As before it can be static text or substitution text, as well as any combination of these two.

For example, let’s assume that 3D objects in loaded visualization are tagged with Usage Id “Collaboration. This tag will contain Collaboration session identifier, and I should be able to create link in my info card which will use Fiori Based Navigation to open Collaboration viewer and automatically load particular collaboration session based on my selected object. To do that I will set Fiori Navigation Semantic object to “Collaboration”, Action will be “Display”. There is one additional parameter which I have to add to this link so I will press “Add Parameter” button and give it name “CollaborationDetails”.

All these parameters are fixed and don’t depend on selected object. However, value of this last parameter will be taken from selected object therefore we will provide substitution text here.

This will construct Fiori Intent Based Navigation link on left hand side (Card Preview) and at runtime this will navigate to Collaboration app.

“Autogenerated List” checkbox allows us to use data source of type list to automatically generate list of Fiori Intent Based Navigation links. This is useful if we have data source which returns list of data and we want to use some of that data to automatically construct list of Fiori navigation links. In this case we will use text substitution of type data source with prefix ds:.

First, we need to select data source which must be configured earlier using “Manage Data Sources” app.

Let’s consider the simplest example where data source does not have any input parameter. It will just return list of items from some service.

To create list of Fiori Intent Based Navigation links we need to provide some parameters:

Display Name parameter defines what will be displayed as the link name in the list. In this case we will show field “name” which is coming from data source – that’s why we use text substitution of type ds:.

Highlight Indicator specifies field in data source output which should resolve to true or false. If it resolves to true then next field Highlight Text will be displayed, or it will be hidden if that parameter is false. In the example above all items have that value set to true so text “Important” is displayed in all of them.

Next are regular Fiori Intent navigation semantic object, action and list of parameters. Here we set parameter “material” based on value extracted from Usage Id “As-Designed” from selected object in 3D scene.

This was example with data source which didn’t need any input parameters. A little more difficult use case is if we want to use data source which do require some input parameters. In this case we have to specify where these parameters are coming from. Again, they can be static texts, or can be extracted from selected object’s metadata or Usage Id.

Let’s say I want to use data source which has one single parameter “binId”, like in the picture below. 

This parameter is shown in UI and there is drop down list where I can specify where to get this parameter from. Static Value is the simplest, but it will not change at runtime. This is good option if I want always to use the same value as input parameter for this data source. In most cases we will use either Usage or Metadata which will be extracted from selected object. It is also possible to specify scene id or selected node id but these are IPD Visualization internal parameters and should not be used for external integrations.

Depending on selected source of the parameter more UI options will be displayed. If I select Static Text then only single text field is presented where I will type this statis text. However, if I select Usage then two drop down boxes will be presented. In the first box I will select what Usage Id I expect on selected objects. Then second box will be populated with list of keys from selected Usage Id. In most cases that will be single key but as mentioned before, some Usage ids can have multiple keys and I need to specify which one will be taken. This is like using substitution text where we also can specify what Usage Id and what parameter we want to use but this way is more user friendly.

If data source has multiple input parameters, then such UI selection will be enabled for each of its parameters.

If Usage or Metadata is selected there will be switch button “Match Ancestors” which allows us to specify what to do if required Usage Id or metadata is not found on currently selected object. If this switch is turned on then we will go up the tree and find the first ancestor object which does have requested Usage Id or metadata field and we will use that one. If this switch is turned off and requested data does not exist on selected node then system will not try to find ancestor object with this data and this section of info card will not be enabled.

The rest is the same as explained earlier, we will specify Fiori Navigation semantic object, action and parameters.

Data Source

This section allows us to invoke data source which can modify data on server. Because of that requirement only data sources that use POST verb are included in selection here.

This section is represented with single item which looks like link. When user clicks on it system will collect parameters from selected object as specified, and invoke such data source. If invocation is successful there will be green notification saying that call to data source was successful. If something went wrong then red warning will be displayed.

Properties

This section allows us to show tabular data retrieved from data source. As in other sections we will first give this section a name and specify if we want this title to be displayed in info card, and if this section will be expanded or collapsed when user opens info card.

Next, we can add one or more tables of data. For each one we will select data source form the list of available data sources. Only data sources of type “object“ or type “list” are listed here.

If data source has input parameters, then we need to specify where parameters are coming from. See previous example for details about this selection.

If data source is of type “object” then we will show two columns table with name/value pairs of all data retrieved from data source.

However, if data source is of type list, then table is multi-row table where each row represents single record retrieved from data source and columns are data source output parameters.

Both types of tables are shown in the image below. Note that for simplicity I have used data sources without input parameters.

Visualization

The Visualization section of info card allows us to navigate to another visualization in IPD Visualization system and open it in selected Viewer template. Although the same outcome can be achieved using “Fiori Intent Navigation” section advantage of this one is that it allows visualization preview in info card.

Typical use case for this is to open a 3D model of an assembly, select a part and then open 3D model of that part alone or it can be a 2D drawing visualization with formal specifications of that part. It can also be navigation type of visualization, there are no limitations here.

To specify what visualization we want to show in info card we need to select how do we identify it. In “Resolve Visualization by” drop down list we can select if we are looking for Usage Id, Metadata or we want to specify fixed value. In this example the target visualization is identified by its Usage Id which must match Usage Id or metadata of selected node. For example, if selected node has Usage Id “As-Built” and key “Model No” set to “123abc” then system will look for a visualization with the same Usage Id and it’s key value. Again, note that Usage Id can have multiple keys – they all must match.

It is possible that Usage Id or Metadata lookup will result in more than one visualization. This is not correct situation, but it is possible if multiple visualizations are tagged with the same data. In this case system will show message that there are multiple visualizations found, and this section cannot be resolved.

Viewer Templates

Viewer templates define options which we want to present to users when they open visualization in such viewer. Viewer templates are different for different visualization types which is understandable as, for example, 2D drawing type of visualization will not have options to rotate objects like in 3D space.

Viewer templates are managed in Manage Templates app, like info cards but in Viewer Templates tab.

When we add new viewer template, we first have to give it a unique name and select its type.

To create demo viewer for 3D models we will select 3D Model as the content type for which this viewer will be applicable.

Preset Configuration fills some of parameters of viewer template to be suitable for general use cases or for analytic viewing templates. It is possible to manually change these parameters and change viewer template from one mode to another.

UI Layout

Viewer Template designer has two main areas: the preview area and table with settings and options. When we create new viewer template system asks to select a 3D model which will be loaded as example. This allows us to see how viewer will look like later at runtime when real 3D models are loaded.

There are buttons in top right corner which we will use to save this viewer template as draft or to publish it to make it usable for all other users. Here I can also select different sample visualization to be loaded so that I can see how my viewer template will work with them.

Settings on right hand side can be used to customize viewer template and define what we want to include or exclude.

Settings

Toolbar section we can use to choose to completely remove top toolbar, or to include it but remove some of buttons from it. We can also select if initial state of the toolbar should be expanded or collapsed.

In the Viewport section we can select if scene orientation widget (scene axes in top right corner of the viewport) is displayed or not.

Important option in this section is that we can customize context menu which is open when user right clicks in viewport area. Default context menu has few options that are always present. But if we select an 3D object and right click on it then additional, custom items defined here are resent to end user.

Custom context menu items can have any name and one of two options which define what will happen when user clicks on such custom menu item. They are defined under Actions drop down list. The first option is to “Show Properties Panel” with selected view in it. View is predefined UI layout which shows data retrieved from data source based on selected objects identifier and it is defined in the “Properties Panel” section described later.

Second option is “Navigate to URL”. In this option we can construct URL and insert parameters in curly bracket. System will produce UI to select how these parameters will be populated. For example, I can specify URL like this:

https://www.google.com/search?q={material}

This will insert UI to select where is value for parameter “material” coming from. There is drop down list with options and they are similar to selections in info cards explained above. For this demo I will select “Node Usage ID” which means that I want this parameter to be extracted from selected object. If selected object has Usage Id “As-Designed” then value will be taken from its key “Material” and this will replace parameter in the URL.

This way I can add as many parameters as I need for my URL to function properly.

Most of other sections are self-explanatory and we will not spend too much time on them. Important section is “Properties Panel” where we define data view of selected object. This is also used in custom context menu when “Show Properties Panel” action is selected.

First, we need to create new view and give it a name. Then we select data source that will be used to retrieve external data about selected object. In this case only data sources of type “object” can be used. In most cases such data source has input parameter used to provide object identifier. In this example here parameter name is EQU and there is UI inserted where I can select where this parameter is coming from. As with info card settings, I can select to provide static value which is always the same for all selected objects. But in most cases I want to get identifier from the selected object and I can select Usage Id or metadata. There are few other options that are not relevant for this demo. If Usage Id is selected, then there are additional options to select which Usage Id and what is its key to be used as input parameter for data source call. Once parameter is successfully resolved we call data source, fetch data and show it as table.

For simplicity in this example, I have used static value to provide equipment id but in real use case that will come from selected objects Usage Id.

Next important section of viewer template is “Info Card”. This is where we can select info card designed in previous chapter. In order to use info cards, I have to enable them in UI by flipping “Available on UI” switch button. This adds new button in the top right corner of my viewer, above viewport. At runtime when I select an 3D object and click this button this will open info card, get data from selected object and fill info card according to its design.

Publishing

The last step in preparation of viewer template is to publish it. This will make it available for all users.

Before viewer template can be used it has to have proper assignment. This is done by pressing the “Assign” button in top right corner of viewer template designer. This viewer template is already specified to be applicable for 3D Models only (we defined that when we created it) but now we also have to select some additional options.

If “Allow for all Visualizations” switch button is turned off, then this template cannot be used as default. This is why “Set as default Viewer” switch button is not enabled. This means that this viewer will be available only for certain 3D model visualizations and these are the ones that have specific metadata. Metadata must be specified in the list in the bottom part of this dialog box. Here we can add one or more lines of metadata specifications and only visualizations that have such metadata assigned will have option to be opened by this viewer.

If “Allow for all Visualizations” switch button is turned on then metadata selection is ignored and this template will be available for all visualizations of type 3D Model. And in this case we can set this viewer template as default which means it will be used when user clicks on a tile representing 3D visualization. Only one viewer template can be default so this will affect all users.

Now when we have assigned and published our viewer template we can use it. If it’s not set as default then we will have to click on three dots icon next to 3D visualization and from displayed menu select “View Using” and then select our newly created viewer template.