Shapes

What is a shape?

What shapes are available?

Configurable shapes

How to configure a shape



List of roles



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.

See Configurable shapes

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:

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

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