Creating custom cards for the home page with the custom cards API

Create custom cards to display key performance indicators on the IBM® Cloud Pak for Data home page with the Custom cards REST API.

For example, if you want to show disk usage as a percentage of available disk space, you can add a custom card to the home page that displays the data in a donut or bar chart.

You can use the Custom cards REST API to complete the following tasks:

Generate an authorization token
To use the Custom cards REST API, you must authenticate to IBM Cloud Pak for Data. See Generating an authorization token. See also Get authorization token in the IBM Cloud Pak for Data Platform API.

Get a list of custom cards

Retrieves the properties for the custom cards that you can update.

Curl

GET /zen-data/v1/custom_cards

Sample command

curl -kiv -X GET \
  https://my-deployment-url/zen-data/v1/custom_cards \
  -H 'Authorization: Bearer authorization-token' \
  -H 'Content-Type: application/json'

Sample response

In the following code block, the body of the response is replaced with ....

"_messageCode_": "success",
    "message": "Successfully retrieved custom cards",
    "requestObj": {
      ...
}

Create or replace a custom card

Creates a custom card or replaces an existing custom card. You must include the card definition as a JSON string in the HTTP request body. The definition specifies the structure and the content of the card.

Parameter	Type	Description
key	`String`	The name of the card that you want to create or replace. The string must be unique. If a custom card with the specified key does not exist, the custom card is created, otherwise the existing custom card is replaced.
data	`object`	Provides data to the card. You must provide either a data_url object or a data object. The data object is an object that populates data in the card. The properties of the object must match the type of template defined. The expected structure for each template_type parameter is in the examples below.
data_url	`endpoint`	Provides data to the card. You must provide either a data_url object or a data object. The data_url object is an endpoint that is called to populate data in the card. The response that is sent by the endpoint matches the type of template defined. The expected response structure for each template_type parameter is shown in the examples below.
description	`String`	Helps users understand the purpose of the card. The string must be 200 characters or less.
drilldown_url (Optional)	`String`	Defines the URL that the user navigates to when they click View details. If this parameter is not defined, the card does not display a View details link.
order	`integer`	Defines the position of the card. The value must be in the range 1 - 50.
permissions	`array`	Specifies the permissions that a user needs to see the card. The array must have at least one permission. If the array has no permissions parameter, the card is shown to everyone. For a list of valid permissions, run List all permissions in the Cloud Pak for Data platform API.
refresh_rate (Optional)	`Integer`	The interval in seconds at which the content is refreshed by the source.
template_type	`enumerated_type`	Defines the display type of the card. The template_type parameter must be one of the following values: `bar` `big_number` `content_block` `donut` `list` `number_list` `text_list`
title	`String`	The display name for the card. The string must be 40 characters or less.
window_open_target (Optional)	`string`	Specifies the target attribute or the name of the window. The following values are supported: Empty or not provided - the URL gets loaded on the current page by default. `_blank` - URL is loaded into a new window or tab every time. `name` - The name of the window where the URL is loaded. The name does not specify the title of the new window.

Use the following examples to understand the data object.

bar_data

“data”: {
        “bar_data”: {
              x_axis_label: 'Packages',
              y_axis_label: 'Projects',
                "data_array": [
                  {
                        "group": "Qty",
                        "value": 65000
                    },
                    {
                        "group": "More",
                        "value": 29123
                    },
                    {
                        "group": "Sold",
                        "value": 35213
                    },
                    {
                        "group": "Restocking",
                        "value": 51213
                    },
                    {
                        "group": "Misc",
                        "value": 16932
                    }
                ]
       }
}

big_number_data

“data”: {
       “big_number_data”: {
              prefix: 'ArrowUp32',
              metric: '1.6',
              suffix: '%',
              sub_text: 'Since last month',
              footer_1: '867 Total vulnerabilities',
              footer_2: 'AskPQL 2.3 package most at risk'
       }
}

content_block

"data": {
    "content_block_data": {
      "rows": [
        {
          "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, ...",
          "type": "text",
          "nav_url": "",
          "window_open_target": ""
        },
        {
          "content": "Sed ut perspiciatis unde omnis iste natus error sit ...",
          "type": "text",
          "nav_url": "",
          "window_open_target": ""
        },
        {
          "content": "B2C systems",
          "type": "link",
          "nav_url": "/some/link/b2c",
          "window_open_target": "b2c_window"
        },
        {
          "content": "B2C systems",
          "type": "link",
          "nav_url": "/some/link/b2c",
          "window_open_target": ""
        }
      ]
    }
  }

donut_data

"data": {
              "donut_data": {
                "center_label": "Disk usage",
                "data_array": [
                  {
                    "group": "2V2N 9KYPM version 1",
                    "value": 20000
                  },
                  {
                    "group": "L22I P66EP L22I P66EP L22I P66EP",
                    "value": 65000
                  },
                  {
                    "group": "JQAI 2M4L1",
                    "value": 75000
                  },
                  {
                    "group": "J9DZ F37AP",
                    "value": 1200
                  },
                  {
                    "group": "YEL48 Q6XK YEL48",
                    "value": 10000
                  },
                  {
                    "group": "Misc",
                    "value": 25000
                  }
                ]
              }
            }

