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 Get authorization token in the IBM Cloud Pak for Data Platform API. The authorization-token that you get in the response is used as a token in subsequent API calls.
Curl

POST -H "cache-control: no-cache" -d "{\"username\":\"{user}\",\"password\":\"{pwd}\"}""https://{host}{:port}/icp4d-api/v1/authorize"

Sample command
```
curl -k -X POST \
  https://my-deployment-url/icp4d-api/v1/authorize \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
       "username":"username",
       "password":"password"
}'
```
Sample response
```
{
    "_messageCode_": "200",
    "message": "Success",
    "token": "authorization-token"
}
```

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.
roles (Optional)	`zen_user_role`	Specifies the role that a user needs to access a card. Use this with the permissions parameters set to an empty array. Use `zen_user_role` for the default `User` role. Use `zen-administrator_role` for the default `Administrator` role To find all available roles, use the following `curl` command. Then, use the role_id for that role from the `curl` response when you create a custom card. `curl -k -X GET 'https://my-deployment-url/usermgmt/v1/roles' --header "Authorization: $token"`
template_type	`enumerated_type`	Defines the display type of the card. The template_type parameter must be one of the following values: `donut` `bar` `big_number` `text_list` `number_list` `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'
       }
}

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.

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
         }
      ]
}

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'
}

text_list

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

number_list

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

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'
       }
       ]
}

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 command using roles

{
  "permissions": [],
  "roles": ["zen_user_role"],
  "order": 1,
  "title": "Content block title",
  "template_type": "content_block",
  "data": {
      "content_block_data": {
          "rows": [
                        {
                            "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
                            "type": "text"
                        },
                        {
                            "content": "Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?",
                            "type": "text"
                        },
                        {
                            "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"
                        }]}
    }
}

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

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