Creating custom home page cards with API
Create custom cards to display information on the console 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
- Get a list of custom cards
- Create or replace a custom card
- Edit a custom card
- Delete a custom card
You cannot use the Custom cards API to replace, edit, or delete existing cards that are added by default.
Sample custom cards
You can start with a template to create each of the custom cards that are shown in the following image. Review the template types for a description of the templates that are used.
Template types:
- The
donuttemplate illustrates an array of values as percentages in a donut chart. - The
bartemplate creates a two-dimensional bar graph. - The
big_numbertemplate highlights significant data. - The
text_listdisplays a list of text strings. - The
number_listdisplays a list of numeric values and associated text. - The
listdisplays 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.
Generate an authorization token
To use the Custom cards REST API, you must first authenticate. Use the token that you get in the response as a token in subsequent API calls.
-
Get an Identity Management (IM) access token:
curl -k -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \ -d "grant_type=password&username=<username>&password=<password>&scope=openid" \ https://<cluster_address>/idprovider/v1/auth/identitytoken<username>is your username.<password>is your password.-
<cluster_address>is the IBM Cloud Pak console route. You can get the IBM Cloud Pak console route by running the following command:oc get route -n <your-foundational-services-namespace> cp-console -o jsonpath=‘{.spec.host}’Following is a sample output:
cp-console.apps.mycluster.mydomain.comBased on the example output, your console URL would be
https://cp-console.apps.mycluster.mydomain.com.The username and password are defined in the
config.yamlfile.
-
Use the IM access token to call the Platform UI token API:
curl -k X GET 'https://<master_node_hostname>/v1/preauth/validateAuth' \ -H 'username: admin' \ -H 'iam-token: <iam-token>'<master_node_hostname>the hostname for the master node.<iam-token>is the IM token that you obtained from the response in the previous step.
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 following examples. |
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 following examples. |
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. |
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: - 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 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:
datadata\_urldescriptiondrilldown\_urlorderpermissionstemplate\_typetitle
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"
}