Content Property Index Extraction Configuration

An extraction recipe for a single value within a content property JSON object.

An extraction recipe defines which values within your JSON content property will be added to the search index and made available to CQL queries as a field. This can allow you to track custom information and make it look like a simple field on the content object.

You can further extend the field definition by including UI support.

See the content property key documentation for a complete example.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "objectName": "attachment.type",
  "type": "string",
  "alias": "myFirstAddon_contentType",
  "uiSupport": {
    "defaultOperator": "~",
    "name": {
      "value": "Content Type",
      "i18n": "attachment.type.name"
    },
    "tooltip": {
      "value": "Content Type Tooltip",
      "i18n": "attachment.type.tooltip"
    },
    "dataUri": "/data/content-types",
    "valueType": "string"
  }
}

Properties

objectName
Type
Max length
1000
Required
Yes
Description

The objectName of the JSON data which should be indexed. The objectName is the key of a flattened JSON object with '.' as the path separator.

For instance, for JSON "{"label": {"color": "red", "text":"connect"}} the valid objectName referencing the color is label.color.

Currently, specifying indexes for JSON arrays is not supported.

type
Type
Required
Yes
Allowed values
  • number
  • NUMBER
  • string
  • STRING
  • text
  • TEXT
  • date
  • DATE
Description

The type of the referenced value.

The type can be one of the following values:

* number - The extracted number will be indexed as a double value for efficient range filtering and sorting. * text - The extracted value will be tokenized before indexing, allowing searching for particular words. * string - The entire extracted value will be indexed as a single token, without any filtering. When the extraction expression evaluates to a JSON array, each element will be indexed separately. This Enables searching for an exact value, e.g. a unique identifier. * date - Two representations are possible: either a string following the ISO 8601 datetime format, or a long value in Unix time. This enables efficient range filtering and sorting.

alias
Type
Description

A CQL field name alias for this content property. Only alphanumeric and underscore (_) characters are allowed.

By defining an alias you are exposing it to CQL and allow other macros and search features to easily use your content property in their search.

Important: Must be globally unique. Prefixing it with the name of your add-on is the best way to ensure this.

uiSupport
Type
Description

uiSupport can be used to define how your aliased field will be displayed in the CQL query builder. By defining uiSupport, your content property will appear in the CQL query builder for all macros and search features built on CQL. For example, your property will become usable in the Content By Label macro, and filterable by users on the Confluence search screen.

Note: You need to define an alias to use uiSupport.

The UI Support element allows you to define how your content property field will be presented in the CQL Builder.

When you define UI support for a field, then the CQL builder will include it in all CQL features in Confluence, including other CQL based macros.

See the content property key documentation for a complete content property example.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "defaultOperator": "~",
  "name": {
    "value": "Content Type",
    "i18n": "attachment.type.name"
  },
  "tooltip": {
    "value": "Content Type Tooltip",
    "i18n": "attachment.type.tooltip"
  },
  "dataUri": "/data/content-types",
  "valueType": "string"
}

Properties

name
Type
Required
Yes
Description

The name of this field as used by the CQL builder UI components.

Represents a string that can be resolved via a localization properties file. You can use the same i18n Property key and value in multiple places if you like, but identical keys must have identical values.

Example

1
2
3
4
{
  "value": "My text"
}
valueType
Type
Required
Yes
Allowed values
  • space
  • SPACE
  • label
  • LABEL
  • user
  • USER
  • contentid
  • CONTENTID
  • contenttype
  • CONTENTTYPE
  • date
  • DATE
  • string
  • STRING
  • number
  • NUMBER
Description

As well as providing a text field and allowing any entry, the UI support system provides a number of build in components that can enrich the user experience. These provide extra user interface components to allow setting or picking their value in an intuitive way.

The type can be one of the following values:

  • space - provides a space picker and stores the result space key as the result.
  • label - provides a label picker and stores the list of labels as the result.
  • user - provides a user picker and stores the username as the result.
  • contentId - provides a content picker and stores the content id as the result.
  • contentType - provides a content type picker.
  • date - provides a date picker
  • string - provides a free form text field
  • number - provides a free form text field

dataUri
Type
Description

If provided, the CQL builder will provide a drop down and use this url to find the list of value values. This URL should return a json array of objects describing the valid options.

1
2
3
4
5
6

 [
   {"id": "value1", "text": "First Option"},
   {"id": "value2", "text": "Second Option"}
 ]

NOTE: since the call to this URL will be made from the user's browser, you need to enable CORS headers for responses to this resource.

Setting a Access-Control-Allow-Origin header to the URL of the Atlassian Cloud instance where this add-on is installed is usually enough to satisfy the CORS requirements. This can be done by tracking the client key and its url in your /installed callback, then looking up the url when the request is made.

defaultOperator
Type
Max length
100
Description

The CQL builder will use this operator when constructing the CQL string.

tooltip
Type
Description

The tooltip of this field as used by the CQL builder UI components.

Represents a string that can be resolved via a localization properties file. You can use the same i18n Property key and value in multiple places if you like, but identical keys must have identical values.

Example

1
2
3
4
{
  "value": "My text"
}

Rate this page: