Version 40

    This document breaks down the sequence of events that occur between your service and a Jive instance. This document is intended to help you create an implementation on any platform; it is not intended as an introduction to Jive development. For a JavaScript-based overview of the Jive development platform, refer to Getting Started with the Jive Node SDK.

     

     

     

     

    Add-on Creation and Registration

     

    This section covers the add-on registration process. Verification with the global registry and OAuth-based authentication is not discussed in this section.

    registration.png

    1. Start your server. The server hosting your service must be started before registration occurs.
    2. Create add-on package. You must create an add-on package, which is a zip file with some essential metadata, and upload it to Jive. The Jive Node SDK service automatically creates this package (extension.zip) with service metadata inside of it. The add-on package contains two essential files within it: meta.json and definition.json. Refer to Getting Started > Building a Jive Add-On and Building a Jive Add-On - definition.json for detailed information about the add-on package and these two files.
      1. meta.json contains some basic metadata about the add-on package. Below is a sample meta.json file.

        {

            "package_version": "1.0",

            "id": "ac4a8747-f17a-4209-c7f6-3f69bf691919",

            "type": "client-app",

            "name": "Add-on containing tiles(s)",

            "description": "Tiles: [sampletile-list]",

            "minimum_version": "0000",

            "icon_16": "extension-16.png",

            "icon_48": "extension-48.png",

            "icon_128": "extension-128.png",

            "status": "available",

            "released_on": "2013-03-08T19:11:11.234Z",

            "register_url": "%serviceURL%/jive/oauth/register",

            "unregister_url": "%serviceURL%/jive/oauth/unregister",

            "service_url": "http://localhost:8090",

            "redirect_url": "%serviceURL%"

        }

      2. definition.json contains a schema specific to the type of add-on you are installing. Below is a sample definition.json file that installs a list tile. To see an example that includes an app definition, refer to Hosting Your Own App below.

        {

          "integrationUser": {

              "systemAdmin": false

          },

          "tiles": [

              {

                  "sampleData": {

                      "title": "My Great List",

                      "contents": [

                          {

                              "text": "Initial text to be replaced"

                          }

                      ],

                      "config": {

                          "listStyle": "contentList"

                      }

                  },

                  "displayName": "My Great List",

                  "name": "sampletile-list",

                  "description": "sampletile-list",

                  "style": "LIST",

                  "icons": {

                      "16": "https://community.jivesoftware.com/servlet/JiveServlet/showImage/102-99994-1-1023036/j.png",

                      "48": "https://community.jivesoftware.com/servlet/JiveServlet/showImage/102-99994-1-1023036/j.png",

                      "128": "https://community.jivesoftware.com/servlet/JiveServlet/showImage/102-99994-1-1023036/j.png"

                  },

                  "action": "http://localhost:8090/sampletile-list/action",

                  "id": "33697725-e1f0-4372-ae5e-d2cbeb89615f",

                  "definitionDirName": "sampletile-list",

                  "published": "2013-02-28T15:12:16.768-0800",

                  "updated": "2013-02-28T15:12:16.768-0800",

                  "config": "http://localhost:8090/sampletile-list/configure",

                  "unregister": "http://localhost:8090/unregister",

                  "register": "http://localhost:8090/registration"

              }

          ],

          "templates": [

              {

                  "name": "defaultTemplate",

                  "displayName": "Contains: [sampletile-list] ",

                  "description": "Extension UUID 00c127ff-24e9-4b02-bc8b-803ab12146da Contains: [sampletile-list] ",

                  "tiles": [

                      "sampletile-list"

                  ]

              }

          ],

          "osapps": [],

          "storageDefinitions": [],

          "jabCartridges": []

        }

      3. Additional assets might be included within this package, such as icons for the add-on. The screenshot below illustrates the contents of the package automatically created by the Jive Node SDK when you create a project:
        package-assets.png

    3. Upload package. Once the package is created, upload it to the Jive server from the Manage > Add-ons administrative option.
      install-addon.png
    4. Extract add-on information. Jive grabs the information from your JSON files (meta.json and definition.json).
    5. Register add-on. Jive registers the add-on by sending a POST to the registration URL (register_url property from within meta.json). Jive passes the following information to your service.

      PropertyDescription
      clientIdThe unique ID for your service as defined by the Jive instance.
      clientSecretThe client secret that is unique to your service.
      codeCode that can be used for authentication. Refer to Getting Started > Building a Jive Add-On for more information.
      scopeDescribes whether your service has access to the Jive API.
      jiveUrlThe URL for the Jive instance.
      jiveSignatureThe signature for that Jive instance; can be used for verification.
      jiveSignatureURLThe URL where you can verify the Jive instance. Refer to Getting Started > Building a Jive Add-On for more information.
      tenantIdThe globally unique ID for the Jive instance.
      timestampThe timestamp for this message.

      For example:

      {

          "clientId": "i5j15eikcd5u2xntgk5zu4lt93zkgx6z.i",

          "clientSecret": "7wmyigctxbopc22jo7u4xorxsn2m9r04.s",

          "code": "nki1dxrtl3r2q3kkgorwfkrmik234ppw.c",

          "scope": "uri:/api",

          "jiveUrl": "http://ws-z0-120493.jiveland.com:8080",

          "jiveSignature": "dtuW522kpoayRLFkPq6l3MOXxoKwfyNHsgGMlitr9PM=",

          "jiveSignatureURL": "https://market.apps.jivesoftware.com/appsmarket/services/rest/jive/instance/validation/29c38d1a-9c8a-4ec5-9b55-56fc44a5a402",

          "tenantId": "0ee9ae5c-4702-49eb-a716-3d46de4b10d3",

          "timestamp": "2013-07-12T15:28:46.493Z"

      }

    6. Store registration information. Your service should store all the registration information (for later use).

     

    Hosting Your Own App

     

    This section covers the sequence of events that relate to hosting your own app. There is some overlap in this sequence with the previously described add-on creation and registration since we are installing the app through the add-on mechanism.

    app hosting sequence.png

     

    1. Start your app server. The server hosting your app must be started before Jive attempts to access it.
    2. Upload your package. Once the add-on package is created, upload it to the Jive server from the Manage > Add-ons administrative option. Add-on package creation and add-on registration is described in the previous sequence (Add-on Creation and Registration).
      install-addon.png
    3. Inspect definition.json for a reference to the app.xml URL. Jive looks for the URL to your app.xml file within the "osapps" property of definition.json.

      {

        "integrationUser": {

            "systemAdmin": false

        },

        "templates": [],

        "osapps": [

            {

                "name": "My App",

                "id": "46a2e65d-98d8-51ca-ab39-d7c5dc559c93",

                "appPath": "46a2e65d98d851caab39d7c5dc559c93",

                "url": "http://my.domain.com:8090/osapp/myapp/app.xml"

            }

        ],

        "storageDefinitions": [],

        "jabCartridges": []

      }

    4. Request app.xml. Using the url specified in definition.json, Jive requests app.xml from your service. Below is the boilerplate app.xml content that automatically gets created when you build an app with the Jive Node SDK:

      <?xml version="1.0" encoding="UTF-8"?>

      <Module specificationVersion="1">

        <ModulePrefs title="My App"

                    description="Description of My App"

                    author="John Doe"

                    author_affiliation="Jive"

                    author_email="john.doe@my.company.com">

       

          <!-- Commonly used features -->

          <Require feature="dynamic-height" />

          <Require feature="jive-core-v2" />

          <Require feature="jquery-1.6" />

          <Require feature="osapi"/>

          <Require feature="settitle"/>

          <Require feature="views" />

          <Require feature="jive-core-v3" />

          <Require feature="embedded-experiences" />

          <Require feature="actions">

              <Param name="action-contributions">

                <![CDATA[

                <action id="com.jivesoftware.profile.rtc"

                          path="jive/actions/profile"

                          label="Example Profile Pop-Up"

                          url="https://developer.jivesoftware.com"

                          icon="images/icon16.png"

                          windowSpec="left=40,top=40,width=500,height=500,toolbar=1,resizable=0"/>

                ]]>

            </Param>

          </Require>

       

          <!-- Icons: 3 sizes, 16x16, 48x48, 128x128 -->

          <Link rel="Icon"      href="images/icon16.png" />

          <Link rel="MediumIcon" href="images/icon48.png" />

          <Link rel="LargeIcon"  href="images/icon128.png" />

       

        </ModulePrefs>

       

        <Content type="html" view="home,canvas" href="hello.html" preferred_height="400" />

       

      </Module>

    5. Request other app assets. Based on what is contained within your app.xml file, Jive will request other app assets from your service. It will request icons associated with the app during installation time. It will request the other assets when a user launches the app.

     

    Tile Registration and Data Push

     

    This section covers the tile registration process and the tile data push sequence.

    tile-sequence.png

    Before this sequence begins, your tile must be registered with Jive. This can occur within the definition.json that is included with an add-on package. Refer to the Add-on Creation and Registration sequence (as well as Building a Jive Add-On - definition.json) for more information.

     

    1. Add tile to a place. When a user attempts to manage a space, they can add a tile to a place.
      add-a-tile.png
    2. Configure tile (User --> Jive). The user then configures the tile.
      config-tile.png
    3. Fetch Config UI (Jive --> Service). Jive makes an HTTP GET request to the URL specified in the config property of your tile definition from definition.json and displays the response.
    4. Save place settings. Once the place is set up properly, the user saves the settings of the place. You can specify the initial data within the sampleData property of definition.json.
    5. Register tile instance. After the place settings are saved, Jive makes an HTTP POST request to the URL specified in the register URL property of your tile definition from definition.json. The body of the request contains the following information:

      PropertyDescription
      guidThe GUID for your tile instance that is globally unique.
      remoteIDThe numerical ID of your tile instance that is unique to that Jive instance.
      configConfiguration information for that tile.
      nameThe name of the tile.
      jiveUrlThe URL for the Jive instance.
      tenantIDThe globally unique ID for the Jive instance.
      pushUrlThe URL to use when pushing information to that tile instance.
      codeThe secret code to use when pushing information to the tile instance.

      For example:

      { guid: 'community:localhost%3A8080/tile:1070',

        remoteID: 1070,

        config:

        { parent: 'http://localhost:8080/api/core/v3/places/1037',

          startSequence: '55' },

        name: 'sampletile-list',

        jiveUrl: 'http://localhost:8080',

        tenantID: 'a5247fb8-1f60-4649-b59b-930475588bbf-dev',

        pushUrl: 'http://localhost:8080/api/jivelinks/v1/tiles/1070/data',

        code: 'o33xm85tfxe4n4vk4lw5gwvcjwkdcp4d.c' }

    6. Request tokens. Your service should make an HTTP POST request to the URL specified in jiveUrl with the following subfolder: "/oauth2/token". For example, using the above example, your request should go to http://localhost:8080/oauth2/token . Include a Basic authorization header with a base64-encoded version of clientId:clientSecret, which was given to you during the add-on registration sequence.
      Authorization: Basic <clientId>:<clientSecret>
      Include the code (given to you in the previous step) within the body of the request:

      client_id=i5j15eikcd5u2xntgk5zu4lt93zkgx6z.i&code=o33xm85tfxe4n4vk4lw5gwvcjwkdcp4d.c&grant_type=authorization_code

      Jive responds with token information in the body. For example:

      {
        "scope":"uri:/api/jivelinks/v1/tiles/1075",
        "token_type":"bearer",
        "expires_in":"172799",
        "refresh_token":"2deuz4keb363yb88u0isl55wddpju92eva5hz4pk.r",
        "access_token":"jdribkctbrgmvd1zyb3pzn6t4sowrr1tp7wxregi.t" }

    7. Store tokens. Your service should store the tokens.
    8. Push new tile information. When there is new information to push to Jive, perform an HTTP PUT request to the pushURL value. The header field should include your access token value.

      Authorization: Bearer jdribkctbrgmvd1zyb3pzn6t4sowrr1tp7wxregi.t

      The body of the request should follow the appropriate JSON schema for the type of tile being displayed.

      Tile TypeSchema Documentation
      List TileList Tile: Design and JSON Schema
      Table TileTable Tile: Design and JSON Schema
      Gauge TileGauge Tile: Design and JSON Schema
      Gallery TileGallery Tile: Design and JSON Schema
      Calendar TileCalendar Tile: Design and JSON Schema

      For example, this JSON snippet comes from a simple list tile:

      data: {

          "title": "My Great List",

          "contents": [

              {

                "text": "A cat",

                "icon": "http://localhost:8090/images/cat.png",

                "linkDescription": "A cat."

            },

            {

              "text": "A dog",

              "icon": "http://localhost:8090/images/dog.png",

              "linkDescription": "A dog."

            }

          ],

          "config":

          {

              "listStyle": "contentList"

          }

      }


      The Jive instance can respond with the following possible response codes:

      Response CodeDetails
      2xxThe push information in this request is valid.
      400Access token is no longer valid. Use the refresh token to acquire another access token.
      410Tile is no longer valid. You should destroy the tile instance.