Version 21

    JiveDerby-JW17-Lockup.png

     

    High-Level Architecture

     

    The Jive Derby architecture was designed with a few core principles in mind, such as:

    • Spin-up from anywhere with internet connectivity and access to any Jive 9/Cloud instance.
    • Show case convergence of IoT and smart data capture to create or enhance collaboration experiences.
    • Minimal infrastructure (reduced costs) after the Jive Derby event to sustain collaboration.
    • Open-source project demonstrating Jive integration best practices using Add-ons

     

    The general flow for the integration runs as the following:

    1. Racers build their derby cars and visit the Jive Derby start gate.
    2. Racers are assigned a Racer ID
      • This ID corresponds to their Jive User ID on the hosting Jive instance
    3. Start gate assistant uses a simple UI to map users to respective lanes on the track, and starts the race.
    4. IoT sensors and other devices capture race speed information, and send racer profile information, lane assignments, race recording and speed details to Cloud Environment for further processing and orchestration.
    5. The cloud environment stores and processes the race result information and then sends API calls to Jive to create the collaboration experiences.
    6. After the event, the Jive Derby Cloud Environment can mostly be decommissioned (minus Race Photo storage, S3), allowing Jive to support the remaining collaboration experience.

     

    Now that we've walked through the high-level flow, let's break down each of the components and provide links to resources that were used to construct the solution.

    jive-derby-overview.png

     


     

    Jive Integration

     

    Overview

     

    Environment Details:

    • Node.js 6.9.x (or higher)
    • Jive SDK v 0.2.x
    • Persistence - postgres-sql
    • All Tile and App Resources are bundled into the Jive Add-On
      • jive-sdk build --apphosting="jive"

     

    Related Resources:

    jivedev-diagram.png

     

    Analytics / Data Export Service (DES)

     

    Jive Derby uses DES in a limited fashion, mainly to show how information from DES can complement existing systems/algorithms to blend awareness of activity in Jive!

     

    For more details, see: Tiles > Custom View Tile - External (Popular Races) to learn about how a make-shift "popular" algorithm based on DES was created to power a Jive Tile experience.

     

    Related Resources:

    GitHub

    Analytics_Blue.svg

     

    Apps

     

    Jive's App Framework allows developers to integrate experiences into the Jive user experience in a rich and context aware manner.  While the Jive Derby could easily extend deeper into Jive, it focuses on 2 primary scenarios in its inaugural launch.

     

    External Objects (See Figure 1)

    The Jive Derby cloud environment submits racer and race details to Jive in the form of an external object.  The external object is defined as having an app view (ext-object) which tells Jive to use the App to render the experience, in lieu of the standard location. This allows Jive to attribute additional collaboration services around the external object, such as Shares, Bookmarks, Likes, Comments and Structured Outcomes.

     

    Profile Page - Tab + NavBar (See Figure 2)

    When external objects are created, the Jive Derby cloud environment is notified by Jive via webhooks that allows Jive Derby to map races to content Jive objects.  Once mapped, the cloud environment marks each Jive external object with ExtProps metadata that is used to support this app experience.  This allows Jive to have a native API to conceptually filter Jive objects by derby, winner and racer, while also displaying additional meta-data associated with the app.

     

    Related Resources:

    GitHub

    Figure 1

    Figure 2

     

    OAuth2 Client

     

    By virtue of being a middleware service, Jive Derby is also an OAuth2 Client.  It uses an OAuth token obtained during the Activity Stream setup to query and call APIs on behalf of the person who setup the stream.  This OAuth token is also used to proxy profile information to the Local Environment through the Jive Proxy service.

    Note:  For simplicity, Jive Derby currently supports only a single OAuth token at a time.  While it is common for middleware services to store and manage multiple OAuth tokens at a time, we wanted to focus more on the high-level capabilities.  Should you have questions about supporting multiple tokens with your middleware, you might want to check out the Github4Jive project, which shows how this would work.

    Related Resources:

    GitHub

    Rest-API_Turquoise.svg

     

    Tiles

     

    Add-On Configuration

     

    When creating Add-Ons, it is possible to specify a "config_url" in the Add-On's meta.json file, which will force the installing using the configure the add-on when installed.   Typically,  this experience is used to collect System level configuration information, such as a shared OAuth token for all sub-components, license keys, etc...

     

    In the case of the Jive Derby, we dont need/want this level of elevated access, so this screen is simply an pop-up with a Save button, but it has been wired to insure that if someone wanted to drop additional details ... it would be easy.

    Note:  If you wanted to move OAuth token grant to this phase you could, you would just simply need to port code from the JiveDerby-RaceActivity tile (below) to this experience.  See Figure #2

    See Also:

    • Tiles > Activity Stream (below)

     

    Related Resources:

    GitHub

    Figure 1

    Figure 2

    Screen Shot 2017-04-04 at 2.01.36 AM.png

     

    Activity Stream

     

    An Activity Stream Tile is a popular way of bringing in external system activity into Jive in a rich and interactive manner.  When a Jive Derby race completes, the data is aggregated and posted to Jive as an External Object Activity.  An externalID field is added to the Jive Object which allows Jive Derby to map the external object to the race.  A Jive App is leveraged to customize the content presentation to reflect the Jive Race details.  This one integration types powers numerous other facets of the Jive Derby, so understanding this is key!

     

    When the activity stream is added to a place and configured, the configuration experience offers the user the ability to authorize Jive Derby to support this derby and place on their behalf.  This is an example of a delegated pattern of authorization, such that, administrators are not needed authorization and yet authorization tokens granted will not exceed the permissions of the authorizing user.  As a person who has access to administrate the Jive place's Tile page, they should have ample rights to perform any administrative function to the place, should Jive Derby require it.

     

    See Also:

    • Apps > External Objects (above)
    • REST API > Webhooks (below)

     

    Related Resources:

    GitHub

    Figure 1

    Figure 2

    Screen Shot 2017-04-04 at 2.01.36 AM.png

     

    Custom View Tile - Internal (Your Races)

     

    Custom View Tiles are a powerful way to impact the Jive user experience via a component on a Page.  This example demonstrates how Custom View Tiles can be published in Jive, such that display resources, assets AND DATA are stored in Jive.  This means that developers can create  experiences that store information entirely in Jive, that, when rendered, can stitch together external and internal resources for a dynamic and interactive experience.

    Note:  Custom View Tiles (Internal) are able to interact securely with Jive services (scoped as the current user) or remote services to mash information from Jive and third-party service for an integrated user-experience within the Tile.  This makes them inherently different from a standard Data Tile, which has a single data context for all viewers (minus the Action functionality), allowing them to personalize the experience to the view.

    Related Resources:

    GitHub

     

     

    Custom View Tiles are a powerful way to impact the Jive user experience via a component on a Page.  This example demonstrates how Custom View Tiles can be published in Jive, such that display resources and assets are stored in Jive; however, the Tile data context is pushed into Jive from an external service in a completely decoupled manner from the user browsing session.  In essence, Custom View Tiles (External) are Jive Data Tiles with a custom user experience.

    Note:  Custom View Tiles (External) are able to interact securely with Jive services (scoped as the current user) or remote services to mash information from Jive and third-party service for an integrated user-experience within the Tile.  This makes them inherently different from a standard Data Tile, which has a single data context for all viewers (minus the Action functionality), allowing them to personalize the experience to the view.

    Related Resources:

    GitHub

     

     

    Gallery Tiles are an easy way to make an instant visual impact in your community.  A Gallery Tile simply receives a list of images and supports the UX to page through each image (including Full Screen) with simple caption labels.  In our case, we are using the Gallery Tile to show a list of the most recent races (animated GIFs) so people can see what they are missing.

     

    Related Resources:

    GitHub

     

    List Tile (Top Racers)

     

    List Tiles are the bread and butter of Jive Data Tiles.  You can create a simple list of items for internal or external elements. With Jive Derby, we use the List Tile to show Jive people and instead of showing traditional Title and Company, we are padding the list with their fastest race times and number of races per racer.  This is a great way for the leaderboard to be displayed in a compact space.  There is also a link provided at the bottom "View Full Leaderboard" of the list to view the full leaderboard results, which is an example of a Tile Action link to a standard URL, in this case, a Jive document. (see: Figure 2).

     

    Related Resources:

    GitHub

    Figure 1

    Figure 2

     

    Table Tile (Race Stats)

     

    Table Tiles are popular for displaying multiple values from a specific context in an easy to read format.  All values in the Table can contain Tile Action which either link to a URL, or render a dynamic Tile Action experience for further integration capabilities.

     

    In this example, we are using the Tile Action for "Last Race" to link to a URL that holds the external race results, but we are also using the Tile Action in the footer of the Tile to launch a dynamic Tile Action experience that retrieves additional race stats and displays them in chart form.

     

    Related Resources:

    GitHub

    Figure 1

    Figure 2

     

    Simple Stream Integration

     

    Embedded into the Jive Derby is a mechanism for developers to tap into the result feed and have Jive Derby notify a custom end-point with race results information shortly after the race.  This feature was designed to give developers an interactive feed that they could use to build features like a simple stream integration, or power input into a more full featured activity based integration.

    Developers attending JiveWorld17 are encouraged to get creative and showcase their SSI integrations using during the Hackathon and breaks in the Hacker Lounge and/or create a blog post in the Jive Jive Developers space.  Talk with a Hacker Lounge assistant if you have further questions.

    How to Register Your Simple Stream Client with Jive Derby

    curl -x POST -d url={url} -d verb={verb} -d header={header} -d token={token} -d onlyLive={onlyLive} https://{HOST}/api/derby/{derbyID}/results/callback

    Note:  If an end-point fails more than 3 times, it will be removed from the list.  You will need to re-register your end-point to re-activate it.

    ParameterDescriptionValues
    HOSTrequired - Hostname will be on display in the Hacker Lounge.Ask an attendant, or comment on this document to receive the host.
    derbyIDrequired - This is the key for the derby you wish to receive updates.

    (i.e.) jw17

     

    Default: N/A

    urlrequired - This is the end-point where Jive Derby will echo results.  Must by URL Encoded!

    (i.e.) https://sandbox....../

     

    Default: N/A

    verboptional - If you want to specify a custom HTTP Verb.

    (i.e.) PUT

     

    Default: POST

    headeroptional - If you want Jive Derby to send you a custom header on each notification.

    (i.e.) X-VALIDATION-HEADER

     

    Default: X-JDERBY-TOKEN

    tokenoptional - The security value you want Jive Derby to pass in the header.

    (i.e.) any text

     

     

    Default: RANDOM GUID

    onlyLiveoptional - Filter notifications to only include Live Races (no debug)

    (true | false)

     

    Default: true

     

     

    Related Resources:

    Example Output

     

    {

      "raceID": 20043,

      "photoURL": "https://developer.jivesoftware.com/jive-derby/photos/derby/jw17/20043.gif",

      "splits": [1.025, 3.035],

      "derby": {

      "name": "JiveWorld17",

      "id": "jw17"

      },

      "timestamp": "2017-03-20T18:56:57.653Z",

      "diagnostic": false,

      "results": [{

      "totalTimeSec": 1.111,

      "racer": {

      "profileURL": "https://community.jivesoftware.com/people/ryanrutan",

      "joinDate": "10/18/2007",

      "avatarURL": "https://community.jivesoftware.com/api/core/v3/people/32109/avatar?a=13546",

      "name": "Ryan Rutan",

      "company": "Jive Software",

      "id": 32109,

      "title": "Director, Developer Evangelism & Partner Innovation",

      "region": "Americas",

      "track": "Developer Topics",

      "uri": "https://community.jivesoftware.com/api/core/v3/people/32109",

      "username": "ryanrutan"

      },

      "rank": 1,

      "lane": 1,

      "speed": 100

      }, {

      "totalTimeSec": 2.2222,

      "racer": {

      "profileURL": "https://community.jivesoftware.com/people/ryanrutan",

      "joinDate": "10/18/2007",

      "avatarURL": "https://community.jivesoftware.com/api/core/v3/people/32109/avatar?a=13546",

      "name": "Ryan Rutan",

      "company": "Jive Software",

      "id": 32109,

      "title": "Director, Developer Evangelism & Partner Innovation",

      "region": "Americas",

      "track": "Developer Topics",

      "uri": "https://community.jivesoftware.com/api/core/v3/people/32109",

      "username": "ryanrutan"

      },

      "rank": 2,

      "lane": 2,

      "speed": 50

      }],

      "measurements": [{

      "unit": "ft",

      "type": "distance",

      "value": "32",

      "label": "Distance"

      }, {

      "unit": "%",

      "type": "humidity",

      "value": 47.97,

      "label": "Humidity"

      }, {

      "unit": "F",

      "type": "temperature",

      "value": 83.86,

      "label": "Temperature"

      }, {

      "unit": "",

      "type": "uv",

      "value": 0,

      "label": "UV Index"

      }, {

      "unit": "lux",

      "type": "ambient-light",

      "value": 2.62,

      "label": "Ambient Light"

      }, {

      "unit": "",

      "type": "microphone",

      "value": 69.21,

      "label": "Sound Level"

      }, {

      "unit": "inHg",

      "type": "pressure",

      "value": 263.25,

      "label": "Pressure"

      }]

    }

     

     

    REST API

     

    The REST API is pervasive throughout Jive Derby.  Below are just some of the services that are used, and in what capacity.

     

    /contents

    • Creating / Updating the Jive Leaderboard as a Document in the Configured Jive place
    • Mapping Jive Ext Objects to Jive Derby Race via Webhooks and externalID

     

     

    /extProps

    • Marking Jive places with Derby meta-data used for later App Views and Tile Configs
    • Marking Jive ExtObjects with meta-data that can be used to assist filtering Jive content through custom app experiences.

     

     

    /webhooks

    • Used to assist with linking Jive External Objects and Race Results in Jive Derby.
    • Future plans to do additional interactions with comments and structured outcomes for formalize / augment race results.

     

    Related Resources:

    Rest-API_Turquoise.svg

     

     


     

    Cloud Environment

    The Jive Derby cloud environment was designed to work in a cloud environment, specifically Amazon AWS.

     

    That being said, Jive Derby can be run in any cloud (or private) environment, as long as the functional requirements are met!

     

    AWS EC2/ElasticBeanStalk w/AWS Certificate Manager

     

    Manages / scales the Cloud Service as it receives information from the Local Environment and renders the Jive integration experiences.

     

    Note: Cheaper alternative for this could be using NGROK for the Cloud Environment service.
    eleasticbeanstalk_square.png pict--amazon-ec2-aws-compute-and-networking---vector-stencils-library.png--diagram-flowchart-example.png

     

    AWS RDS - Postgres 9.6

     

    The persistence layer for Jive Derby is designed to operate using a traditional SQL, as opposed to document databases like Mongo.

     

    Related Resources:

    GitHub

    aws-rds.png

     

    AWS S3

     

    The primary function for S3 is to store race binary assets once the race is complete, and make them available via a web URL.

    Note:  Cheaper alternative for this could be an FTP Service into a publicly readable folder with a simple HTTP front-end to retrieve files.

    Related Resources:

    AmazonS3.png

     

    AWS IoT

     

    The primary function for AWS IoT is to aggregate all the data from the Raspberry Pi and Thunderboard into a web addressable service that would allow us to decouple access to the IoT devices from their most recent values.  The Raspberry Pi is configured to poll these sensors on a regular schedule and submit the information to an AWS IoT shadow device, such that reading from AWS IoT we have environment details within recent history.

    Note: Cheaper alternative for this could be to create your own cache service; however, AWS IoT has a lot of cool features for mass IoT device management, so if you can afford to have it as part of your architecture (or similar cloud management solutions), it may benefit you in the long run.

    Related Resources:

    aws-iot.jpg

     

    Amazon Lambda

     

    Lambda is not used as extensively as it could be in the solution; however, there is plenty of room for its use.  Currently the only real-world application it has is to service a simple Alexa powered integration to read leaderboard results (and future idea to even to do lane assignments and race starts using an Amazon Echo/dot).

     

    Related Resources:

    aws-lambda.png

     


     

    Local Environment

    The Jive Derby local environment represents all the sensors and hardware needed to collect the race details.

     

    Raspberry Pi 3 (Adafruit)

    • Running Rasbian Jessie
    • 32GB microSD Card

     

    ngrok.com

    • We use NGROK as an on-the-ground option give us reliable connectivity regardless of network.  As long as the Raspberry Pi can see the internet, we can find the Raspberry Pi to manage access.

     

    Related Resources:

    3055-06.jpg

     

    Electronic Derby Timer w/Solenoid (Derby Magic)

     

    TODO: DESCRIBE WHAT IT DOES

     

    Related Resources:

    DSCF1603b-466x296.jpg

     

    Raspberry Pi Camera Board v2 - 8 Megapixels (Adafruit)

     

    TODO: CONNECTED TO SPECIFIC RASPI PINS WITH BUILT IN PULL UP RESISTORS

    TODO: raspicam, GraphicsMagick, ImageMagick (see README file) LINK

     

    Related Resources:

    3099-04.jpg

     

    Pi Traffic Light (Amazon)

     

    Provides a physical visual queue for various status during the Derby.  Also, goes well with the concept of racing, as we use it to simulate a race tree!

     

    Related Resources:

     

     

    IR Break Beam Sensor - 5mm LEDs x 2 (Adafruit)

     

    Places alongside the track to capture race splits for various distances. (optional)

     

    Related Resources:

    2168-02.jpg

     

    Thunderboard Sense (Silicon Labs)

     

    Connect to a Thunderboard Sense, poll device for measurement updates, and then proxy those to AWS IoT.

     

    Related Resources:

    thunderboard-sense-bubbles.jpg?$Large2Column30pct$