list_data

“data”: {
       list_data: {
              headers: [
                     'project_name',
                     'last_updated_time'
              ],
              rows: [
              {
                     'project_name': 'Improving customer online registration',
                     'last_updated_time': '2 min ago',
                     'nav_url': ' /projects/49753ad5-dcf5-4f94-913f-10acf78a4e71
              },
              {
                     'project_name': '2020 Q1_Increasing Search performance and..',
                     'last_updated_time': '30 min ago',
                     'nav_url': ' /projects/49753ad5-dcf5-4f94-913f-abc
              },
              {
                     'project_name': '2019 Customer shoes sales analysis',
                     'last_updated_time': '1 hour ago',
                     'nav_url': ' /projects/49753ad5-dcf5-4f94-913f-def
              },
              {
                     'project_name': 'Project X Final version',
                     'last_updated_time': 'Today 11:04 PM',
                     'nav_url': ' /projects/49753ad5-dcf5-4f94-913f-qrs
              },
              {
                     'project_name': 'Project X Final version 2',
                     'last_updated_time': 'Yesterday 12:45 AM',
                     'nav_url': ' /projects/49753ad5-dcf5-4f94-913f-tuv
              }
              ]
       }
}

number_list_data

“data”: {
       “number_list_data”: {
              rows: [
              {
                     drilldown_url: '/zen/#/openSource/packages',
                     label: 'Total approved packages',
                     value: '3'
              },
              {
                     label: 'Total licenses',
                     value: '2345'
              },
              {
                     label: 'Total user interactions',
                     value: '25K'
              }
              ]
       }
}

text_list_data

“data”: {
       “text_list_data”: {
              rows: [
              {
                     drilldown_url: '/zen/#/openSource/packages',
                     label: 'Data virtualization',
                     sub_text: 'dv'
              },
              {
                     label: 'Watson assistant',
                     sub_text: 'assistant'
              },
              {
                     label: 'Watson openscale',
                     sub_text: 'aios'
              }
              ]
       }
}

Use the following examples to understand the data_url object. The format of the expected response that is provided in the data_url from the endpoint for each card type is shown in the following examples.

bar

{
      "x_axis_label": "Packages",
      "y_axis_label": "Projects",
      "data_array": [
         {
            "group": "Australia",
            "value": 250
         },
         {
            "group": "Brazil",
            "value": 120
         },
         {
           "group": "Canada",
            "value": 190
         },
         {
            "group": "Germany",
            "value": 170
         }
      ]
}

big_number

{
       prefix: 'ArrowUp32',
       metric: '1.6',
       suffix: '%',
       sub_text: 'Since last month',
       footer_1: '867 Total vulnerabilities',
       footer_2: 'AskPQL 2.3 package most at risk'
}

content_block

{
    "rows": [
      {
        "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, ...",
        "type": "text",
        "nav_url": "",
        "window_open_target": ""
      },
      {
        "content": "Sed ut perspiciatis unde omnis iste natus error sit ...",
        "type": "text",
        "nav_url": "",
        "window_open_target": ""
      },
      {
        "content": "B2C systems",
        "type": "link",
        "nav_url": "/some/link/b2c",
        "window_open_target": "b2c_window"
      },
      {
        "content": "B2C systems",
        "type": "link",
        "nav_url": "/some/link/b2c",
        "window_open_target": ""
      }
    ]
}

donut

{
      "center_label": "Disk usage",
      "data_array": [
         {
            "group": "2V2N 9KYPM version 1",
            "value": 20000
         },
         {
            "group": "L22I P66EP L22I P66EP L22I P66EP",
            "value": 65000
         },
         {
            "group": "JQAI 2M4L1",
            "value": 75000
         },
         {
            "group": "J9DZ F37AP",
            "value": 1200
         },
         {
            "group": "YEL48 Q6XK YEL48",
            "value": 10000
         },
         {
            "group": "Misc",
            "value": 25000
         }
      ]
}

list

{
       headers: [
              'project_name',
              'last_updated_time'
       ],
       rows: [
       {
              'project_name': 'Improving customer online registration',
              'last_updated_time': '2 min ago',
              'nav_url': ' /projects/49753ad5-dcf5-4f94-913f-10acf78a4e71
       },
       {
              'project_name': '2020 Q1_Increasing Search performance',
              'last_updated_time': '30 min ago',
              'nav_url': '/zen/#/mydata/datasets'
       },
       {
              'project_name': '2019 Customer shoes sales analysis',
              'last_updated_time': '1 hour ago',
              'nav_url': '/zen/#/mydata/datasets'
       },
       {
              'project_name': 'Project X Final version',
               'last_updated_time': 'Today 11:04 PM',
               'nav_url': '/zen/#/mydata/datasets'
       },
       {
              'project_name': 'Project X Final version 2',
              'last_updated_time': 'Yesterday 12:45 AM',
              'nav_url': '/zen/#/mydata/datasets'
       }
       ]
}

