Shapes
Which shapes and roles are required for a visualization to be compatible
Example for an Atlassian Jira JQL Query
What is a shape?
A shape
is a parameter you define in the metadata
of a Data Stream. See Custom Data Streams
Shapes can be used:
When writing custom data streams
When editing configurable data streams such as JQL that bring back custom columns
When using SQL Analytics tiles
The shape you assign to a column tells SquaredUp what the column contains (for example, a number, a date, a currency, a URL, etc.). Based on the shape SquaredUp decides how to display this column, for example to display a URL as a clickable link.
What shapes are available?
There are many different shapes you can use for your columns and the list of possible shapes gets expanded constantly:
Basic types, like:
boolean
,date
,number
,string
Currency types that get displayed with two decimal values and their currency symbol (for example $23,45), like:
currency
(generic currency),eur
,gbp
,usd
Data types, like:
bytes
,kilobytes
,megabytes
Time types, like:
seconds
,milliseconds
,timespan
The status type :
state
Utility types, like:
customUnit
url
(will be displayed as a link)
Tip:
Some shapes can be configured.
If a shape is configurable, you can edit how the shape displays data in SquaredUp.
Configurable shapes
If a shape is configurable, you can edit how the shape displays data in SquaredUp.
How to configure a shape
Note: Shapes are configured directly in your custom Data Stream, in the shape
parameter for metadata
. Instead of just using the shape name as a value there, use the shape name together with the configuration as shown in the following code examples.
Here are some examples of how to configure a shape:
Shape "state":
You can map the states you're getting back from your data to the states SquaredUp expects.
SquaredUp expects the following values for states to be able to show Status Blocks in the correct matching color:
success | green |
warning | yellow |
error | red |
unknown | gray |
If your data uses different values for states, you can map them to the values SquaredUp expects.
Tip: Any state value that SquaredUp doesn't recognize gets automatically set to unknown
. You can usually just leave out the unknown
state from your mapping and just specify the other three states.
Example:
"shape": ["state", {
"map": {
"success": ["yes", "succeeded"],
"warning": ["warning", "failed"],
"error": ["no", "off"],
}
}]
Shape "url":
You can give links a label to make them easier to read. If you don't give them a label, the full URL for the link will be displayed, which can take up too much space and isn't user-friendly to read.
Example for a fixed label (all links will get the same label):
"shape": ["url", { "label": "Click here" }]
Example for dynamically using content from another column as a label:
Lets say your data is a table with Jira issues. You want to use the issue number for the links to the tickets in Jira. In that case, you can use the content from the "Issue number" column as a label for the "Link to the issue" links.
//If the column name is "name":
"shape": ["url", { "label": "{{column.name}}" }]
//If the column name includes dots, like "properties.name":
"shape": ["url", { "label": "{{column.[properties.name]}}" }]
Shape "number"
You can configure how a number is displayed, for example limiting the number of decimal places:
"shape": ["number", {"decimalPlaces": 3}]
Note:SquaredUp will round up or down to get the nearest number with the correct number of decimals.
Tip: This setting works for all number shapes (number
, seconds
, kilobytes
, etc.)
Shape "customUnit":
CustomUnit is a shape that's meant to be configured. It enables you to create a shape that is displayed exactly like you need it: with a prefix, suffix, and separator.
Example:
You want to display the currency "Philippine peso" together with its symbol in this format: ₱18.4556 PHP. This means ₱ is the prefix, "." the separator for the value, and PHP the suffix.
"shape": ["customUnit", {"prefix":"₱", "suffix":"PHP", "separator":"."}]
List of roles
label | A column containing user-friendly names. Line Graphs use this role to group data into series. so each label will get its own line in the Line Graph. |
link | A column containing a link that can be used as a drilldown in Status Blocks. |
timestamp | A column containing a date to use on the X -axis of a Line Graph. |
unitLabel | A column containing user-friendly labels for data series, e.g. ‘Duration’. Line Graphs can use this role to label the Y-axis. |
value | A column containing the numeric value you want to use in your visualization. |
Which shapes and roles are required for a visualization to be compatible
Scalar
- Requires shape: number, prefers role: value
Donut
- Requires shape: number, prefers role: value
- Requires shape: string, prefers role: label
Line
- Requires shape: date, prefers role: timestamp
- Requires shape: number, prefers role: value
- Requires shape: string, prefers role: label (optional)
- Requires shape: string, prefers role: unitLabel (optional)
Bar
- Requires shape: number, prefers role: value
- Requires shape: string, prefers role: label
- Requires shape: string, prefers role: unitLabel (optional)
Blocks
- Requires shape: string, prefers role: label
- Requires shape: state
Table
- Nothing required
Example for an Atlassian Jira JQL Query
Example for a JQL query
This Data Stream returns a list of issues based on the given JQL query.
Tip: When you are using the blocks visualization for a tile that uses this Data Stream, completed issues will be shown as green, all other issues will be gray.
Which entry point do I have to select from the dropdown?
JQL query
Code example:
{
"name": "projectIssuesAll",
"dataSourceConfig": {
"jql": "project={{key}}&updatedDate>='{{timeframe.startTime}}'"
},
"rowPath": [],
"matches": {
"type.0": { "type": "equals", "value": "jira project" }
},
"metadata": [
{ "name": "key", "displayName": "Key", "shape": "string", "role": "id" },
{ "name": "fields.summary", "displayName": "Summary", "shape": "string" },
{ "name": "fields.issuetype.name", "displayName": "Type", "shape": "string" },
{ "name": "fields.priority.name", "displayName": "Priority", "shape": "string" },
{ "name": "fields.status.name", "displayName": "Status", "shape": "string" },
{ "name": "fields.status.statusCategory.name", "displayName": "Status Category", "shape": "string", "visible": false },
{ "name": "fields.resolution.name", "displayName": "Resolution", "shape": "string" },
{ "name": "fields.project.name", "displayName": "Project", "shape": "string" },
{ "name": "fields.issuetype.subtask", "displayName": "Subtask", "shape": "boolean", "visible": false },
{ "name": "fields.creator.displayName", "displayName": "Creator", "shape": "string", "visible": false },
{ "name": "fields.reporter.displayName", "displayName": "Reporter", "shape": "string" },
{ "name": "fields.created", "displayName": "Created", "shape": "date" },
{ "name": "fields.updated", "displayName": "Updated", "shape": "date" },
{ "name": "fields.statuscategorychangedate", "displayName": "Last Status Category Change", "shape": "date", "visible": false },
{ "name": "fields.resolutiondate", "displayName": "Resolution Date", "shape": "date" },
{ "name": "url", "displayName": "Link", "shape": "url" },
{ "name": "blockState", "displayName": "Block State", "shape": "state", "visible": false },
{ "name": "blockLabel", "displayName": "Block Label", "shape": "string", "role": "label", "visible": false }
]
}
For the full Atlassian Jira data source data stream reference information for a Jira JQL query see Custom Data Streams - Atlassian Jira data source
For more data source data stream code examples see Custom Data Streams