Building a Jive Add-On - definition.json

Version 10

    The primary source of configuration data in a Jive Add-On is the definition.json. In this document, I'll explain the structure and data structures that are supported.

    Refer to Getting Started > Building a Jive Add-On for additional information about Jive Add-Ons.

     

     

     

    Overview

    The definition.json contains one top level object. This object supports a number of properties, documented below. Any property not listed here is not supported and will be ignored.

    FieldTypeRequired VersionNotes
    integrationUserIntegrationUser7c4 / 7.0This field is required for any add-on installed in Jive through the add-ons management page. In most cases it will be an empty object.
    templatesTemplateDef[]7c4 / 7.0Defines one or more templates for this add-on
    tilesTileDef[]7c4 / 7.0Defines one or more tiles for this add-on
    storageDefinitionsStorageDef[]7c4 / 7.0Defines one or more storage definitions for this add-on. must configure a storage instance after under 'storage management' tab.
    osappsAppDef[]7c4 / 7.0This installs classic Jive apps for all users on the Jive community
    jabCartridgesCartridgeDef[]7c4 / 7.0 + ExtendedAPIs pluginDefines one or more Jive Anywhere cartridges. Will only add the cartridge, to publish - needs to go to admin-console to JAB cartridge management.

     

    Tokens

    Many fields in these definition objects recognize one or more tokens. These tokens are listed below.

    i18n key

    Most text fields that are intended to be visible to Jive users support i18n keys. To be recognized as an i18n key, the value cannot contain spaces. It may contain one or more dot [.] separated identifers. Each identifier can contain upper and lower-case letters numbers and dashes [-]. The first identifier must start with a lower-case letter.

    • e.g.: my.valid.identifer, another.valid.identifer.0.With-a-number, An.invalid.identifier

     

    Filename from Add-on

    Some fields that accept a URL can recognize a simple filename. This file must be present in the data directory of the Jive Add-On package.

     

    %serviceURL%

    Most fields that expect a URL, can be prefixed with the service_url set in the meta.json. In these cases, begin your URL value with %serviceURL% and the value will be replaced when the add-on is installed.

     

     

    Object Types

     

    IntegrationUser

    FieldTypeRequired?TokensDescription
    systemAdminbooleanN default = false---Must also include "jiveServiceSignature" if this is "true".
    runAsStrategyString<Enum>NnoneOne of: "email", "userid", "id", or "uri"
    jiveServiceSignatureStringIf systemAdmin = truenone

    Used to ensure that this add-on can be granted admin access.

    Contact Mark Weitzel / Ryan Rutan for more details

     

    AbstractDef

    This is the base type for most objects in the definition.json

    FieldTypeRequired?TokensDescription
    displayNameStringYi18n keyThis is the human-readable name of this definition object.
    descriptionStringYi18n keyThis is the description of this definition object.

     

    TemplateDef

    Extends AbstractDef

    FieldTypeRequired?TokensDescription
    nameStringYnoneAn identifier unique to this template definition
    removebooleanN default = false---If this value is true, and an existing template definition exists with the specified name, it will be removed. Use this flag to remove obsolete template definitions created in older versions of this add-on. If this value is true, only the name field is required, all other fields are ignored.
    subtitleStringYi18n keyNot displayed currently
    blurbStringYi18n keyNot displayed currently
    backgroundImageURLString<URL>NnoneThe background image for the place header
    tagsString[]NnoneThe default set of tags for the place
    categoriesString[]NnoneCategories to which this template definition should be organized.
    tilesString[]Ynone

    The names of tiles that should appear in this template. see: TileDef.name These names may also reference one of a list of built-in templates (values forthcoming)

    externallyAccessiblebooleanN default = false---The social group will be externally accessible (Tied House)
    contentTypesString[]Nnone

    A list of content types that should be included in the group, if this template is used to build a group from scratch.

    thread, document, blog, poll, video, wallentry, project, task

    groupTypeStringNnone

    The type of group, if this template is used to build a group from scratch.

    OPEN (default), MEMBER_ONLY, PRIVATE, SECRET

     

    TileDef

    Extends AbstractDef

    FieldTypeRequired?TokensDescription
    nameStringYnoneAn identifier unique to this tile definition
    removebooleanN default = false---If this value is true, and an existing tile definition exists with the specified name, it will be removed. Use this flag to remove obsolete tile definitions created in older versions of this add-on. If this value is true, only the name field is required, all other fields are ignored.
    styleString<Enum>Ynoneone of: "CALENDAR", "LIST", "GAUGE", "TABLE", "GALLERY", or "ACTIVITY"
    sampleDataObjectN---Not used when style = ACTIVITY
    clientIDStringNnoneDO NOT USE!
    productNameStringNnonetodo: Should support i18n
    configString<URL>N%serviceURL%URL of an HTML file used for a synthetic app. This synthetic app is optionally passed the existing tile config object and returns a replacement config object. The structure of this config is not interpreted by Jive, and is passed intact to other synthetic app UIs.
    actionString<URL>N%serviceURL%URL of an HTML file used for a synthetic app. This synthetic app is optionally passed the action context taken from the tile's most recent data push. The structure of this config is not interpreted by Jive, and is passed intac.
    registerString<URL>N%serviceURL%URL of a publicly accessible endpoint which is called when a tile instance is created.
    unregisterString<URL>N%serviceURL%URL of a publicly accessible endpoint which is called when a tile instance is destroyed.
    dataProviderKeyString<Enum>N default = externalnoneDO NOT USE!
    stateString<Enum>N default = PUBLISHEDnoneDO NOT USE!
    iconsIconsY---Icon set for this tile.
    tagsString[]Nnone
    categoriesString[]NnoneCategories to which this tile definition should be organized.
    displayWidthString<Enum>N  default=NARROW

    Indicates on which column types this tile is available for selection and display. Value can be one of: "NARROW", "WIDE", or "ALL". (Available since Jive Cloud 8c2 / June 2014)

    i18nStringwhen i18n is usednone

    Comma separated list of i18n key wildcards, similar to @depends i18n=xxx.yyy.* in Jive UI code.

    Used to import i18n resources from the add-on that are used by this tile.

    oAuth2DependentbooleanN default = false---

     

    Icons

    FieldTypeRequired?TokensDescription
    16String<URL> | String<Filename>Y%serviceURL%, filename from add-on ( e.g. "{{filename}}.png" would be reference a file at the root of each add-on's folder (e.g. /public/tiles/{{tile_name}}/{{filename}}.png)
    48String<URL> | String<Filename>Y%serviceURL%, filename from add-on ( e.g. "{{filename}}.png" would be reference a file at the root of each add-on's folder (e.g. /public/tiles/{{tile_name}}/{{filename}}.png)
    128String<URL> | String<Filename>N%serviceURL%, filename from add-on ( e.g. "{{filename}}.png" would be reference a file at the root of each add-on's folder (e.g. /public/tiles/{{tile_name}}/{{filename}}.png)

     

    StorageDef

    Extends AbstractDef

    FieldTypeRequired?TokensDescription
    nameStringYnoneAn identifier unique to this storage definition
    removebooleanN default = false---If this value is true, and an existing storage definition exists with the specified name, it will be removed. Use this flag to remove obsolete storage definitions created in older versions of this add-on. If this value is true, only the name field is required, all other fields are ignored.
    iconsIconsY%serviceURL%, filename from add-onIcon set for this storage definition.
    configPlaceString<URL>N%serviceURL%Path to a page that configures the registration of a place.
    configInstanceString<URL>N%serviceURL%Path to a page that configures the settings of a storage instance.
    registerPlaceString<URL>Y%serviceURL%Path to an endpoint that called when connecting the Jive place with the storage container.
    userMappingOptionsString[]YnoneThe supported user-mappings for this storage definition. can be "EMAIL", "USERNAME", "CUSTOM".
    supportedResourceNamesString[]Nnonenot used at the moment.
    prefixUrlString<URL>N%serviceURL%The prefix for any URL returned in the resources of objects passed in the communication. If URLs will be relative, the will be prefixed by this value.
    resolveResourcesString<URL>N%serviceURL%not used at the moment.
    goToContainerNameStringNi18n keyThe text to show in the "go-to" links of places. If not set, will use "Go to {definition-name} Folder" text.
    goToFileNameStringNi18n keyThe text to show in the "go-to" links of files. If not set, will use "Go to {definition-name} File" text.
    healthCheckURLStringN%serviceURL%Path to an endpoint that called when viewing the "storage management" page. It will pass the JSON configuration retrieved from configInstance page. If not passed, will show an "healthy" state.
    i18nStringNnone

    Comma separated list of i18n key wildcards, similar to @depends i18n=xxx.yyy.* in Jive UI code.

    Used to import i18n resources from the add-on that is used by this storage definition.

    userFacingURLString<URL>Y%serviceURL%Url to redirect the user when click on the "integration user" on 'posted on behalf of' indications

     

    AppDef

    Extends AbstractDef

    FieldTypeRequired?TokensDescription
    nameStringYnoneA friendly string for developers to locate / identify their app. This string is not surfaced to end user
    removebooleanN default = false---If this value is true, and an existing app definition exists with the specified name, it will be removed. Use this flag to remove obsolete app definitions created in older versions of this add-on. If this value is true, only the name field is required, all other fields are ignored.
    idString<UUID>YnoneA unique identifier for this app. This value can never changed in future updates of app.
    urlString<URL>Y%serviceURL%Gadget XML URL. Its an absolute gadget xml url. Just like app installed via market, the gadget xml will include references to resource bundles and icons. Jive instance would load the app and resources from this gadget xml.
    appPathString<URL>YThe short name of the app. It is used to create user friendly url for the app.

     

    CartridgeDef

    Extends AbstractDef

    FieldTypeRequired?TokensDescription
    nameStringYnoneAn identifier unique to this cartridge definition.
    removebooleanN default = false---If this value is true, and an existing cartridge definition exists with the specified name, it will be removed. Use this flag to remove obsolete cartridge definitions created in older versions of this add-on. If this value is true, only the name field is required, all other fields are ignored.
    patternsString[]YnoneThe url patterns that this cartridge should run on.
    zipFileNameString<Filename>Yfilename from add-onThe name of the file from the 'data' folder.