number_list

{
      rows: [
         {
            label: 'Total approved packages',
            value: '3'
         },
         {
            label: 'Total licenses',
            value: '2345'
         },
         {
            label: 'Total user interactions',
            value: '25K'
         }
      ]
}

text_list

{
      rows: [
         {
            label: 'Data virtualization',
            sub_text: 'dv'
         },
         {
            label: 'Watson assistant',
            sub_text: 'assistant'
         },
         {
            label: 'Watson openscale',
            sub_text: 'aios'
         }
      ]
}

Curl

PUT /zen-data/v1/custom_cards/{key}

Sample command

curl -k -X PUT 'https://my-deployment-url/zen-data/v1/custom_cards/unique-card-key' \
--header 'Authorization: Bearer authorization-token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "permissions": ["manage_catalog"],
  "order": 1,
  "title": "Disk usage",
  "template_type": "big_number",
  "data": {      "big_number_data": {
        "metric":  "55",
        "sub_text": "Increase since last month",
        "prefix": "ArrowUp32",
        "suffix": "%",
        "footer_1": "867 Total vulnerabilities",
        "footer_2": "AskPQL 2.3 package most at risk"
      }
    }
}
'

Sample response

{
    "_messageCode_": "success",
    "data": [
        {
            "id": "537163840404062200",
            "name": "os_vulnerabilities",
            "title": "Open source vulnerabilities",
            "description": "",
            "drilldown_url": "",
            "order": 12,
            "template_type": "big_number",
            "data_url": "",
            "empty_state": {},
            "source_url": "",
            "refresh_rate": 0,
            "data": {
                "big_number_data": {
                    "metric": "55",
                    "sub_text": "Increase since last month",
                    "prefix": "ArrowUp32",
                    "suffix": "%",
                    "footer_1": "867 Total vulnerabilities",
                    "footer_2": "AskPQL 2.3 package most at risk"
                }
            }
        }
    ],
    "message": "PUT custom card succeeded"
}

Edit a custom card

Edit the information that is displayed on an existing card. You can edit the following content:

data
data_url
description
drilldown_url
order
permissions
template_type
title

To edit a custom card, use the rules that are specified in Create or replace a custom card.

Curl

PATCH /zen-data/v1/custom_cards/{key}

Path parameters

Parameter	Type	Description
key	`String`	The name of the card that you want to update.

Sample command

This command updates the title of a custom card called disk_usage_donut.

curl -kiv -X PATCH \
  https://my-deployment-url/zen-data/v1/custom_cards/disk_usage_donut \
 
  -H 'Authorization: Bearer authorization-token' \
  -d '{
  
  "title": "Disk usage"
}'

Sample response

{
    "_messageCode_": "success",
    "data": [
        {
            "id": "1",
            "name": "homepage_card_disk_usage",
            "title": "Disk usage",
            "description": "",
            "drilldown_url": "/zen/#/v1/diskUsage",
            "order": 2,
            "template_type": "donut",
            "data_url": "/zen-data/v1/homepage/diskUsage",
            "empty_state": {},
            "source_url": "",
            "refresh_rate": 0,
            "data": null
        }
    ],
    "message": "Successfully edited custom card"
}

Delete a custom card
Deletes an existing card with the specified key.
Curl

DELETE /zen-data/v1/custom_cards/{key}

Path parameters

Parameter Type Description

key String The name of the custom card that you want to delete.

Sample command
This command deletes the os_vulnerabilities card.
```
curl -kiv -X DELETE \
  https://my-deployment-url/zen-data/v1/custom_cards/os_vulnerabilities \
  -H 'Authorization: Bearer authorization-token' 
```
Sample response
```
{
    "_messageCode_": "success",
    "message": "Successfully deleted custom card"
}
```

Parameter	Type	Description
key	`String`	The name of the custom card that you want to delete.

You can't use the Custom cards API to replace, edit, or delete existing cards that are added by Cloud Pak for Data.

Sample custom cards

You can start with a template to create each of the custom cards that are shown in the following image. See the template types for a description of the templates that were used.

This image shows all the custom cards types that can be created. The templates that are used to create each of these custom cards are described in the legend that follows this image .

Template types:

1 The donut template illustrates an array of values as percentages in a donut chart.
2 The bar template creates a two-dimensional bar graph.
3 The big_number template highlights significant data.
4 The text_list displays a list of text strings.
5 The number_list displays a list of numeric values and associated text.
6 The list displays a list of navigation links. The list can contain headers and associated clickable links.
7 The content_block displays rows of text or links. Each row can be a paragraph of text or clickable links.

For the JSON payload that describes these custom cards, see the sample command in Create or replace a custom card.