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

Important: IBM Cloud Pak® for Data Version 4.7 will reach end of support (EOS) on 31 July, 2025. For more information, see the Discontinuance of service announcement for IBM Cloud Pak for Data Version 4.X.

Upgrade to IBM Software Hub Version 5.1 before IBM Cloud Pak for Data Version 4.7 reaches end of support. For more information, see Upgrading IBM Software Hub in the IBM Software Hub Version 5.1 documentation.

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

Required role
You must have administration privileges in Cloud Pak for Data. API authentication uses an authorization token with administration privileges.
Authentication
To use the Custom cards REST API, you must authenticate to IBM Cloud Pak for Data. See Generating an API authorization token. See also Get authorization token in the IBM Cloud Pak for Data Platform API.

Methods

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:

Get a list of custom cards

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

For more information, see Get a list of custom cards.
Sample command
curl -k -X GET 'https://{cpd_cluster_host}/v1/custom_cards' \
  -H 'Accept-Language: en-US' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {token}'
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.

For more information, see Create or replace a custom card.

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: 'Watson Query',
                     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: 'Watson Query',
            sub_text: 'dv'
         },
         {
            label: 'Watson assistant',
            sub_text: 'assistant'
         },
         {
            label: 'Watson openscale',
            sub_text: 'aios'
         }
      ]
}
Sample command
curl -k -X PUT 'https://{cpd_cluster_host}/v1/custom_cards' \
--header 'Authorization: Bearer {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"
}
Update a custom card
Update 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

For more information, see Update an existing card.

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

This command updates the title of a custom card.

curl -k -X PATCH 'https://{cpd_cluster_host}/v1/custom_cards/disk_usage_donut' \
  -H 'Accept-Language: en-US' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {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.

For more information, see Delete a custom card.
Sample command

This command deletes the os_vulnerabilities card.

curl -k -X DELETE 'https://{cpd_cluster_host}/v1/custom_cards/os_vulnerabilities' \
  -H 'Accept-Language: en-US' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {token}'
Sample response
{
    "_messageCode_": "success",
    "message": "Successfully deleted custom card"
}
Note: You can't use the Custom cards API to replace, edit, or delete existing cards that are added by Cloud Pak for Data.